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	No	Show agent and host state.
identity	No	Show the resolved directory identity.
restart	Yes	Restart the host process.
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 the host process.
quit	Yes	Stop the agent itself.
events	No	Stream agent events.
logs	No	Tail the agent or host log.
health	No	Show host, config, update, and browser-delivery health.
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.

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.

velatir status

identity

Show the directory identity resolved for this device (department, office, groups, and custom attributes). See Directory context.

velatir identity

restart

Restart the host process. The agent watchdog brings it back within 30 seconds. Same effect as velatir host restart.

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.

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 the host process. The agent watchdog brings it 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.

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 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.

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_ingest_your_api_key_here

Common Recipes

Verify the install end to end

velatir status
velatir health
velatir test

velatir test confirms the client, ingest key, and backend are all working.

Rotate the ingest key

velatir set-api-key --key vltr_ingest_new_key
velatir status

Confirm with status that the masked key has changed.

Force the latest version

velatir update --apply
velatir version

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.