CLI Reference

Complete command documentation for Roady - the planning-first system of record.

Getting Started

roady init

Initialize a new Roady project in the current directory.

roady init [project-name] [flags]

Flags

--interactive

Prompt for AI configuration after initialization

# Example

roady init my-project --interactive

roady setup

Wire the MCP server, instructions, and session hooks for an agent: claude-code, claude-desktop, codex, gemini, cursor, opencode, copilot, or kiro.

roady setup claude-code

roady next

Brief on the task you are on, or the one to start next. Agent hooks run it at session start.

roady next

roady doctor

Check the health of the Roady environment and validate project setup.

roady doctor

Spec Commands

Manage product specifications - the source of truth for what you're building.

roady spec analyze

Analyze a directory for markdown files and infer a product specification.

roady spec analyze [dir] [flags]

Flags

--reconcile

Use AI to semantically deduplicate and reconcile the spec

# Example

roady spec analyze docs/ --reconcile

roady spec add

Quickly add a new feature to the specification.

roady spec add [feature-title]

# Example

roady spec add "User authentication with OAuth"

roady spec validate

Validate the current specification structure and content. Also available as roady spec lint.

roady spec validate

roady spec import

Import a spec from a markdown file.

roady spec import [file.md]

roady spec explain

Get an AI-generated explanation of the current spec.

roady spec explain

Plan Commands

Manage execution plans - the task DAG derived from your spec.

roady plan generate

Generate a plan from the current spec. Creates tasks with dependencies.

roady plan generate [flags]

Flags

--ai	Emit a decomposition prompt instead of generating. Run it with your own model, then write the tasks back with `roady_update_plan`.
--json	Emit the prompt request as JSON for an agent to consume

# Examples

roady plan generateroady plan generate --ai

roady capture

Record features, requirements, and tasks in one write (YAML or JSON). See docs/capture.md.

roady capture -f plan.yaml

roady plan import

Turn a harness's plan file (Claude Code, Kiro, Codex ExecPlan, markdown) into tasks.

roady plan import ~/.claude/plans/my-plan.md --dry-run

roady plan approve

Approve the current plan for execution. Required before tasks can be started.

roady plan approve

roady plan reject

Reject the current plan, requiring regeneration.

roady plan reject

roady plan prune

Remove tasks from the plan that are no longer in the spec.

roady plan prune

Task Commands

Manage individual task lifecycle - start, complete, block, and verify.

roady task mine · assigned · unassigned

Answer who is working on what. mine resolves you from ROADY_USER, then git user.name, then USER.

roady task mineroady task assigned <name>roady task unassigned

roady task start

Start working on a task. Validates dependencies and WIP limits.

roady task start [task-id] [flags]

Flags

-e, --evidence

Evidence for the task (e.g., commit hash, URL)

roady task complete

Mark a task as completed.

roady task complete [task-id] [flags]

Flags

-e, --evidence

Evidence for completion (e.g., commit hash, PR URL)

roady task block / unblock

Mark a task as blocked or remove the block.

roady task block [task-id]roady task unblock [task-id]

roady task stop

Stop working on a task (return to pending).

roady task stop [task-id]

roady task check

Run a task's acceptance check and record the result as evidence. roady task verify refuses while the check fails.

roady task check [task-id]

roady task verify

Mark a completed task as verified with evidence.

roady task verify [task-id] --evidence "PR #123 merged"

roady task reopen

Reopen a completed task if issues are found.

roady task reopen [task-id]

Drift Commands

Detect and manage drift between specs, plans, and execution.

roady drift detect

Report where intent, plan, and reality have parted company. Exits non-zero when drift is found, so it can gate CI.

roady drift detect

What it checks

intent	The spec changed since it was last locked
plan	Requirements with no task, or tasks with no requirement
code	A task marked done whose file is missing or uncommitted
stale	The plan itself has fallen behind — the repository moved on without it

roady drift accept

Accept current drift by locking the spec snapshot.

roady drift accept

roady drift explain

Get AI-generated explanation and resolution steps for current drift.

roady drift explain

Status & Audit

View project status, rebuild state, and inspect the audit trail.

roady status

Show a high-level summary of the project state with optional filtering.

roady status [flags]

Flags

-s, --status	Filter by status (pending,blocked,in_progress,done,verified)
-p, --priority	Filter by priority (high,medium,low)
--ready	Show only tasks ready to start (unlocked + pending)
--blocked	Show only blocked tasks
--active	Show only in-progress tasks
-n, --limit	Limit number of tasks shown
--json	Output in JSON format

# Examples

roady status --ready --limit 5roady status -s in_progress,blocked -p highroady status --json

roady state rebuild

Reconstruct state.json by replaying the event log. events.jsonl union-merges cleanly, but state.json is a whole-file document and will still conflict; it is derived data, so keep either side and replay.

git checkout --ours .roady/state.jsonroady state rebuild --dry-runroady state rebuild

roady audit trail

Produce an evidence trail for a task, agent, or session: chain integrity, findings, evidence, and every recorded event. Exits non-zero when verification fails.

roady audit trail [task-id] [flags]

Flags

--agent	Only events from this agent
--session	Only events from this session ID

Git & MCP Commands

Advance task state from commits and connect AI agents.

roady git sync

Scan recent git commits for task completion markers [roady:task-id].

roady git sync

# Commit with task marker

git commit -m "Implement auth [roady:task-1]"

roady mcp

Start the Roady MCP (Model Context Protocol) server for AI agent integration.

roady mcp [flags]

Flags

--transport	Transport to use: stdio, http, ws, grpc (default "stdio")
--addr	Address for http/ws/grpc transports (default ":8080")

# Examples

roady mcproady mcp --transport http --addr :8080roady mcp --transport grpc --addr :50051

Advanced Commands

Policies and audit integrity.

roady policy check

Check if the current plan complies with policies (WIP limits, dependencies).

roady policy check

roady audit verify

Verify the integrity of the project audit trail (hash-chain verification).

roady audit verify

Environment Variables

Configure Roady behavior via environment variables.

Variable	Description
ROADY_SESSION_ID	Session recorded in the audit trail (generated per run when unset)
ROADY_AGENT	Agent name recorded in the audit trail (auto-detected for Claude Code, Cursor, Codex, Gemini CLI)
ROADY_USER	Task owner (`roady task mine`) and per-owner WIP limits

Project Data Files

Files stored in the .roady/ directory.

File	Purpose
spec.yaml	Product specification (features, requirements)
spec.lock.json	Pinned spec snapshot for drift detection
plan.json	Task DAG with approval status
state.json	Execution state (task statuses)
policy.yaml	Governance (max_wip, allow_ai)
events.jsonl	Immutable audit trail (hash-chained)