# CLI URL: https://briq.cloud/docs/cli > Install the briq CLI, sign in with a link or an API key, and run the MCP tools from a terminal or a script. ```bash npm install -g briq-cli briq login briq run postgres --sleep 2h ``` The CLI calls the [REST API](https://briq.cloud/docs/api/overview). Each command is an [MCP tool](https://briq.cloud/docs/mcp/tools) 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. ## Sign in ### With a link ```bash briq login ``` ```text 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. ``` 1. Open the link on any device, sign in, pick the team and the [budget](https://briq.cloud/docs/concepts/keys-and-policy), and approve. 2. 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 ```bash 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 ```bash briq whoami ``` ```text 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](https://briq.cloud/cookbook), or one with its fields and outputs | | `briq run ` | `briq_run` | Create and start a briq. See [briq run](#briq-run) | | `briq up` | `briq_up` | Bring up the stack in `briq.yaml`. See [briq up](#briq-up) | | `briq list` | `briq_list` | Briqs of the team. `--stack `, `--all` for destroyed ones too | | `briq status ` | `briq_status` | One briq | | `briq exec ` | `briq_exec` | Run a command and exit with its code. `--timeout `, `--stdin` to pipe input. Flags after the id go to the command | | `briq exec --async ` | `briq_exec` | Start a command that takes over a minute; prints its exec id | | `briq exec-result ` | `briq_exec_result` | Where it stands, with its output. `--wait `. Exits with its code | | `briq exec-stop ` | `briq_exec_stop` | Stop it | | `briq logs ` | `briq_logs` | Recent logs. `-n 200`, `--since ` | | `briq files-put [file]` | `briq_files_put` | Upload a file (1 MB at most), from `file` or piped stdin | | `briq files-get ` | `briq_files_get` | Download a file to stdout, or `-o ` | | `briq expose ` | `briq_expose` | A URL for a port. `--mode private` or `public`, `--rotate` for a new token | | `briq expose --protocol postgres` | `briq_expose` | A TCP endpoint over TLS. See [Connect from outside](https://briq.cloud/docs/guides/connect-to-a-database-from-outside) | | `briq fork ` | `briq_fork` | [Fork](https://briq.cloud/docs/concepts/fork) one briq. `--name`, `--stack`, `--sleep`, `--no-wait` | | `briq fork --stack ` | `briq_fork` | Fork every briq of a stack. `--into `, `--branch ` (into the stack it names: `feat/login` → `feat-login`), `--sleep`, `--env `, `--expose` ([from outside](https://briq.cloud/docs/concepts/fork#reach-a-fork-from-outside)), `--no-wait`. Exits `1` when a fork ends in `error` | | `briq stop ` · `briq start ` | `briq_stop` · `briq_start` | Stop or start a briq. Its disk is kept | | `briq destroy ` | `briq_destroy` | Destroy a briq | | `briq destroy --stack ` | `briq_destroy` (`stack`) | Destroy every briq of a stack, by name or id. `--branch ` for the stack a branch's fork made | | `briq set-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 ` | `briq_feedback` | Write to the briq team: `bug`, `idea` or `question` | | `briq mcp` | | Where to add briq to an MCP client: [Clients](https://briq.cloud/docs/setup/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](https://briq.cloud/docs/mcp/tools#briq_run) input as flags. ```bash 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` | A recipe: another tag (`postgres:17`) or a compatible image | | `-e, --env ` | `env` | Added to a recipe's env, or replacing one of its values | | `--cmd ` | `cmd` | Run with `sh -c`. A language recipe's start command | | `--port ` | `ports` | An image's ports, or the port a language recipe's app listens on | | `--file ` | `files` | Written before the command starts, from a local file | | `--size`, `--sleep` | `size`, `sleep` | | | `--volume-gb ` | `volume.gb` | With an image, `--volume ` too | | `--checkout ` | `checkout.repo` | A language recipe: `github.com/owner/app`. `--ref`, `--path` | | `--token ` | `checkout.token` | A private repo: the secret holding its token, its value read from `$NAME` | | `--step ` | `steps` | Run before it starts, in order | | `-n, --name`, `-s, --stack` | `name`, `stack` | | | `--expose ` | `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](https://briq.cloud/docs/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](https://briq.cloud/docs/stack-file). ```text $ 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 ` | The stack file. Default: `briq.yaml` in the current directory or a parent | | `-s, --stack ` | Bring it up as this stack instead of the file's `stack` | | `--secret ` | The value of a `{ secret: NAME }` of the file. `NAME` alone reads `$NAME`. Without it, briq generates one | | `--env ` | 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](https://briq.cloud/docs/setup/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](https://briq.cloud/docs/guides/database-per-branch).