CLI reference

The brig CLI is the canonical way to deploy and operate workloads. This page is the complete command surface; the concept pages it links to explain the “why”.

Install

# macOS
brew install brig/tap/brig

# Linux
curl -fsSL https://get.brig.run/cli | sh

Authenticate

brig login                       # opens the browser to authorize this machine
brig login --profile staging     # named profile for a second workspace
brig --profile staging ps        # use a profile for one command

Credentials persist in ~/.brig/config.json. See Access & tokens for profiles, precedence, and non-interactive login.

Command index

Group	Commands
Workloads	`deploy` · `ps` · `inspect` · `status` · `logs` · `scale` · `rollback` · `delete` · `exec` · `shell`
Nodes	`nodes` · `node add` · `node provision` · `node labels`
Networking	`domain …` · `mesh …`
Storage	`volume …` · `snapshot …`
Secrets	`secret …`
Access	`login` · `logout` · `whoami` · `use` · `profiles` · `token …` · `audit verify` · `tenant ca`

Workloads

brig deploy <file.toml>          # create or update a workload
brig deploy <file.toml> --watch  # block until replicas are running
brig ps                          # list workloads + replica counts (all envs)
brig inspect <name>              # one workload: every replica + recent events
brig status                      # one-screen fleet health (nodes + workloads)
brig logs <name>                 # stream logs
brig scale <name>=<n>            # set replica count (no version bump)
brig rollback <name>             # revert to the previous version
brig delete <name>               # tear down (--force to skip the prompt)
brig exec <name> -- <cmd>        # one-shot command in a replica (no tty)
brig shell <name>                # interactive shell in a replica

Common flags:

--env <name|path> — target an environment. A bare name resolves to .env.<name>; a path is used as-is. Single-workload commands default to production; brig ps lists all envs.
deploy: --watch, --timeout 5m, and the local-image flags --image, --workload, --node user@host (repeatable), -i/--identity, --concurrency.
logs: -f/--follow, --tail 100, --replica 0, --since 5m, --grep <s>.
exec / shell: --replica <n>.

See Workloads for the deploy/rollout model and deploy --image for registry-less pushes.

Nodes

brig nodes                       # list nodes: health, capacity, heartbeat
brig node add user@host …        # bootstrap existing server(s) over SSH
brig node provision --provider … # create + join a fresh cloud VM
brig node labels <node-id> [labels…]   # read or replace a node's labels (PUT)

Full flag tables in Nodes. Fleet health, including cordoned and dead nodes, shows in brig status.

Custom domains

brig domain add <host> <workload>   # --env, --challenge http-01|dns-01|byo
brig domain verify <host>           # check the TXT proof, promote toward live
brig domain list                    # --env to filter
brig domain show <host>             # status, challenge, verified_at, last error
brig domain remove <host>           # --force to skip the prompt

See Custom domains for the DNS records and status lifecycle.

Mesh

brig mesh check                  # cp probes every node's proxy (non-zero exit if any fail)
brig mesh endpoints <workload>   # live placements + identities
brig mesh routes                 # dump a local proxy's routing table (--addr)
brig mesh ping <host:port>       # dial with the local workload identity (mTLS)
brig mesh server                 # tiny mTLS echo server (--addr, --identity-dir)

See Networking.

Volumes

brig volume list                 # cloud volumes: class, size, AZ, state, node
brig volume inspect <volume-id>
brig volume delete <volume-id>   # only when unbound or in error

Local volumes aren’t tracked individually. See Volumes.

Snapshots

brig snapshot create <workload>           # --volume <name>, --destination <name>
brig snapshot list                        # --workload <name>
brig snapshot inspect <snap_id>
brig snapshot restore <snap_id>           # --workload / --volume to redirect
brig snapshot delete <snap_id>

brig snapshot schedule create <workload> --daily --keep 7 --destination prod
brig snapshot schedule list
brig snapshot schedule delete <sch_id>

brig snapshot destination add <name> --bucket … --access-key-id … \
  --secret-access-key-from-env <VAR> [--endpoint …] [--region …] [--default]
brig snapshot destination list
brig snapshot destination get <name>
brig snapshot destination test <name>
brig snapshot destination set-default <name>
brig snapshot destination remove <name>

schedule create takes --interval <seconds> (≥60), or the shorthands --hourly / --daily, plus --keep (default 7). Destination secrets are passed out-of-band — --secret-access-key-from-env|-file|-stdin, never on argv. See Snapshots and Snapshot destinations.

Secrets

brig secret create <name> --from-file <path>   # or --from-env <VAR> / --from-stdin
brig secret list                               # names + updated-at only
brig secret delete <name>

The value never goes on argv. Reference secrets from a workload’s secrets = […]. See Secrets.

Access & tokens

brig whoami                      # active profile, cp URL, token status
brig use <profile>               # switch profiles
brig profiles                    # list (rm to remove)
brig logout

brig token create <api|node-join|proxy> --label … --ttl <s> [--scope …]
brig token list <api|node>
brig token revoke <api|node> <id>

brig audit verify                # verify the hash-chained audit log
brig tenant ca                   # print the tenant's mesh root CA (PEM)

See Access & tokens.

Configuration

The CLI reads, in precedence order:

BRIG_PROFILE — selects a named profile from the config file.
BRIG_CP_URL / BRIG_API_TOKEN — per-call overrides (CI escape hatch; not needed in normal use).
The active profile in ~/.brig/config.json (written by brig login).

Workload TOML grammar

The complete spec consumed by brig deploy. See Workloads for worked examples.

Top level

Field	Type	Required	Notes
`name`	string	yes	1–63 chars, `[a-z0-9-]`, no leading/trailing `-`.
`image`	string	yes	OCI ref, or local tag when `[deploy] source="local"`.
`instances`	int	yes	1–100. Must sit within `[autoscale]` band if present.
`cpu`	string	no	`"500m"` or `"1.5"` (cores).
`memory`	string	no	`"512Mi"`, `"1Gi"`, or raw MiB `"1024"`. Binary units only.
`command`	string	no	Override the image `CMD`.
`ports`	[]string	no	`"80"`, `"80:host.example.com"`, `"80/udp"`.
`volumes`	[]string	no	Compact local volumes: `["/data"]`.
`env`	map	no	POSIX-shaped keys.
`secrets`	[]string	no	Workspace secret names → injected env vars.
`allow_from`	[]string	no	Ingress allowlist (workload names). Empty = open.
`allow_to`	[]string	no	Egress allowlist (workload names).
`public`	bool	no	Default `true` → managed `*.brig.run` URL + TLS.

`[[volume]]`

Field	Type	Notes
`mount`	string	Required. Absolute path, no `..`.
`class`	string	`"local"` (default) or `"ebs"`.
`size_gib`	int	Required for `ebs` (1–16384); forbidden for `local`.
`snapshot_every`	string	Go duration, min `1h`. Pairs with `snapshot_keep`.
`snapshot_keep`	int	1–365. Pairs with `snapshot_every`.
`snapshot_destination`	string	Workspace destination name; omit = default.

`[placement]`

Field	Type	Notes
`node`	string	Pin all replicas to one node id.
`requires_labels`	[]string	Schedule only on nodes carrying all these labels.
`together`	bool	Co-locate all replicas on one node.
`same_node_only`	bool	Refuse cross-node inbound mesh calls (proxy 403).

`[autoscale]`

Field	Type	Notes
`min`	int	Enable when `min > 0`. 1–100.
`max`	int	≥ `min`. 1–100.
`cpu_target`	float	0–1, default `0.70`.
`scale_up_after`	string	Duration, default `1m`.
`scale_down_after`	string	Duration, default `5m`.

`[routing]`

Field	Type	Notes
`sticky_by_header`	string	HTTP header to hash for replica stickiness.

`[deploy]`

Field	Type	Notes
`source`	string	`"registry"` (default) or `"local"` (push local image over SSH to `--node`s).