@getstackrun/cli

Tail STACK runtime activity in your terminal. Sign in via OAuth Device flow.

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

# Tail your audit_log — no env vars needed after auth login
npx @getstackrun/cli monitor --follow

# Replay a real-shape demo (no auth needed)
npx @getstackrun/cli monitor --demo --loop

Both monitor modes render rows of the same shape — straight from audit_log columns on STACK's API. What you see in --demo is the same shape --follow produces against your own data.

Commands

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_... — the CLI still accepts it as a fallback.

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

License

Apache-2.0