Skip to main content

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.

​
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

CommandRequires adminPurpose
statusNoShow agent and host state.
startYesActivate transparent proxy interception.
stopYesDeactivate transparent proxy interception.
restartYesStop then start.
updateNo / YesCheck for updates, or apply with --apply.
host restartYesDrain and respawn the host process.
quitYesStop the agent itself.
eventsNoStream agent events.
logsNoTail the agent or host log.
versionNoShow CLI, agent, and host versions.
get-configNoShow effective configuration.
set-api-keyYesUpdate the Velatir API 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 agent and host. Does not require elevation. 
velatir status
Output includes:
  • Agent uptime and version
  • Host status (running, restarting, stopped) and version
  • Transparent proxy state (active or inactive)
  • Masked API key
  • Last successful trace submission timestamp
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 the firewall rules. 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. Useful after changing network conditions, for example connecting or disconnecting a VPN. Requires administrator rights. 
velatir restart
See VPN compatibility for when a restart is necessary.

​
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

​
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 logs --host -f
Then trigger an interaction in a supported AI application and watch the host log produce a trace.

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

​
Restart cleanly after a VPN change

velatir restart
The desktop client re-resolves the upstream network interface on start. 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.