Early access is open. Stagd is free during the beta. Sign up
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

For language models and agents: this page as Markdown, or every page through llms.txt.