Plan CLI Reference

All commands use the refrakt plan <command> namespace. Add --format json to any command for machine-readable output.

init

Initialize a plan directory in your project.

npx refrakt plan init

Creates the directory structure, example files, and optionally wires your AI agent with plan context.

create

Scaffold a new entity.

npx refrakt plan create <type> --title "Description"

Types: spec, work, bug, decision, milestone

Attributes by entity type:

# Auto-assigned ID
npx refrakt plan create work --title "Add search" --priority high --complexity moderate

# Explicit ID
npx refrakt plan create milestone --id v2.0.0 --title "Next major release" --target 2026-09-01

next

Find the next actionable work item.

npx refrakt plan next

Returns the highest-priority item whose status is ready (work) or confirmed (bug) and whose dependencies are all complete.

update

Modify an entity's attributes, check off criteria, or add a resolution.

npx refrakt plan update <id> [options]

Pass an empty string to clear an attribute: --assignee ""

# Change status and assign
npx refrakt plan update WORK-042 --status in-progress --assignee "alice"

# Check off a criterion
npx refrakt plan update WORK-042 --check "Login form validates email"

# Complete with resolution
npx refrakt plan update WORK-042 --status done --resolve "Implemented in PR #123"

status

Terminal dashboard showing project status.

npx refrakt plan status

Displays status counts, blocked items, ready queue, recent completions, and warnings.

validate

Check plan integrity.

npx refrakt plan validate

Checks for: duplicate IDs, broken references, invalid attribute values, filename format mismatches.

next-id

Show the next auto-increment ID for a type without creating anything.

npx refrakt plan next-id work
# → WORK-126

Types: spec, work, bug, decision (not milestones — they use explicit names).

history

View git-native change history.

# Single entity
npx refrakt plan history WORK-042

# Global activity
npx refrakt plan history --since 7d

serve

Local web dashboard for browsing your plan.

npx refrakt plan serve

build

Generate a static plan site.

npx refrakt plan build

migrate

Convert legacy filenames to the {ID}-{slug}.md naming convention. Use this when you have plan files that were created manually or with an older version of the CLI that used a different naming scheme.

By default, migrate runs in dry-run mode and shows what would change without modifying any files.

# Preview changes (dry-run)
npx refrakt plan migrate filenames

# Apply renames
npx refrakt plan migrate filenames --apply

# Apply with git history preservation
npx refrakt plan migrate filenames --apply --git

JSON output

All commands support --format json for machine-readable output. This is useful for scripting, CI pipelines, and integration with other tools.

npx refrakt plan next --format json

{
  "id": "WORK-042",
  "title": "Implement login flow",
  "status": "ready",
  "priority": "high",
  "complexity": "moderate",
  "milestone": "v1.0.0",
  "source": "SPEC-001",
  "assignee": null,
  "tags": ["auth"],
  "criteria": {
    "total": 4,
    "checked": 0
  },
  "file": "plan/work/WORK-042-implement-login-flow.md"
}

The exact shape varies by command — plan status returns aggregate counts, plan validate returns an array of diagnostics, etc. Pipe through jq for further processing:

# Get IDs of all ready work items
npx refrakt plan next --count 100 --format json | jq -r '.[].id'