veris
Command and flag reference.
veris is a single static binary. It runs beside your code, never inside
it, and routes outbound calls to the matching twin, so your source, hostnames and
credentials stay as they are. Where an address does move it moves through a
variable your code already reads, never through an edit:
setup’s direct tier points a vendor base URL
production already sets at the twin, and a twin the control plane serves no
hostname for — a database or another data plane — has its URL handed to your
command by veris run itself, under the variable that twin publishes. Either way
the code and the path under test are the shipped ones.
veris run --image is the container tier, setup’s usual path and the one that
needs Docker: your tests run in the image you name, and the proxy runs in its own
container next to it and owns the network the two share. Code whose every vendor
call on the tested path builds its URL from a variable production already sets
takes the direct tier instead — no image and no proxy, the sandbox’s addresses in
those same variables.
Install
curl -LsSf https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.sh | shWindows:
powershell -c "irm https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.ps1 | iex"Set VERIS_INSTALL_DIR to install elsewhere, or VERIS_PROXY_VERSION to pin one.
veris version prints what you have.
Commands
| Command | Purpose |
|---|---|
login | Pair this machine with a Veris control plane |
logout | Revoke this machine’s key and forget it |
whoami | Which key, organisation and plane a command would use |
profile | Logins, one per control plane |
services | The catalog: every twin an environment can include |
env | Named environments, chosen per folder |
up | Start a sandbox of the environment and wait for it |
status | This folder’s sandbox and its twins |
down | Delete this folder’s sandbox |
run | Run a command against a sandbox and report what it sent |
sandbox | Any sandbox, by id: get, list, delete, reset, services, data, trace, clock, exports |
snapshot | Recorded worlds: create, list, get, delete |
baseline | What every new sandbox boots: get, promote, set, clear, list |
serve | Run the proxy on its own, for a long-lived session |
check | Assert that a live proxy belongs to this run. Exit 2 if not |
doctor | Check login, plane, docker, tunnel, CA, project, environment and sandbox |
version | Print the version |
veris run
Target
| Flag | Default | Meaning |
|---|---|---|
--fresh | false | Deploy a sandbox of the environment, run, delete it after: up, run and down in one process, for CI |
--keep | false | Leave a --fresh sandbox running afterwards, as this folder’s |
--ttl <minutes> | the environment’s ttl_minutes, then the control plane’s default | How long the sandbox --fresh deploys may live if teardown never runs — --fresh deletes it when the command exits. Refused without --fresh |
--environment <id> | Deploy a sandbox for this run, delete it after. Needs --image | |
--ttl-minutes <n> | 0 | How long the sandbox --environment deploys may live if teardown never runs. Needs --image |
--env <name> | The environment in .veris/twin.yaml whose run.command and proxy settings fill in what the command line leaves out | |
--sandbox <id> | $VERIS_SANDBOX_ID | Attach to an existing sandbox, leave it running |
--api-base <url> | $VERIS_API_BASE, else https://svc.api.veris.ai | Control plane |
--api-key <key> | $VERIS_API_KEY | Never written to disk |
--refresh | false | Re-read the sandbox instead of using the cached copy |
--route <svc>=<host>[/prefix] | Override a twin’s routes. Repeatable | |
--config <file> | $VERIS_PROXY_CONFIG | Explicit config file |
--ttl and --ttl-minutes are two flags with two scopes: --ttl bounds the
sandbox --fresh deploys here, --ttl-minutes the one the proxy container
deploys for --environment.
Precedence, most explicit first: --config, --sandbox, $VERIS_PROXY_CONFIG,
$VERIS_SANDBOX_ID, then the sandbox this folder’s .veris/twin.local.yaml
points at, which veris up wrote and which is what a bare veris run routes
at. They never merge.
Container
| Flag | Default | Meaning |
|---|---|---|
--image <image> | Run the command in this image | |
-v <mount> | Bind mount. Repeatable | |
-e <VAR=val> | Environment variable. Repeatable | |
-w <dir> | Working directory inside the image | |
--cap-add <CAP> | Add a capability. ALL and SYS_ADMIN are refused. Needs --image | |
--proxy-uid <n> | 14741 | The uid the proxy uses. Your image must not run as it |
--proxy-image <image> | ghcr.io/veris-ai/veris-cli:runner | The proxy’s own image |
--keep-proxy | false | Leave the proxy container up for inspection |
Without --image, the command runs as a local child process with proxy
environment variables set. A library that ignores those variables reaches the
real vendor, silently. Pass --image for code under test.
Proxy and process
| Flag | Default | Meaning |
|---|---|---|
--listen <addr> | 127.0.0.1:8080 | The address the proxy binds. :0 picks a free port. Refused with --image, where the proxy is another container |
--log-level <level> | warn | debug, info, warn or error |
--log-format <format> | text | text or json |
--session | false | The command is an interactive session you type at, a shell: keep it in this terminal’s foreground process group and let the terminal deliver its signals, instead of isolating it and forwarding them |
Assertions
| Flag | Meaning |
|---|---|
--require-service <name>[:count] | Fail unless that twin was called. Repeatable |
--require-host <host>[:count] | Fail unless that hostname was intercepted |
--require-callback <path>[:count] | Fail unless a callback arrived. * for any path. Needs --expose |
--strict | Block unmapped hosts with 421 instead of letting them out |
--receipt <file> | Write the receipt as JSON: both ledgers and the verdict, never on stdout |
--quiet | Do not print the receipt |
Webhooks
| Flag | Meaning |
|---|---|
--expose <port> | Publish this local port at a public HTTPS URL |
--expose-host <host> | Host the port is on. Use host.docker.internal from the host |
--expose-token <token> | Named tunnel token, for a stable URL |
--expose-hostname <host> | The hostname that tunnel serves. Required with the token |
Trust
| Flag | Default | Meaning |
|---|---|---|
--patch-bundled-cas | false | Patch SDK-bundled certificate files. Needs --image. See Certificates |
--ca-dir <dir> | ~/.veris/ca | Where the certificate lives. Refused with --image |
--java-truststore <path> | A JKS truststore containing the Veris certificate. Refused with --image | |
--java-truststore-pass <pw> | changeit | Its password |
veris up
Settings come from the flag, then the environment’s entry in .veris/twin.yaml,
then the defaults.
| Flag | Meaning |
|---|---|
--env <name> | Environment name or id, the same as the positional NAME |
--ttl <minutes> | Sandbox lifetime in minutes: the config, then the control plane’s default |
--boot <source> | What the sandbox boots: bundle, baseline or snapshot. The config, then bundle. snapshot needs --snapshot, or a snapshot: in the config |
--snapshot <id or name> | Snapshot id or name. On its own it means --boot snapshot; refused beside --boot bundle or --boot baseline |
--callback-url <url> | Where the twins deliver callbacks |
--timeout <duration> | Budget for ready and routable, e.g. 300s or 5m |
--watch | Show the wait as a live panel of the sandbox and its twins, on a terminal |
--proxy | Open a shell routed at the new sandbox, and hold it until you leave |
--image <image> | With --proxy: run the session inside this image, the redirect in the kernel |
--listen <addr> | With --proxy: the address the proxy listens on. :0 picks a free port |
--expose <port> | With --proxy: publish this local port at a public URL, for callbacks |
--strict | With --proxy: block unmapped hosts instead of letting them out |
The sandbox outlives a --proxy session: veris down, or the TTL, is what ends it.
veris env create
| Flag | Meaning |
|---|---|
--services <names> | Comma-separated service names from the catalog. Refused with --from: the server has no route that changes an adopted environment’s services |
--from <id> | Adopt the existing server environment with this id instead of creating one. Refused with --services |
--ttl <minutes> | Sandbox TTL recorded in the config. Left out, the control plane’s own default applies |
--boot <source> | The source a sandbox boots from: bundle, baseline or snapshot. snapshot needs --snapshot |
--snapshot <id> | The snapshot id or name a sandbox boots, with --boot snapshot |
--data <file> | Data file to add after boot. Repeatable or comma-separated |
--command <cmd> | The test command run through the proxy, as one shell string |
--image <image> | proxy.image: run the test command in this container image, the proxy beside it |
--require-service <name>[:count] | proxy.require_service: fail a run unless this service was called |
--require-callback <path>[:count] | proxy.require_callback: fail a run unless your app received a callback on this path. Needs --expose |
--expose <port> | proxy.expose: publish this local port at a public URL, for callbacks |
--strict | proxy.strict: block unmapped hosts instead of letting them out |
--default | Make it the project’s default environment |
--force | Replace an environment of the same name in .veris/twin.yaml |
The name and the service list go to the control plane; the rest is recorded in
that environment’s entry in .veris/twin.yaml, and the proxy flags land in its
proxy: block, which fills in whatever a veris run command line leaves out. On
a terminal the name and the services are asked for; off one, pass the name and
either --services or --from.
veris sandbox clock set
Exactly one of the first three.
| Flag | Meaning |
|---|---|
--freeze-at <instant> | Hold every twin at that instant, as RFC 3339 or a bare Unix second. Freezing pauses outbound webhook delivery until --live |
--offset <duration> | Run live at real time plus this: +7d, -36h, 1w |
--live | Run at real time with no offset |
--id <id> | Sandbox id. Without it, this folder’s |
veris baseline promote
| Flag | Meaning |
|---|---|
--sandbox <id> | Sandbox id to capture. Without it, this folder’s |
--clock-restore <mode> | What a sandbox booted from the capture does with its clock: today (the default), frozen or rebase |
--keep-external | Keep third-party webhook destinations in the image, instead of scrubbing them |
--keep-source | Keep the captured sandbox, which is left frozen and scrubbed |
--timeout <duration> | Client deadline for the capture, and for the poll after a dropped answer |
up, env create, sandbox clock set and baseline promote each also take
--api-base, --profile, --json, --quiet and --yes.
Environment variables
| Variable | Purpose |
|---|---|
VERIS_API_KEY | The key every command sends, ahead of the active profile’s. veris doctor warns when it overrides one |
VERIS_PROFILE | Which login to use, when you hold more than one |
VERIS_ENV | Which environment in .veris/twin.yaml a command acts on |
VERIS_ENVIRONMENT_ID | An environment id, for when nothing else names an environment |
VERIS_SANDBOX_ID | Which sandbox to attach to. Also set into whatever run launches |
VERIS_API_BASE | Control plane. Defaults to https://svc.api.veris.ai |
VERIS_PROXY_CONFIG | Path to a config file |
VERIS_TUNNEL_TOKEN | Named tunnel token: the default for --expose-token |
VERIS_SYSTEM_CA_BUNDLE | The file to read the system trust roots from, when they are not at one of the usual paths |
VERIS_PUBLIC_URL | Given to your workload when --expose is used |
Driven by hand rather than by veris run --image — from a compose file, or a CI
job that wires the containers itself — the runner image reads its own:
VERIS_STRICT, VERIS_TTL_MINUTES, VERIS_EXPOSE, VERIS_TUNNEL_HOSTNAME,
VERIS_PROXY_UID and VERIS_LOG_LEVEL among them, listed in
Environment variables.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Usage or configuration error |
2 | check failed: no proxy, not ours, or a different run |
3 | The run did not call a service it was required to call |
4 | The outcome is indeterminate |
| other | Whatever your command exited with |