CLI

The npm package is getstead; both getstead and stead binaries are installed. Use Node.js 22 or newer.

npm install --global getstead@0.2.1
getstead --help

Alternatively prefix commands with npx --yes getstead@0.2.1. The CLI has no --version command in this release; inspect the installed package with npm list --global getstead or record the version in your invocation.

Account and project commands

Command	Behavior
getstead login [--api-url URL]	Display a browser authorization link; default API is https://api.getstead.dev. --browser explicitly selects this mode.
getstead login --email EMAIL [--api-url URL]	Password login; input is hidden in a terminal or read from stdin. Requires an already verified developer account.
getstead logout	Revoke and remove the saved CLI login.
getstead projects list	List accessible projects and their deletion state.
getstead projects create NAME	Create a project, display its initial credential once, and select it in this directory.
getstead projects use ID	Select an owned project in this directory’s stead.json.
getstead projects delete ID --confirm-name NAME	Permanently request deletion after an exact name match. Requires developer login.
getstead init [DIR]	Scaffold the starter, default current directory; refuse to overwrite existing template files.

Project account commands use the developer session. Run init before selecting a project in a new directory.

Project commands

These use either your saved developer login plus stead.json.projectId, or STEAD_PROJECT_SECRET for automation.

Command	Behavior
getstead deploy [--config PATH]	Publish the built bundle, agents, exposures, and new migrations. Defaults to ./stead.json.
getstead doctor [--json] [--check-provider]	Read project diagnostics. The provider option makes a small billable model call.
getstead run SCENARIO	Read a JSON file at that path, or scenarios/SCENARIO.json, and start its project scenario.
getstead run --resume RUN_ID	Resume the recorded program; do not also pass a scenario.
getstead runs [--status STATUS] [--cursor CURSOR]	List runs and recorded spend. Pass the returned cursor for another page.
getstead trace RUN_ID	Display run state, step events, ledger entries, and totals.
getstead approvals [--status STATUS] [--cursor CURSOR]	List approvals, default status pending.
getstead approve APPROVAL_ID	Approve a pending, unexpired action and trigger automatic resume.
getstead deny APPROVAL_ID	Deny a pending, unexpired action.
getstead keys set --base-url URL	Save a provider key from STEAD_PROVIDER_KEY or piped stdin. No key argument is accepted.

There is no CLI cancellation command in this release. Use the console or SteadClient.cancelRun.

Environment and precedence

Variable	Meaning
STEAD_API_URL	Overrides stead.json.apiUrl. Login’s --api-url overrides both.
STEAD_PROJECT_SECRET	If nonempty, selects project-credential authentication for project commands instead of the saved login.
STEAD_PROVIDER_KEY	Nonempty value takes precedence over stdin for keys set.
STEAD_CONFIG_DIR	Directory containing the private session.json file.
XDG_CONFIG_HOME	If no STEAD_CONFIG_DIR, sessions use $XDG_CONFIG_HOME/stead; otherwise default ~/.config/stead.
STEAD_DASHBOARD_URL	Overrides optional stead.json.dashboardUrl for trace links.

The CLI does not automatically load .env. Existing exported shell variables remain authoritative. A saved login is pinned to its API URL; targeting a different server requires a new login. Do not diagnose a mismatch by printing secret environment variables.

Exit behavior

Successful commands exit 0; usage and request errors exit 1. doctor exits 1 when diagnostics require action or the optional provider check did not complete. Notices alone do not fail it. run exits 1 for a failed outcome; inspect the reported status for approval waits, cancellation, and budget exhaustion rather than treating exit 0 as proof of completed business work.

doctor checks model credentials and browser origins even for projects that only run tools from a server or CLI. Missing settings produce exit 1 in those projects too. Read the individual checks: a missing model key does not prevent tool-only execution, and browser origins are needed when your customer app uses browser authentication.

Installation operator command

getstead keygen writes an Ed25519 private/public PEM pair to stdout for someone operating a Stead installation. Hosted developers do not need it. Its output includes a private key; do not run it in logs or attach the output to support requests.