Skip to main content

​
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

CommandRequires adminPurpose
statusNoShow agent and host state.
startYesActivate AI traffic capture.
stopYesDeactivate AI traffic capture.
restartYesStop then start.
hideYesHide the system-tray icon.
showYesShow the system-tray icon.
updateNo / YesCheck for updates, or apply with --apply.
host restartYesRestart Velatir’s capture process.
quitYesStop the agent itself.
eventsNoStream agent events.
logsNoTail the agent or host log.
healthNoShow interception-stack health and any failing checks.
testNoSend a synthetic trace to verify the install end to end.
versionNoShow CLI, agent, and host versions.
get-configNoShow effective configuration.
set-api-keyYesUpdate the Velatir ingest key.
set-caYesProvide a bring-your-own CA.

​
Global Flags

FlagEffect
--help, -hPrint usage. Also accepted as the help subcommand.
--version, -vAlias for version.
--jsonEmit JSON output where applicable. Useful for scripting.

​
Exit Codes

CodeMeaning
0Success
1Agent unreachable
2Administrator privileges required
3Operation failed
64Invalid 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.