Give your agent its own cloud.

Install the briq CLI, sign in with a link or an API key, and run the MCP tools from a terminal or a script.

npm install -g briq-cli
briq login
briq run postgres --sleep 2h

The CLI calls the REST API. Each command is an MCP tool with the same options: briq_exec is briq exec, briq_set_sleep is briq set-sleep. Agents use the MCP server; the CLI is for you, your scripts, git hooks and CI. It needs Node 22.6 or later.

With a link

briq login

Open this link to sign in, then pick the team and budget for the briq CLI:

  https://app.briq.cloud/connect?user_code=WDJBMJHT

Approve only if the page shows the code WDJBMJHT.

Open the link on any device, sign in, pick the team and the budget, and approve.
The CLI shows the team and budget, and saves the sign-in.

The CLI is then an agent of the team, listed on the dashboard's Agents page, where you revoke it. It stays signed in while you use it at least once every two weeks.

With an API key

briq login --key bq_live_…
cat key.txt | briq login --key
export BRIQ_API_KEY=bq_live_…     # CI, containers, agents

Create the key on the dashboard's Agents page. BRIQ_API_KEY wins over a saved sign-in.

Who am I

briq whoami

team    Acme (acme), plan pro
as      briq CLI (signed in by link)
budget  … a day, 5 briqs at once, sizes nano, small
api     https://api.briq.cloud (production)

briq logout forgets the sign-in on this machine and prints the Agents page. What it signed in with (a link's grant or a key) stays connected until you revoke it there. Run briq logout before signing in again.

Commands

Command	MCP tool	What it does
`briq catalog [name]`	`briq_catalog`	The recipes, or one with its fields and outputs
`briq run <recipe or image>`	`briq_run`	Create and start a briq. See briq run
`briq up`	`briq_up`	Bring up the stack in `briq.yaml`. See briq up
`briq list`	`briq_list`	Briqs of the team. `--stack <name>`, `--all` for destroyed ones too
`briq status <briq>`	`briq_status`	One briq
`briq exec <briq> <cmd…>`	`briq_exec`	Run a command and exit with its code. `--timeout <ms>`, `--stdin` to pipe input. Flags after the id go to the command
`briq exec <briq> --async <cmd…>`	`briq_exec`	Start a command that takes over a minute; prints its exec id
`briq exec-result <briq> <exec>`	`briq_exec_result`	Where it stands, with its output. `--wait <ms>`. Exits with its code
`briq exec-stop <briq> <exec>`	`briq_exec_stop`	Stop it
`briq logs <briq>`	`briq_logs`	Recent logs. `-n 200`, `--since <cursor>`
`briq files-put <briq> <path> [file]`	`briq_files_put`	Upload a file (1 MB at most), from `file` or piped stdin
`briq files-get <briq> <path>`	`briq_files_get`	Download a file to stdout, or `-o <file>`
`briq expose <briq> <port>`	`briq_expose`	A URL for a port. `--mode private` or `public`, `--rotate` for a new token
`briq expose <briq> <port> --protocol postgres`	`briq_expose`	A TCP endpoint over TLS. See Connect from outside
`briq fork <briq>`	`briq_fork`	Fork one briq. `--name`, `--stack`, `--sleep`, `--no-wait`
`briq fork --stack <stack>`	`briq_fork`	Fork every briq of a stack. `--into <stack>`, `--branch <branch>` (into the stack it names: `feat/login` → `feat-login`), `--sleep`, `--env <file>`, `--expose` (from outside), `--no-wait`. Exits `1` when a fork ends in `error`
`briq stop <briq>` · `briq start <briq>`	`briq_stop` · `briq_start`	Stop or start a briq. Its disk is kept
`briq destroy <briq>`	`briq_destroy`	Destroy a briq
`briq destroy --stack <stack>`	`briq_destroy` (`stack`)	Destroy every briq of a stack, by name or id. `--branch <branch>` for the stack a branch's fork made
`briq set-sleep <briq> <sleep>`	`briq_set_sleep`	When it goes to sleep: `30m`, `3h`, `7d`, `never`. `--stack` for its whole stack
`briq quota`	`briq_quota`	What the credential may still spend and run today
`briq feedback <topic> <message>`	`briq_feedback`	Write to the briq team: `bug`, `idea` or `question`
`briq mcp`		Where to add briq to an MCP client: Clients

--json on any command prints the API's response instead of the summary. Messages go to stderr, so --json output stays parseable.

briq run

A recipe and the fields it changes, or an image with its settings: the briq_run input as flags.

briq run postgres --image pgvector/pgvector:pg16 --volume-gb 10 --sleep 2h
briq run node --checkout github.com/acme/api --step 'npm ci' --cmd 'npm start' --expose private
briq run nginx:1.27 --port 80 --file /usr/share/nginx/html/index.html=index.html --expose public

Option	Field	Notes
`--image <image>`	`image`	A recipe: another tag (`postgres:17`) or a compatible image
`-e, --env <K=V…>`	`env`	Added to a recipe's env, or replacing one of its values
`--cmd <command>`	`cmd`	Run with `sh -c`. A language recipe's start command
`--port <n…>`	`ports`	An image's ports, or the port a language recipe's app listens on
`--file <path=local…>`	`files`	Written before the command starts, from a local file
`--size`, `--sleep`	`size`, `sleep`
`--volume-gb <n>`	`volume.gb`	With an image, `--volume <mount>` too
`--checkout <repo>`	`checkout.repo`	A language recipe: `github.com/owner/app`. `--ref`, `--path`
`--token <NAME>`	`checkout.token`	A private repo: the secret holding its token, its value read from `$NAME`
`--step <command…>`	`steps`	Run before it starts, in order
`-n, --name`, `-s, --stack`	`name`, `stack`
`--expose <mode>`	`expose`	`private` or `public`: a URL in the outputs
`--no-wait`	`wait: false`	Return before the briq is ready

A field no flag covers (nginx's routes, a healthcheck) goes in a stack file.

briq up

Bring the stack in briq.yaml up: create each service the stack does not have, leave the others. See Stack file.

$ briq up --secret STRIPE_KEY --env .env.local
stack shop: 3 created, 1 already there
bq_7kq2m9x1p4ab  db  postgres:16  running  …
…
14 values written to .env.local

Option	Notes
`-f, --file <path>`	The stack file. Default: `briq.yaml` in the current directory or a parent
`-s, --stack <name>`	Bring it up as this stack instead of the file's `stack`
`--secret <NAME[=value]…>`	The value of a `{ secret: NAME }` of the file. `NAME` alone reads `$NAME`. Without it, briq generates one
`--env <file>`	Write the outputs into this dotenv file, mode 600 when new
`--no-wait`	Return before the new briqs are ready

It prints an endpoint that cannot be opened yet as a warning, and exits with 1 when a briq of the stack is in error. An agent's permission prompt can allow one command: Bash(briq up:*).

Environment variables

Variable	What it sets	Default
`BRIQ_API_KEY`	The key every call uses, over the saved sign-in	none
`BRIQ_API_URL`	The API, and so the environment: `https://api.stg.briq.cloud` for staging, `http://localhost:3001` for a local stack	`https://api.briq.cloud`, or the API of the saved sign-in
`BRIQ_CONFIG_DIR`	Where the sign-in is saved	`~/.config/briq` (`$XDG_CONFIG_HOME/briq`)

The config file holds one sign-in and the API it is for, readable by you only (mode 600).

Exit codes

Code	Meaning
`0`	Done
`1`	The API refused the call, or could not be reached. The error code comes first: `not_found: …`
`2`	A wrong command, flag or argument
`3`	Not signed in, or the credential was refused (revoked, expired). Run `briq login`

briq exec and briq exec-result exit with the command's own code.

Good to know

briq login uses the device flow (RFC 8628), as agents on a server do: see Setup for agents.
Prefer piping a key to --key: a key on the command line stays in your shell history.
A 5xx error prints a request id. Quote it when you ask for help.
To fork a stack per git branch with hooks, see A database per branch.

CLI