# CLI

> Every stagd command. The CLI talks to the same API as the dashboard, as the signed-in person.

## Global options

| Option | Environment | Meaning |
|---|---|---|
| `--api-url` | `STAGD_API_URL` | The Stagd API to talk to |
| `--token` | `STAGD_TOKEN` | A session token; overrides the one stored by `stagd login` |
| `--json` | | Print JSON instead of tables |

## Signing in

| Command | |
|---|---|
| `stagd login` | Sign in through your browser (device login). `--no-browser` prints the link instead |
| `stagd logout` | Sign out and forget the stored token. `--all` signs out every other browser and CLI too |
| `stagd whoami` | Who you're signed in as, and your org |
| `stagd auth sessions` | Where you're signed in: each browser and CLI, how it signed in, when it was last used and when it expires; this one is marked |
| `stagd auth revoke <id>` | Sign one session out, by its id from `stagd auth sessions`. `--others` signs out all but this one |

## Orgs

| Command | |
|---|---|
| `stagd orgs create <slug> --name <name>` | Create an org and switch to it |
| `stagd orgs list` | The orgs you belong to; `*` marks the current one |
| `stagd orgs rename --name <name>` | Change the current org's name (admins); its slug stays |
| `stagd orgs switch <slug>` | Act in another org |
| `stagd orgs members` | The people in the current org |
| `stagd activity` | Who changed what in the current org, newest first: secrets (names, never values), seeds, compute, integrations, repositories, GitHub, members and invites. `--limit` (50) or `--all`; `--area` for one area, `--actor` for one person by email |

## GitHub

| Command | |
|---|---|
| `stagd github connect` | Install the Stagd GitHub App and link it to your org |
| `stagd connections list` | Connected code host accounts |
| `stagd connections delete <id>` | Disconnect one. `--yes` skips the prompt |
| `stagd repos list` | Repositories your org can preview, and whether previews are on. `--connection <id>` for one account, `--all` for hidden ones too, `--limit` for the first so many by name |
| `stagd repos enable <owner/name>` | Turn previews on for a repository; Stagd then reads its compose file |
| `stagd repos disable <owner/name>` | Turn previews off and tear down the repository's running previews |

## Compute

| Command | |
|---|---|
| `stagd compute providers` | Kinds of compute you can connect, with what each can do |
| `stagd compute connect <provider>` | Connect an account. `--name`, and `--value key=value` (or `key=@-` for stdin) for scripts |
| `stagd compute list` | Your compute connections; `*` marks the default |
| `stagd compute test <name>` | Check a connection's credentials again |
| `stagd compute update <name>` | Change a connection's settings, or give it a new secret: `--value key=value` |
| `stagd compute install <name>` | Kubernetes: print the cluster's install for kubectl: `stagd compute install <name> \| kubectl apply -f -`. Run again, it updates the cluster and a connected relay keeps its token; `--new-token` gives it a new one, cutting off the old (`--yes` when it can't ask). `--wait` waits for the relay to connect. A Docker host, on the host itself: `--run` runs the relay with a new token; `--print` prints the `docker` commands instead |
| `stagd compute uninstall kubernetes` | Print what removes Stagd from a Kubernetes cluster, without tokens, for kubectl: `stagd compute uninstall kubernetes \| kubectl delete --ignore-not-found -f -`. Run it after deleting the connection |
| `stagd compute default <name>` | Run new previews on this connection |
| `stagd compute delete <name>` | Forget a connection and its credentials. `--yes` skips the prompt |

## Seeds

The data your previews' databases start with: dumps in a storage integration (Azure Blob Storage or S3), named for `stagd.yaml`'s `seed`.

| Command | |
|---|---|
| `stagd seeds list` | Your org's seeds, and the file each finds now |
| `stagd seeds add <name> --from <integration> --path <path>` | Name a dump as a seed. A pattern such as `dumps/*.dump` is the newest file it matches at each deploy, and a path ending in `/` the newest file under it (leaving out files without an extension, like `latest`). Stagd looks for the file before it saves |
| `stagd seeds find <path> --from <integration>` | The file a path finds, without saving anything |
| `stagd seeds change <name>` | Point a seed at another `--path` or `--from` integration |
| `stagd seeds remove <name>` | Forget a seed; its file stays in your storage. `--yes` skips the prompt |

## Your app

| Command | |
|---|---|
| `stagd setup` | The steps to your org's first live preview, as Home shows them: what's done, the next step with its link, and the admins for the steps only they can do |
| `stagd init [dir]` | Write a `stagd.yaml` to start from, made from the checkout's compose file: the URLs previews get, and the settings most repositories want next, commented out. Leaves a `stagd.yaml` that's there alone |
| `stagd validate [dir]` | Check `stagd.yaml` ([reference](https://stagd.dev/docs/reference/stagd-yaml.md)) and the compose file in a checkout as previews would read them. Exits non-zero when something needs fixing |

## Previews

| Command | |
|---|---|
| `stagd preview create --repo <owner/name> --pr <n>` | Start a preview of a pull request, or update it to a new commit. Use `--branch <name>` for a branch, `--sha` to pin a commit |
| `stagd ui` | The org's previews in the terminal, laid out like k9s: a table by status, refreshed every 2 seconds. `enter` describes one (its services, URLs and why it failed), `l` follows its logs, `o` opens it, `p` its pull request, `w` wakes it, `ctrl-d` destroys it after you confirm. `/` filters, `:` takes a command (`:previews`, `:logs`, `:q`), `esc` goes back. `--demo` shows made-up previews |
| `stagd preview list` | Your org's previews. `--repo` for one repository, `--all` to include torn-down ones, `--limit` for the newest so many (default 50, at most 5000), a page at a time |
| `stagd preview get <id>` | One preview |
| `stagd preview watch <id>` | Follow a preview until it's live, asleep, failed or torn down |
| `stagd preview wake <id>` | Start a sleeping preview again |
| `stagd preview destroy <id>` | Tear a preview down now |
| `stagd preview mail <id>` | The mail a preview captured (`services: { mail: {} }` in `stagd.yaml`), newest first and numbered. `--to` (To, Cc or Bcc), `--from` and `--subject` pick some, each by part of the text; `--limit` caps the list (default 50) |
| `stagd preview mail <id> <n>` | One message, by its number in the list or its id: its text, attachments, links and any template text it left unfilled (`{{name}}`, `undefined`). `--html` prints its HTML instead |
| `stagd preview mail <id> --clear` | Delete everything the preview captured |
| `stagd preview testers <id>` | The users `stagd.yaml` names for signing in to the preview (`testers`), and how each signs in |
| `stagd preview testers <id> --check [tester…]` | Sign in to the live preview as each tester, or those named, and print how each step went; exits non-zero when one doesn't work. `--screenshots <dir>` keeps the page where a sign-in stopped |
| `stagd preview texts <id>` | The text messages a preview's app sent (`services: { sms: {} }`), newest first. `--to` (a number, by its digits) and `--body` pick some; `--limit` caps the list (default 50) |
| `stagd preview logs <id>` | What the preview's services wrote to stdout and stderr, the latest 500 lines, oldest first: each with its time (UTC), service and level, ready to pipe or paste. `--service` (`-s`, repeatable) picks services, `--since 10m` (or a time) and `--lines` (`-n`) how far back, `--errors` only errors; `--follow` (`-f`) keeps printing new lines. `--build` prints the end of each service's build output instead. In a terminal the lines are in color (each service its own, errors red); piped, with `--json` or with `NO_COLOR` set they're plain |
| `stagd preview traces <id> [trace id]` | The traces the preview's services sent (`services: { otel: {} }` in `stagd.yaml`), newest first, from the last 15 minutes. `--service`, `--errors`, `--slower-than 500ms`, `--since` and `--limit` pick some. With a trace id, its spans as a waterfall, each under the span that called it, with when it started and how long it took; `--attributes` adds each span's attributes and events |
| `stagd preview usage <id>` | Each service's CPU and memory now, its average CPU and peak memory over `--window` (default 1h, up to 24h), its restarts and how long it has run, as the Services tab has them. `--json` for every point |
| `stagd preview policy` | Who may open previews, how their URLs look, and how long they run. `--access org\|public`, `--public-ingress <name>` (repeatable), `--unguessable-urls`, `--sleep-after 2h` (45m to 24h), `--expire-after 36h` (1h to 48h; `default` for Stagd's), `--repo` for one repository, `--reset` to drop its override |

`create` and `wake` follow the preview until it's live and exit non-zero if it fails, so a CI job can wait on them. Pass `--no-wait` to return at once.

Both `mail` and `texts` can wait for what a step sends:

| Option | |
|---|---|
| `--wait` | Wait for the next matching message and print it; exit non-zero if none arrives before `--timeout` (default 2m) |
| `--none` | Wait out `--timeout` and exit non-zero if a matching message arrives: a check that a step sent nothing |
| `--cursor` | Print where the inbox stands now, and nothing else |
| `--after <cursor>` | Count only what arrived after the cursor. Without it, `--wait` and `--none` start from when they're run |

```sh
after=$(stagd preview mail <id> --cursor)
# ...the step that sends it...
stagd preview mail <id> --wait --after "$after" --to bob@example.com
```

For a script, add `--json` (a global option) to any of these: the list, a message, or what `--wait` printed, with every field the API has, links and attachments included:

```sh
stagd preview mail <id> --wait --after "$after" --to bob@example.com --json | jq -r '.links[0]'
```

## Coding agents

| Command | |
|---|---|
| `stagd mcp` | Stagd's tools for coding agents, as an MCP server over stdio, signed in as you. See [Coding agents](https://stagd.dev/docs/guides/coding-agents.md) |
| `stagd mcp install [--client claude\|cursor\|all]` | Adds `stagd mcp` to Claude Code (through `claude mcp add`) and Cursor (`~/.cursor/mcp.json`), for every project, keeping their other servers |
