CLI Reference - Velatir Documentation

Overview

The velatir command-line interface is installed on the system path by the Windows MSI and the macOS package. It communicates with the local Velatir Agent over a platform-native IPC channel:

Windows: named pipe \\.\pipe\VelatirAgent
macOS and Linux: Unix domain socket

The CLI is the same surface used by the tray icon and is the supported way to script the desktop client.

At a Glance

Command	Requires admin	Purpose
`status`	No	Show agent and host state.
`start`	Yes	Activate transparent proxy interception.
`stop`	Yes	Deactivate transparent proxy interception.
`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	Drain and respawn 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 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 API 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 agent and host. Does not require elevation.

velatir status

Output includes:

Agent version and uptime
Host version and whether it is running
Host executable path
The last update check (time and outcome)

Use --json to produce a structured result suitable for monitoring tools.

start

Activate transparent proxy interception. Requires administrator rights.

velatir start

On Windows this brings up the Wintun adapter and configures the system route. On macOS it activates the network system extension configuration. If the host is not running, it is launched first.

stop

Deactivate transparent proxy interception. Requires administrator rights.

velatir stop

The host continues to run but no longer receives traffic. This is the safe way to pause monitoring without uninstalling.

restart

Equivalent to stop followed by start. Requires administrator rights.

velatir restart

Velatir re-binds automatically when the network changes, so a restart is not normally needed after a VPN connect or disconnect. Use it as a manual fallback. See VPN compatibility.

Tray Icon

hide

Hide the Velatir system-tray icon. Requires administrator rights.

velatir hide

The icon disappears immediately — no host restart — and stays hidden across restarts. Velatir keeps running and intercepting normally; only the tray icon is affected. To hide it from the moment of install instead, use the VELATIR_HIDE_TRAY MSI property — see Enterprise deployment.

show

Show the tray icon again. The inverse of hide. Requires administrator rights.

velatir show

Update Commands

update

Check whether a newer payload is available. Does not download.

velatir update

To apply a pending update synchronously, add --apply. This drains the running host, swaps to the new payload, and relaunches. Requires administrator rights.

velatir update --apply

When the agent’s regular four-hour poll has not yet found the new version, update --apply is the way to force it.

host restart

Drain the host process. The watchdog respawns it within 30 seconds on whichever payload is currently active. Requires administrator rights.

velatir host restart

This is useful after changing configuration that requires the host to reload.

quit

Stop the agent itself. The watchdog will not respawn it. Requires administrator rights.

velatir quit

After quit, the agent only restarts at next user logon (via the scheduled task on Windows or the launch agent on macOS) or when manually restarted.

Observability Commands

events

Stream the agent’s event log. Does not require elevation.

velatir events

Events include HostExited, HostLaunched, UpdateAvailable, UpdateApplied, and proxy lifecycle transitions. Filter by event type:

velatir events --filter UpdateAvailable

logs

Tail the agent or host log. Does not require elevation.

velatir logs           # Agent log
velatir logs --host    # Host log
velatir logs -f        # Follow mode (like tail -f)

Use --host -f together to follow the host log in real time. Logs are useful when diagnosing why traces are not appearing for a specific application.

version

Show the CLI, agent, and host versions.

velatir version

health

Show the latest health of the interception stack, including the reason and remediation lever for any failing check. Does not require elevation.

velatir health
velatir health --json

The host’s health monitor re-evaluates a small set of checks every ~30 seconds and writes a snapshot this command reads. health exits 0 when the overall state is Ok and non-zero when degraded, so it works as a monitoring probe. See Health checks for what each check means.

test

Run a one-shot, end-to-end smoke test of the install. Does not require elevation.

velatir test

Sends a synthetic trace to the Velatir backend using the same configuration the host loads, and prints the HTTP exchange. Success means the whole chain is wired up: the host is running, the API key is valid, and the backend is reachable and accepting traces from this machine. It exits non-zero with a specific reason when the host isn’t running, no API key is configured, or the backend rejects or can’t be reached.

Configuration Commands

get-config

Show the effective configuration. The API key is masked. Does not require elevation.

velatir get-config

set-api-key

Update the Velatir API key. The host is restarted automatically so the new key takes effect immediately. Requires administrator rights.

velatir set-api-key --key vltr_your_api_key_here

set-ca

Provide a bring-your-own certificate authority. The CA file must be a PFX (PKCS#12) bundle. The host is restarted automatically. Requires administrator rights.

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

See Enterprise deployment for the recommended distribution pattern.

Common Recipes

Verify the install end to end

velatir status
velatir test

velatir test sends a synthetic trace and confirms the host, API key, and backend are all working. To watch live interception instead, run velatir logs --host -f and trigger an interaction in a supported AI application.

Rotate the API key

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

The host restarts automatically. Confirm with status that the masked key has changed.

Force the latest payload

velatir update --apply
velatir version

Useful in pilots when a fix has just shipped.

Re-bind after a VPN change

Velatir re-binds automatically when the network changes, so this is only needed as a manual fallback:

velatir restart

See VPN compatibility.

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 each command actually does under the hood.

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 API key

​Force the latest payload

​Re-bind after a VPN change

​Next Steps