> ## 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, 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. | | [`identity`](#identity) | No | Show the resolved directory identity. | | [`restart`](#restart) | Yes | Restart the host process. | | [`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 the host 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 host, config, update, and browser-delivery health. | | [`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. | ## 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: versions, uptime, last update check, and last config sync. Add `--json` for a structured result. ```bash theme={null} velatir status ``` ### identity Show the directory identity resolved for this device (department, office, groups, and custom attributes). See [Directory context](/desktop-app/directory-context). ```bash theme={null} velatir identity ``` ### restart Restart the host process. The agent watchdog brings it back within 30 seconds. Same effect as `velatir host restart`. ```bash theme={null} velatir restart ``` ## Tray Icon ### hide Hide the system-tray icon. It stays hidden across restarts. 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 the host process. The agent watchdog brings it 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. ```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 host, config-sync, update, and browser-delivery posture. Exits `0` when healthy and non-zero when any check fails, 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_ingest_your_api_key_here ``` ## Common Recipes ### Verify the install end to end ```bash theme={null} velatir status velatir health velatir test ``` `velatir test` confirms the client, ingest key, and backend are all working. ### Rotate the ingest key ```bash theme={null} velatir set-api-key --key vltr_ingest_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 ``` ## 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.