Reference
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) 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 |
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:
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 |
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 |