CLI Reference

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

Install

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 context`

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

Usage

sprintra context

Example

$ sprintra context

  VibePilot [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 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 update-story`

Update a story's status, title, points, or assignee

Usage

sprintra update-story <story-id> [options]

Options

-s, --status	New status (todo, in_progress, done)
-t, --title	New title
--points	Story points
--assignee	Assignee name

Example

$ sprintra update-story s-abc123 --status done
Done.

`sprintra create-story`

Create a new story under a feature

Usage

sprintra create-story --feature <id> --title <title> [options]

Options

--feature	Feature ID (required)
-t, --title	Story title (required)
--type	Type: story, task, bug, chore (default: story)
--points	Story points
-d, --description	Description
--assignee	Assignee name

`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 status`

Show connection status and server info

Usage

sprintra status

Example

$ sprintra status

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

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.