CLI Reference - Velatir Documentation

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`	No	Show agent and host state.
`start`	Yes	Activate AI traffic capture.
`stop`	Yes	Deactivate AI traffic capture.
`restart`	Yes	Stop then start.
`hide`	Yes	Hide the system-tray icon.
`show`	Yes	Show the system-tray icon.
`update`	No / Yes	Check for updates, or apply with `--apply`.
`host restart`	Yes	Restart Velatir’s capture process.
`quit`	Yes	Stop the agent itself.
`events`	No	Stream agent events.
`logs`	No	Tail the agent or host log.
`health`	No	Show interception-stack health and any failing checks.
`test`	No	Send a synthetic trace to verify the install end to end.
`version`	No	Show CLI, agent, and host versions.
`get-config`	No	Show effective configuration.
`set-api-key`	Yes	Update the Velatir ingest key.
`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.

velatir status

start

Activate AI traffic capture.

velatir start

stop

Pause AI traffic capture without uninstalling. The client keeps running but stops capturing.

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.

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.

velatir hide

show

Show the tray icon again.

velatir show

Update Commands

update

Check whether a newer version is available (does not download).

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.

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.

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.

velatir quit

Observability Commands

events

Stream the client’s event log. Filter by event type with --filter.

velatir events
velatir events --filter UpdateAvailable

logs

Tail the agent or host log. Useful when diagnosing why traces are not appearing for an application.

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.

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.

velatir health
velatir health --json

test

Run a one-shot, end-to-end check of the install.

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.

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.

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 for the recommended distribution pattern.

velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password'

Common Recipes

Verify the install end to end

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

velatir set-api-key --key vltr_new_key
velatir status

Confirm with status that the masked key has changed.

Force the latest version

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.

velatir restart

Next Steps

Troubleshooting

Resolve agent-unreachable errors and other common issues.

Enterprise deployment

Drive the CLI from MDM and scripted rollouts.

How it works

Understand what the desktop client does.

FAQ

Quick answers to the questions that come up most often.

​Overview

​At a Glance

​Global Flags

​Exit Codes

​Control Commands

​status

​start

​stop

​restart

​Tray Icon

​hide

​show

​Update Commands

​update

​host restart

​quit

​Observability Commands

​events

​logs

​version

​health

​test

​Configuration Commands

​get-config

​set-api-key

​set-ca

​Common Recipes

​Verify the install end to end

​Rotate the ingest key

​Force the latest version

​Re-bind after a VPN change

​Next Steps