CLI

veil is a small terminal client for a Local API worker. It is useful for launching a profile, checking what is running, and killing a stuck session without writing a script.

Early tool

The CLI is at an earlier stage than the APIs it wraps. Everything documented below reflects what the shipped binary actually does, including the gaps noted in Known limitations. For production orchestration, use the REST API or the SDK.

Setup

Point it at your worker

The CLI defaults to http://localhost:3000 for the Local API and http://localhost:4000 for the cloud API. Override either one:

terminal

veil config set localApiUrl http://worker-1.internal:3000

Store your key

veil login prompts for a key and writes it to disk. The stored key is sent as X-API-Key to the Local API, so this is the worker's API_KEY, not your organization key.

terminal

veil login
# or non-interactively
veil login --api-key "$WORKER_API_KEY"

Confirm

terminal

veil config show

Current Configuration:

  SaaS API URL:  http://localhost:4000
  Local API URL: http://worker-1.internal:3000
  API Key:       ***a91f

Configuration is stored as plain JSON at ~/.veilbrowser/config.json. It contains your API key in cleartext, so treat the file as a secret and keep it out of backups that are shared.

Commands

Stores an API key for subsequent commands.

Flag	Purpose
`--api-key <key>`	Skip the prompt and save the key directly

`veil profiles`

Subcommand	Behaviour
`list`	Lists profiles from the worker (see Known limitations)
`launch <id>`	Starts a session for the given profile and prints the session id

terminal

veil profiles launch 8f3c1b20-4e1a-4f57-9c22-6d0b7c9a1f44

Session started: 2b7e1f44-9c05-4a3e-8f21-77c0a1d9e2b6

`veil sessions`

Subcommand	Behaviour
`list`	Lists sessions on the worker (see Known limitations)
`kill <id>`	Terminates a running session

Flag	Purpose
`--status <status>`	Filter `list` by `running`, `exited` or `killed`

terminal

veil sessions kill 2b7e1f44-9c05-4a3e-8f21-77c0a1d9e2b6

`veil config`

Subcommand	Behaviour
`show`	Print the current configuration, with the API key masked
`set <key> <value>`	Update one value

Valid keys are saasApiUrl, localApiUrl and apiKey.

Global flags

--help / -h prints usage, --version / -v prints the CLI version. Each command group also accepts --help on its own, for example veil sessions --help.

Known limitations

These are real defects in the current binary, not usage mistakes:

profiles list and sessions list report nothing. Both read data.profiles and data.sessions from the response, but the Local API returns paginated results under data.items. Until that is reconciled, both commands print "No profiles found." or "No sessions found." regardless of what the worker holds. Query the worker directly in the meantime:
terminal
```
curl -s http://localhost:3000/sessions -H "X-API-Key: $WORKER_API_KEY"
```
profiles create is listed in --help but not implemented. Running it prints "Unknown profiles subcommand". Create profiles from the dashboard or POST /v1/profiles instead.
--limit, --name and --os appear in help text but are not wired up.
Everything targets the Local API. Despite the saasApiUrl setting and the wording of veil login, no command talks to the cloud API today.

Next steps

SDK — typed clients for both APIs.
API reference — the endpoints these commands wrap.

On this page