@getstackrun/cli

STACK from your terminal. The operator CLI mirrors nearly every STACK surface: register agents, issue passports, connect services and grant scoped credentials, manage your team, configure detectors and notifications, retrieve credentials for scripts and CI, and tail the live audit log. Sign in once via OAuth Device flow.

# Sign in (browser opens, RFC 8628 Device flow)
npx @getstackrun/cli auth login

# Fastest path: register a safe bot, make one governed LLM call, see the proof
npx @getstackrun/cli quickstart

# Run a localhost LLM gateway — point any tool's baseURL at it, no key on the box
npx @getstackrun/cli proxy serve --agent familybot

# Retrieve a credential for a script (operator-only, audited, revocable)
export SLACK_TOKEN=$(npx @getstackrun/cli service credential slack --json | jq -r .access_token)

# Tail your live audit log
npx @getstackrun/cli monitor --follow

# See everything
npx @getstackrun/cli --help

Agents with the default stack_managed signing model need no enrollment — quickstart and proxy serve provision the on-box keypair automatically on first run. agent enroll is only for the advanced customer_managed bring-your-own-keypair path.

Which surface? CLI vs MCP vs SDK

STACK has three client surfaces. Pick by who is driving.

| Surface | Who drives it | When | What it's for | | --- | --- | --- | --- | | MCP (mcp.getstack.run) | an LLM assistant (Claude Code, Cursor) | dev and setup, in natural language | auto-discovered stack_* tools over OAuth | | SDK (@getstackrun/sdk, getstack) | the agent's own code | the runtime hot path | offline passport verification, in-process | | CLI (npx @getstackrun/cli) | a human operator in a terminal | ops, scripts, CI | the full operator surface + live audit tail + scriptable credential retrieval |

The three share one credential: auth login writes ~/.stack/credentials.json, and both SDKs read it. Sign in once, all three work.

Commands

npx @getstackrun/cli --help prints the full verb set: agent, passport, service, dropoff, skill, identity, audit, event, team, notifications, detector, intents, llm, and more. The most common starting points are below; see the docs for the rest.

auth

auth login    Sign in via the browser (Device flow, RFC 8628).
              Stores a refresh token at ~/.stack/credentials.json
              with mode 0600. SDKs read it automatically.
auth status   Show the current sign-in state (operator email, scope, expiry).
auth logout   Revoke the refresh token and clear the local file.

monitor

--demo                   Replay a real-shape mission (no auth needed).
                         Same row format as --follow, just scripted.
--follow                 Tail your operator's actual audit_log. Polls
                         every 2s. Auth picked in priority order:
                           1. STACK_API_KEY env var (legacy CI path)
                           2. ~/.stack/credentials.json (auth login)
--loop                   Loop the demo until Ctrl-C (default is one run).
--agent <agent_id>       (--follow) Only show entries for this agent.
--jti <passport_jti>     (--follow) Only show entries for this passport.
--sandbox                (--follow) Tail the public sandbox feed at
                         https://api.getstack.run/v1/public/events.
                         No auth needed.

Examples

# Tail one agent
npx @getstackrun/cli monitor --follow --agent agt_abc123

# Tail one passport (e.g. debugging a specific revoke chain)
npx @getstackrun/cli monitor --follow --jti pas_xyz789

# Tail the public sandbox (no signup, no key)
npx @getstackrun/cli monitor --follow --sandbox

# CI mode (no browser)
STACK_API_KEY=sk_live_… npx @getstackrun/cli monitor --follow

register

npx @getstackrun/cli register

Prints signup + MCP-install instructions for connecting STACK to Claude Code.

Authentication

auth login runs the OAuth 2.1 Device Authorization Grant against https://api.getstack.run:

1. CLI dynamically registers itself as a public PKCE client (one client_id per install).
2. Server issues a device_code + a human-readable user_code (e.g. WDJB-MJHT).
3. CLI prints the URL + opens your browser to https://getstack.run/cli/auth?code=....
4. You confirm the code and approve.
5. CLI persists the refresh token to ~/.stack/credentials.json (mode 0600).

Refresh tokens auto-rotate on every use. The same file is also read by both SDKs (@getstackrun/sdk for TS/JS, getstack for Python), so signing in once gives all three surfaces a working credential.

For CI environments without a browser, keep STACK_API_KEY=sk_live_... set. The CLI still accepts it as a fallback.

See /docs/security/stack-auth for the full auth model.

License

Apache-2.0