CLI (internal)

The veil terminal client — an internal tool, documented for the people who have it.

veil is a small terminal client for a Local API worker: launch a profile, see what is running, kill a stuck session, without writing a script.

Internal tool — not distributed

@veil/cli is a private workspace package. It is not published to npm, it is not in the container images, and there is no download — running veil requires a checkout of the monorepo, which customers do not receive. This page exists because the binary is real and the people who have it need its behaviour written down, not because it is something you can install.

Everything you can actually run is the REST API, from curl or any HTTP client.

The documentation below reflects what the shipped binary does, including the defects in Known limitations.

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. Both are from-source dev defaults, so you will always have to override the worker URL: the published worker image listens on 38923.

terminal

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

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:38923/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

API reference — the endpoints these commands wrap, callable by anyone.
Run a worker — the worker these commands point at.

CLI (internal)

On this page