CLI Reference

The @sprintra/cli package provides 23 commands for managing your project directly from the terminal. Works with both local and cloud Sprintra.

Install (v0.4.1 — 42 KB, 2 lightweight dependencies (commander, open))

npm install -g @sprintra/cli

# Or run directly with npx
npx @sprintra/cli context

Global Options

Flag	Default	Description
-p, --project <id>	auto	Project ID (auto-detected from SPRINTRA_PROJECT env var)
-f, --format <format>	pretty	Output format: `json` or `pretty`
-V, --version	—	Show version number

Commands

`sprintra login`

Authenticate with Sprintra. Opens browser OAuth or accepts a pasted token.

Usage

sprintra login

`sprintra logout`

Clear stored credentials and disconnect from Sprintra.

Usage

sprintra logout

`sprintra whoami`

Show the currently authenticated user and organization.

Usage

sprintra whoami

`sprintra token create`

Create a new personal access token for MCP or API use.

Usage

sprintra token create <name>

Example

$ sprintra token create my-cursor-token
Token created: spt_abc123...
Copy this token — it won't be shown again.

`sprintra token list`

List all personal access tokens for your account.

Usage

sprintra token list

`sprintra token revoke`

Revoke a personal access token by ID.

Usage

sprintra token revoke <id>

`sprintra login`

Authenticate with Sprintra. Stores a token at ~/.sprintra/config.json. Run once per machine — the SessionStart hook reads from this file to call the briefing endpoint.

Usage

sprintra login

Example

$ sprintra login

  Sprintra Login
  Option 1: Paste an MCP token from app.sprintra.io/agents
  Option 2: Press Enter to open browser for login

  Token (or Enter for browser): vp_<…>
  ✓ Authenticated. Token saved to ~/.sprintra/config.json

`sprintra link`

Bind the current directory to a Sprintra project. Writes .sprintra/project.json — the SessionStart hook walks up from cwd to find this marker so it knows which project's briefing to fetch. Run once per repo.

Usage

sprintra link --project=<id> [--project-key=<key>] [--path=<dir>] [--force]

Example

$ sprintra link --project=proj-XXXXXXXX --project-key=YOURKEY

  ✓ Created marker at /your/repo/.sprintra/project.json

`sprintra plugin install (deprecated)`

DEPRECATED. Wrote a hooks.json that Claude Code never read. Use Claude Code's native /plugin install instead: /plugin marketplace add Sprintra-io/sprintra-mcp then /plugin install sprintra@sprintra.

Usage

(do not use — does nothing useful)

`sprintra connect`

Auto-configure MCP in your AI tool (Claude Code, Cursor, Claude Desktop). Use this if you only need the MCP wiring, not the full plugin (SessionStart hook).

Usage

sprintra connect

Example

$ sprintra connect

  Detected: Claude Code
  Updated: ~/.claude.json
  MCP server configured. Restart Claude Code to activate.

`sprintra mcp`

Start the MCP proxy server on stdio. Used internally by AI tools — you rarely need to run this directly.

Usage

sprintra mcp

`sprintra orgs`

List organizations you belong to.

Usage

sprintra orgs

`sprintra projects`

List all projects in your organization.

Usage

sprintra projects

`sprintra features`

List features for a project.

Usage

sprintra features [--status <status>]

Options

-s, --status

Filter by status (idea, backlog, todo, in_progress, done, archived)

`sprintra stories`

List stories for a project.

Usage

sprintra stories [--feature <id>] [--status <status>]

Options

--feature	Filter by feature ID
-s, --status	Filter by status (todo, in_progress, done)

`sprintra sprints`

List sprints for a project.

Usage

sprintra sprints

`sprintra decisions`

List architecture decisions (ADRs).

Usage

sprintra decisions

`sprintra activity`

Recent activity feed.

Usage

sprintra activity [--limit <n>]

Options

-l, --limit

Max entries (default: 20)

`sprintra context`

Full project snapshot — sprint, stories, decisions, blockers, session, stats.

Usage

sprintra context

Example

$ sprintra context

  Sprintra [active]
  AI-native project management tool

  Sprint: Sprint 14 — Session Replay
  Progress: 12/18 stories (67%)
  Ends: 2026-03-21

  In Progress (3):
    s-abc123  Payment webhook handler  Payments
    s-def456  Auth middleware refactor  Authentication

  Stats: 61/70 features | 340/380 stories

`sprintra next-work`

Recommended next story to work on, with full context and readiness score.

Usage

sprintra next-work

Alias: next

Example

$ sprintra next-work

  Next: Implement Stripe webhook signature verification
  ID: s-ghi789  Type: story  Points: 3
  Readiness: 85%
  Feature: Payment Integration [high]

  Acceptance Criteria:
    - Verify webhook signatures using Stripe SDK
    - Handle duplicate events idempotently
    - Log failed verifications to Sentry

`sprintra briefing`

Compact project state summary optimized for AI context windows (<500 tokens).

Usage

sprintra briefing

`sprintra delta`

Show changes since your last session — new stories, status updates, decisions, and activity.

Usage

sprintra delta

`sprintra status`

Show connection status and server info.

Usage

sprintra status

Example

$ sprintra status

  Sprintra CLI v0.4.1
  Server: https://api.sprintra.io
  Mode: production
  Status: ok
  DB: ok (3ms)
  Token: set
  Project: proj-XXXXXXXX

Environment Variables

Variable	Default	Description
SPRINTRA_TOKEN	—	API token for Sprintra Cloud authentication
SPRINTRA_PROJECT	—	Default project ID (avoids --project flag on every command)
SPRINTRA_URL	auto	Override API URL (auto-detects local vs cloud)

Server Auto-Detection

The CLI automatically detects which server to connect to:

Check SPRINTRA_URL

If set, use that URL directly

Probe local server

Check if http://127.0.0.1:4000 is running (1s timeout)

Fall back to Sprintra Cloud

Connect to https://api.sprintra.io (requires SPRINTRA_TOKEN)

JSON Output for AI Agents

Use --format json to get machine-readable output. This is useful when other AI agents or scripts consume the CLI output.

Example

$ sprintra context --format json | jq '.current_sprint.name'
"Sprint 14 — Session Replay"

$ sprintra stories --status todo --format json | jq '.[].title'
"Implement webhook handler"
"Add rate limiting"
"Write integration tests"

Troubleshooting

"Error: project ID required"

Set the SPRINTRA_PROJECT env var or pass --project <id> on every command:

export SPRINTRA_PROJECT=proj-abc123
# or
sprintra context --project proj-abc123

"API error 401: Unauthorized"

Set your SPRINTRA_TOKEN env var. Generate a token from the MCP Tokens page in the Sprintra dashboard.

"Cannot connect"

The CLI couldn't reach any Sprintra server. Check that the local server is running (sprintra start) or that you have internet access for Sprintra Cloud.