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 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 | Use AI to intelligently decompose the spec into tasks |
# Examples
roady plan generate roady plan generate --ai 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 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 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 & Debt Commands
Detect and manage drift between specs, plans, and execution.
roady drift detect
Check for discrepancies between the current Spec and Plan.
roady drift detect 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 roady debt report
Generate comprehensive debt report showing recurring drift patterns.
roady debt report roady debt sticky
Show sticky debt items (unresolved for more than 7 days).
roady debt sticky roady debt trend
Analyze drift trend over time.
roady debt trend roady debt summary
Quick debt health overview showing health level, top debtor, and sticky count.
roady debt summary roady debt score
Component-level debt score with category breakdown.
roady debt score [component-id] roady debt history
Historical debt tracking over a configurable time window.
roady debt history [flags] Flags
| --days | Number of days to look back (default 30) |
Billing & Cost Commands
Define billing rates, log time, and generate cost reports with variance analysis.
roady rate add
Add a new billing rate with optional currency, tax, and default flag.
roady rate add [flags] Flags
| --id | Unique rate identifier |
| --name | Human-readable rate name |
| --rate | Hourly rate amount |
| --default | Set as the default rate |
# Example
roady rate add --id dev --name "Developer" --rate 120 --default roady rate list
List all configured rates with currency and tax information.
roady rate list roady rate rm
Remove a billing rate by ID.
roady rate rm [rate-id] roady rate default
Set a rate as the default for new time entries.
roady rate default [rate-id] roady rate tax set
Configure tax rules for billing rates.
roady rate tax set [flags] Flags
| --name | Tax name (e.g., VAT, GST) |
| --percent | Tax percentage |
| --included | Whether tax is included in the rate |
roady cost report
Generate a cost report with estimated-vs-actual variance analysis.
roady cost report [flags] Flags
| --task | Filter by task ID |
| --period | Time period filter (e.g., 7d, 30d, 90d) |
| --format | Output format: text, csv, json, markdown |
| --output | Write report to file |
# Examples
roady cost report roady cost report --period 30d --format markdown roady cost budget
Show budget status with consumption tracking and variance against policy limits.
roady cost budget Status & Analytics
View project status, forecasts, and analytics.
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 5 roady status -s in_progress,blocked -p high roady status --json roady status forecast
Predict project completion based on current velocity.
roady status forecast [flags] Flags
| --detailed | Show confidence intervals and all velocity windows |
| --burndown | Show burndown chart data |
| --trend | Show velocity trend analysis |
| --json | Output in JSON format |
roady status usage
Show project usage and AI token statistics.
roady status usage roady status timeline
Show a chronological view of project activity.
roady status timeline roady dashboard
Open the interactive TUI dashboard for visual project overview.
roady dashboard roady dashboard serve
Start a web-based dashboard server.
roady dashboard serve [flags] Flags
| -p, --port | Port to listen on (default 3000) |
Integration Commands
Sync with external tools and integrate with your workflow.
roady sync
Sync the plan with an external system via a plugin.
roady sync [plugin-path] # Examples
roady sync roady-plugin-linear roady sync roady-plugin-jira roady sync roady-plugin-github 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 webhook serve
Start the webhook HTTP server to receive events from external systems.
roady webhook serve [flags] Flags
| -p, --port | Port to listen on (default 8080) |
| --github-secret | GitHub webhook secret |
| --jira-secret | Jira webhook secret |
| --linear-secret | Linear webhook secret |
Webhook endpoints:
POST /webhooks/githubPOST /webhooks/jiraPOST /webhooks/linear
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 mcp roady mcp --transport http --addr :8080 roady mcp --transport grpc --addr :50051 roady deps
Manage cross-repository dependencies.
# Subcommands
roady deps list roady deps add --repo ../auth-service --type runtime roady deps scan roady deps graph roady deps remove [dep-id] Plugin Configuration
Configure sync plugins using the interactive TUI wizard (recommended), .roady/plugins.yaml, or environment variables.
Interactive TUI Wizard (Recommended)
Guided setup with auto-installThe easiest way to configure plugins. The wizard guides you through plugin selection, automatic installation, and credential entry.
# Add a new plugin interactively
roady sync add # Edit an existing configuration
roady sync edit my-jira # Remove a configuration
roady sync remove my-jira # Install a plugin without configuring
roady sync install jira Auto-Install: When you select an uninstalled plugin, roady automatically installs it via go install. No manual setup required!
Configuration File (Recommended)
Secure, version-controllable, multi-environmentDefine named plugin configurations in .roady/plugins.yaml. This approach keeps credentials out of your shell history and allows multiple configurations for different environments.
# .roady/plugins.yaml
plugins:
# Production Jira configuration
jira-prod:
binary: ./roady-plugin-jira
config:
domain: https://mycompany.atlassian.net
project_key: ROAD
email: team@company.com
api_token: your-api-token-here
# Development Linear configuration
linear-dev:
binary: ./roady-plugin-linear
config:
api_key: lin_api_xxxxx
team_id: TEAM-UUID
# GitHub Issues
github:
binary: ./roady-plugin-github
config:
token: ghp_xxxxx
repo: myorg/myprojectUsing Named Configurations
# Sync using a named configuration
roady sync --name jira-prod roady sync -n linear-dev # List configured plugins roady sync list # Show a plugin configuration roady sync show jira-prod Security Tip: Add .roady/plugins.yaml to .gitignore to avoid committing credentials. Consider using environment variable references or a secrets manager for production.
Plugin Configuration Reference
Each plugin accepts specific configuration keys. Use these in your plugins.yaml or as environment variables (fallback).
Jira
| domain | JIRA_DOMAIN | Jira instance URL (e.g., company.atlassian.net) |
| project_key | JIRA_PROJECT_KEY | Project key (e.g., PROJ) |
| JIRA_EMAIL | Atlassian account email | |
| api_token | JIRA_API_TOKEN | API token (create here) |
Linear
| api_key | LINEAR_API_KEY | API key (Linear Settings → API) |
| team_id | LINEAR_TEAM_ID | Team ID (from team settings URL) |
GitHub Issues
| token | GITHUB_TOKEN | Personal access token with repo scope (create here) |
| repo | GITHUB_REPO | Repository (owner/repo) |
Notion
| token | NOTION_TOKEN | Integration token (Notion Integrations) |
| database_id | NOTION_DATABASE_ID | Database ID from URL |
Note: Database needs "Name" (title), "Roady ID" (text), and "Status" (status) properties.
Trello
| api_key | TRELLO_API_KEY | API key (Trello Power-Ups) |
| token | TRELLO_TOKEN | Authorization token |
| board_id | TRELLO_BOARD_ID | Board ID from URL |
| todo_list_id | TRELLO_TODO_LIST_ID | Optional: List for new tasks |
| done_list_id | TRELLO_DONE_LIST_ID | Optional: List for completed tasks |
Asana
| token | ASANA_TOKEN | Personal access token (Developer Console) |
| project_id | ASANA_PROJECT_ID | Project GID from URL |
Environment Variables (Legacy)
For quick testing or CI/CD environmentsYou can still use environment variables directly without a config file. The plugin will check the config file first, then fall back to environment variables.
# Direct plugin path (uses env vars)
export JIRA_DOMAIN="company.atlassian.net" export JIRA_PROJECT_KEY="PROJ" export JIRA_EMAIL="you@company.com" export JIRA_API_TOKEN="your-token" roady sync ./roady-plugin-jira Building Plugins
Build official plugins from source or create your own custom plugins.
# Build all official plugins
go build -o roady-plugin-jira ./cmd/roady-plugin-jira go build -o roady-plugin-linear ./cmd/roady-plugin-linear go build -o roady-plugin-github ./cmd/roady-plugin-github go build -o roady-plugin-notion ./cmd/roady-plugin-notion go build -o roady-plugin-trello ./cmd/roady-plugin-trello go build -o roady-plugin-asana ./cmd/roady-plugin-asana Plugins use HashiCorp's go-plugin over gRPC. Implement the Syncer interface to create custom integrations.
Advanced Commands
Multi-project management, policies, and advanced configuration.
roady org status
Show status overview of all Roady projects in a directory.
roady org status [root-dir] roady discover
Discover all Roady projects in a directory tree.
roady discover [root-dir] roady policy check
Check if the current plan complies with policies (WIP limits, dependencies).
roady policy check roady ai configure
Configure AI provider and policy settings.
roady ai configure roady audit verify
Verify the integrity of the project audit trail (hash-chain verification).
roady audit verify roady watch
Watch a directory for documentation changes and automatically detect drift.
roady watch [dir] [flags] Flags
| --auto-sync | Automatically regenerate plan on documentation changes |
Environment Variables
Configure Roady behavior via environment variables.
| Variable | Description |
|---|---|
| ROADY_AI_PROVIDER | AI provider (ollama, openai, anthropic, gemini) |
| ROADY_AI_MODEL | AI model name |
| OPENAI_API_KEY | OpenAI API key |
| ANTHROPIC_API_KEY | Anthropic API key |
| GEMINI_API_KEY | Google Gemini API key |
| GITHUB_WEBHOOK_SECRET | GitHub webhook secret for validation |
| JIRA_WEBHOOK_SECRET | Jira webhook secret |
| LINEAR_WEBHOOK_SECRET | Linear webhook secret |
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, token_limit) |
| ai.yaml | AI provider/model defaults |
| events.jsonl | Immutable audit trail (hash-chained) |
| usage.json | AI token consumption telemetry |
| plugins.yaml | Named plugin configurations (credentials, binaries) |
| rates.yaml | Billing rates, currency, and tax configuration |
| time_entries.yaml | Logged time entries for cost tracking |