npm package: @specdriverdev/cli
Description: Specdriver CLI for pulling blueprints, drafts, and refinements via the Specdriver API.
Latest version: 0.1.2

# 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:
   ```bash
   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:
```json
{
  "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:

```bash
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:

```bash
npm install -g @specdriverdev/cli
```

The same CLI will remain available via `npx` as well:

```bash
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.