Specdriver CLI

Lightweight command-line access to your Specdriver blueprints. Authenticate once, pull projects/specs, and trigger refinements directly from your terminal, VS Code tasks, or AI agents.

Installation

1. Ensure repo dependencies are installed (npm install).
2. Build the CLI package:

   npm run build -w packages/specdriver-cli

3. Add a wrapper script (optional) or call via node packages/specdriver-cli/dist/index.js.

Configuration

The CLI reads its settings from environment variables or ~/.specdriver/config.json (created automatically on first run).

Required values:

• SPEC_API_URL – e.g. https://specdriver.dev
• SPEC_SUPABASE_URL – your Supabase project URL
• SPEC_SUPABASE_ANON_KEY – Supabase anon key with password grant enabled

Example manual config:

{
  "apiUrl": "https://specdriver.dev",
  "supabaseUrl": "https://YOUR.supabase.co",
  "supabaseAnonKey": "eyJhbGci..."
}

Commands

specdriver login

Launches the browser-based device approval flow:

1. CLI prints a XXXX-XXXX code plus a verification link.
2. We open the default browser (or you can copy the link) and use the existing Supabase login screen.
3. After you approve the device, the CLI captures the Supabase tokens locally (~/.specdriver/config.json) and future commands reuse them.

Need legacy behavior? Use specdriver login --password-flow (or --email/--password) to fall back to direct Supabase password auth.

Use specdriver logout to clear stored tokens.

specdriver projects list

List projects the authenticated user owns (hits /api/v1/projects).

specdriver projects list --limit 50

specdriver projects pull <projectId>

Download an entire blueprint as JSON, markdown, or a folder tree for AI tools.

# JSON to stdout
specdriver projects pull 123e4567

# Markdown to file
specdriver projects pull 123e4567 \
  --format markdown \
  --output ./specs/ecommerce.md

# Structured folder (project.json + per-category + per-node files)
specdriver projects pull 123e4567 \
  --format folder \
  --output ./specs/ecommerce

Markdown output includes summary stats, the initial prompt, category sections, and node-level details (file paths, status, business value/user story, dependencies). The folder export drops:

• project.json (full API response)
• README.md (markdown overview)
• /categories/*.md (category summaries with node listings)
• /nodes/*.json (per-node specs keyed by slug or file path)

Perfect for pointing Claude/Cursor agents at a complete local spec directory.

specdriver config

Show the effective configuration (tokens masked).

specdriver drafts start

Kick off a new builder job (blueprint draft). Prompts for project name/description if not provided.

specdriver drafts status <draftId>

Show live stats (categories/nodes vs thresholds) for a draft. Useful while the builder is streaming chunks.

specdriver drafts pull <draftId> [--format json|markdown]

Fetch draft categories/nodes even before finalization so you can inspect/spec-review mid-build.

specdriver drafts finalize <draftId>

Run the same validation/finalization flow as the web app. Converts the draft into a full project once minimum thresholds are met.

specdriver nodes list <projectId>

List project nodes with optional status/locked filters.

specdriver nodes get <nodeId> [--format json|markdown]

Pull a single node in JSON (default) or markdown.

specdriver nodes refine <nodeId> [--message "..."]

Request AI refinements (same endpoint as the UI). Pipe to stdout or save via --output.

specdriver nodes apply <projectId> --input refine-output.json

Apply a saved refinement payload directly to the project.

Packaging binaries

To build distributable binaries (macOS x64/arm64, Linux x64, Windows x64) run:

npm run cli:package

Artifacts are emitted to packages/specdriver-cli/dist/bin/:

• specdriver-macos-x64
• specdriver-macos-arm64
• specdriver-linux-x64
• specdriver-win-x64.exe

Distribute these files through GitHub Releases or S3 and point your marketing/download links at the correct binary per platform. Users just need to download, chmod +x (where appropriate), and drop the binary in their PATH.

Install via npm

Once @specdriverdev/cli is published to npm you can skip the manual download and install globally:

npm install -g @specdriverdev/cli

The same CLI will remain available via npx as well:

npx @specdriverdev/cli projects list

Roadmap

• Device-code auth + PATs (no password entry)
• VS Code extension using the same API client
• Reverse-spec / repo analysis upload
• Long-poll/watch mode for builders & refinements

Notes

• All CLI operations reuse the existing production APIs; no backend changes required.
• Credits/rate limits apply exactly as they do in the browser.
• Starter/Pro/Ultra users can be granted CLI access via feature flag/plan checks.