> ## Documentation Index > Fetch the complete documentation index at: https://docs.velatir.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Control the Velatir desktop client from the command line: status, start and stop, updates, logs, and configuration ## Overview The `velatir` command is installed on the system path by the Windows MSI and the macOS package. It is the supported way to control and script the desktop client. ## At a Glance | Command | Requires admin | Purpose | | ------------------------------- | -------------- | -------------------------------------------------------- | | [`status`](#status) | No | Show agent and host state. | | [`start`](#start) | Yes | Activate AI traffic capture. | | [`stop`](#stop) | Yes | Deactivate AI traffic capture. | | [`restart`](#restart) | Yes | Stop then start. | | [`hide`](#hide) | Yes | Hide the system-tray icon. | | [`show`](#show) | Yes | Show the system-tray icon. | | [`update`](#update) | No / Yes | Check for updates, or apply with `--apply`. | | [`host restart`](#host-restart) | Yes | Restart Velatir's capture process. | | [`quit`](#quit) | Yes | Stop the agent itself. | | [`events`](#events) | No | Stream agent events. | | [`logs`](#logs) | No | Tail the agent or host log. | | [`health`](#health) | No | Show interception-stack health and any failing checks. | | [`test`](#test) | No | Send a synthetic trace to verify the install end to end. | | [`version`](#version) | No | Show CLI, agent, and host versions. | | [`get-config`](#get-config) | No | Show effective configuration. | | [`set-api-key`](#set-api-key) | Yes | Update the Velatir ingest key. | | [`set-ca`](#set-ca) | Yes | Provide a bring-your-own CA. | ## Global Flags | Flag | Effect | | ----------------- | -------------------------------------------------------- | | `--help`, `-h` | Print usage. Also accepted as the `help` subcommand. | | `--version`, `-v` | Alias for `version`. | | `--json` | Emit JSON output where applicable. Useful for scripting. | ## Exit Codes | Code | Meaning | | ---- | --------------------------------- | | `0` | Success | | `1` | Agent unreachable | | `2` | Administrator privileges required | | `3` | Operation failed | | `64` | Invalid usage | ## Control Commands ### status Show the current state of the desktop client: version, uptime, whether capture is running, and the last update check. Add `--json` for a structured result. ```bash theme={null} velatir status ``` ### start Activate AI traffic capture. ```bash theme={null} velatir start ``` ### stop Pause AI traffic capture without uninstalling. The client keeps running but stops capturing. ```bash theme={null} velatir stop ``` ### restart Stop then start. Velatir re-binds on its own when the network changes, so a restart is only a manual fallback. See [VPN compatibility](/desktop-app/vpn-compatibility). ```bash theme={null} velatir restart ``` ## Tray Icon ### hide Hide the system-tray icon. It stays hidden across restarts; capture continues normally. To hide it from install, use the `VELATIR_HIDE_TRAY` MSI property; see [Enterprise deployment](/desktop-app/enterprise-deployment#msi-properties-windows). ```bash theme={null} velatir hide ``` ### show Show the tray icon again. ```bash theme={null} velatir show ``` ## Update Commands ### update Check whether a newer version is available (does not download). ```bash theme={null} velatir update ``` Add `--apply` to install and relaunch the new version immediately. Use this to force an update before the regular poll picks it up. ```bash theme={null} velatir update --apply ``` ### host restart Restart Velatir's capture process. It comes back within 30 seconds. Useful after a configuration change that needs a reload. ```bash theme={null} velatir host restart ``` ### quit Stop the desktop client. It will not restart on its own; it stays stopped until its service starts again (next boot, or `sc start VelatirAgent` on Windows) or you launch it manually. ```bash theme={null} velatir quit ``` ## Observability Commands ### events Stream the client's event log. Filter by event type with `--filter`. ```bash theme={null} velatir events velatir events --filter UpdateAvailable ``` ### logs Tail the agent or host log. Useful when diagnosing why traces are not appearing for an application. ```bash theme={null} velatir logs # Agent log velatir logs --host # Host log velatir logs -f # Follow mode (like tail -f) ``` ### version Show the CLI, agent, and host versions. ```bash theme={null} velatir version ``` ### health Show current health and the reason and fix for any failing check. Exits `0` when healthy and non-zero when degraded, so it works as a monitoring probe. See [Health checks](/desktop-app/health-checks). ```bash theme={null} velatir health velatir health --json ``` ### test Run a one-shot, end-to-end check of the install. ```bash theme={null} velatir test ``` Sends a synthetic trace and prints the result. Success confirms the whole chain works: the client is running, the ingest key is valid, and the backend is reachable. It exits non-zero with a reason when something is wrong. ## Configuration Commands ### get-config Show the effective configuration. The ingest key is masked. ```bash theme={null} velatir get-config ``` ### set-api-key Update the Velatir ingest key. Velatir restarts so the new key takes effect immediately; pass `--no-restart` to skip the restart. ```bash theme={null} velatir set-api-key --key vltr_your_api_key_here ``` ### set-ca Provide a bring-your-own certificate authority. The file must be a PFX (PKCS#12) bundle. Velatir restarts so it takes effect immediately; pass `--no-restart` to skip the restart. See [Enterprise deployment](/desktop-app/enterprise-deployment) for the recommended distribution pattern. ```bash theme={null} velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password' ``` ## Common Recipes ### Verify the install end to end ```bash theme={null} velatir status velatir test ``` `velatir test` confirms the client, ingest key, and backend are all working. To watch live capture instead, run `velatir logs --host -f` and trigger an interaction in a supported AI application. ### Rotate the ingest key ```bash theme={null} velatir set-api-key --key vltr_new_key velatir status ``` Confirm with `status` that the masked key has changed. ### Force the latest version ```bash theme={null} velatir update --apply velatir version ``` ### Re-bind after a VPN change Only needed as a manual fallback; Velatir re-binds on its own when the network changes. See [VPN compatibility](/desktop-app/vpn-compatibility). ```bash theme={null} velatir restart ``` ## Next Steps Resolve agent-unreachable errors and other common issues. Drive the CLI from MDM and scripted rollouts. Understand what the desktop client does. Quick answers to the questions that come up most often.