Commands Reference

All available CLI commands with options, arguments, and usage examples.

Global Flags

These flags apply to all commands:

Flag	Default	Description
`--model <id>`	Provider default	Override the AI model (e.g., `claude-opus-4-6`, `gemini-2.5-pro`)
`--provider <name>`	`claude`	AI provider: `claude`, `gemini`, `codex`, `openrouter`
`--debug`	`false`	Show full stack traces on errors

bash

# Use a different model
reygent run --spec spec.md --model claude-opus-4-6

# Use a different provider
reygent agent dev --provider gemini

# Debug mode for troubleshooting
reygent run --spec spec.md --debug

`reygent init`

Initialize a .reygent/ config folder in your project.

bash

reygent init

What it does:

Creates .reygent/config.json with all built-in agent definitions
Warns if .reygent/ already exists
Skips creation if config.json already exists

When to use: First time setting up reygent on a project so you can customize agent prompts and tools.

`reygent generate-spec`

Generate a full markdown spec from a short description.

bash

reygent generate-spec [description] [--output <file>] [--skip-clarification]

Argument/Option	Description
`description`	Short description of the feature (prompted interactively if omitted)
`--output <file>`	File path to write the spec to (prompted interactively if omitted)
`--skip-clarification`	Skip clarifying questions and generate spec directly

Example:

bash

reygent generate-spec "Add dark mode toggle to settings" --output dark-mode-spec.md

The planner agent generates a structured spec with Title, Overview, Requirements, Acceptance Criteria, and Constraints sections.

`reygent spec <source>`

Load and display a parsed spec from any supported source.

bash

reygent spec <source> [--clarify]

Argument/Option	Description
`source`	Path to `.md` file, issue key (`PROJ-123`), or Linear URL
`--clarify`	Run the planner with an interactive clarification loop

Examples:

bash

# Load from markdown
reygent spec ./feature-spec.md

# Load from Jira
reygent spec PROJ-123

# Load from Linear
reygent spec https://linear.app/team/issue/ENG-456

# Load and run planner clarification
reygent spec ENG-456 --clarify

Without --clarify, outputs the raw spec as JSON. With --clarify, runs the planner agent and displays a structured plan with goals, tasks, constraints, and definition of done.

`reygent agent [name]`

Start an interactive agent session. Spawns the Claude CLI with the agent's system prompt injected.

bash

reygent agent [name] [--spec <source>]

Argument/Option	Description
`name`	Agent name: `dev`, `qe`, `planner`, `security-reviewer`, `pr-reviewer`, `adhoc` (prompted interactively if omitted)
`--spec <source>`	Path to `.md` file, issue key, or Linear URL — appended to the agent's system prompt

Examples:

bash

# Pick agent interactively
reygent agent

# Start interactive session with dev agent
reygent agent dev

# Interactive session with spec context
reygent agent qe --spec ./feature-spec.md

# Use a skill from the registry
reygent agent code-reviewer

`reygent run`

Run the full reygent workflow from spec to reviewed PR.

bash

reygent run --spec <source> [options]

Option	Default	Description
`--spec <source>`	(required)	Path to `.md` file, issue key, or Linear URL
`--dry-run`	`false`	Print workflow stages as a tree diagram without executing
`--security-threshold <level>`	`HIGH`	Minimum severity to fail security review (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`)
`--auto-approve`	`false`	Auto-approve all file edits and actions without prompting
`--insecure`	`false`	Skip SSL certificate verification for API calls
`--skip-clarification`	`false`	Skip planner clarification questions; make assumptions instead
`--max-retries <count>`	`2`	Maximum retry attempts when gate tests fail
`--verbose`	`false`	Show detailed token/cost breakdown per agent, including input/output tokens and estimated cost

Examples:

bash

# Full reygent workflow with interactive prompts
reygent run --spec feature.md

# Fully autonomous — no prompts at all
reygent run --spec ENG-123 --auto-approve --skip-clarification

# Preview what workflow stages would run
reygent run --spec feature.md --dry-run

# Strict security — fail on any finding
reygent run --spec feature.md --security-threshold LOW

# More retries for flaky tests
reygent run --spec feature.md --max-retries 5

# Corporate network with self-signed certs
reygent run --spec feature.md --insecure

# Show detailed token/cost breakdown
reygent run --spec feature.md --verbose

Verbose output example:

┌─ Detailed Usage (--verbose)
│  planner (plan)  $0.45  12s  3 turns  2,500 in / 850 out
│    cache: { cached: 1,200, saved: $0.08, provider: claude }
│  dev (implement)  $0.32  8s  2 turns  1,800 in / 600 out
│  qe (implement)  $0.19  5s  1 turn  900 in / 400 out
│    cache: { cached: 300, saved: $0.02, provider: claude }
│  pr-review (pr-review)  $0.12  4s  1 turn  600 in / 250 out
└─

Shows individual agent calls with stage names, duration, turn count, tokens, and cache metadata.

Reygent Workflow Stages

#	Stage	Agent(s)	What happens
1	Plan	`planner`	Breaks spec into goals, tasks, constraints, definition of done
2	Implement	`dev` + `qe`	Dev writes code + unit tests; QE writes functional tests
3	Unit Test Gate	`dev`	Runs unit tests; retries dev agent on failure
4	Functional Test Gate	`qe`	Runs functional tests; retries dev + qe agents on failure
5	Security Review	`security-reviewer`	Scans for OWASP Top 10 vulnerabilities
6	PR Create	`pr-reviewer`	Creates branch, commits, pushes, opens PR
7	PR Review	`pr-reviewer`	Reviews diff, posts review comment on PR

Interactive Prompts

When running without --auto-approve, you'll be prompted for:

Auto-approve mode — whether to let agents edit files freely
Clarification preference — whether the planner should ask questions or make assumptions
Retry decisions — when a test gate fails, whether to retry
Security bypass — when the security review fails, whether to continue

`reygent continue`

Resume a previously failed or interrupted reygent run. Each reygent run writes a snapshot to .reygent/runs/<runId>.json after every completed stage; continue lets you pick one up where it left off.

bash

reygent continue [--run-id <id>] [--auto-approve] [--verbose]

Option	Description
`--run-id <id>`	Run id (or unique prefix) to resume — skips the interactive picker
`--auto-approve`	Auto-approve all file edits and actions without prompting
`--verbose`	Show detailed per-agent token and cost breakdown

What it does:

Looks up unfinished snapshots in <projectRoot>/.reygent/runs/ (any run whose last completed stage is not pr-review, or that has a failedStage)
Displays up to 5 most recent unfinished runs with short id, spec title, last completed stage, failed stage, and age
Re-invokes reygent run with the original run options (provider, model, type, security threshold, etc.) and replays state from the snapshot so completed stages are skipped
CLI flags passed to continue (--auto-approve, --verbose) override the values stored in the snapshot

Examples:

bash

# Interactive picker
reygent continue

# Resume a specific run by id prefix
reygent continue --run-id a1b2c3d4

# Resume non-interactively (e.g., CI) — --run-id is required
reygent continue --run-id a1b2c3d4 --auto-approve

Requirements and behavior:

Must be run from a project with a .reygent/ directory (same as reygent run)
In non-TTY environments, --run-id is required — the interactive picker is skipped
Ambiguous prefixes (matching more than one run) error out; use a longer prefix
Snapshots stay on disk after a successful resume completes the pr-review stage

`reygent dashboard`

Visual interface for exploring Reygent telemetry data. Generates a self-contained HTML dashboard or runs CLI queries against the local telemetry DB. See Dashboard for full details and screenshots.

bash

reygent dashboard <subcommand> [options]

Subcommands

`reygent dashboard generate`

Generate a standalone HTML dashboard with embedded telemetry data.

bash

reygent dashboard generate [--output <file>] [--open]

Option	Description
`--output <file>`	Output file path (default: `<projectRoot>/.reygent/reygent-dashboard.html`)
`--open`	Open the dashboard in the default browser after generation

`reygent dashboard runs`

List recent runs in the terminal with status, duration, and cost.

`reygent dashboard trends`

Show success/failure trends over time.

`reygent dashboard agent-failures`

Aggregate failure counts by agent to find unstable stages.

`reygent dashboard run <runId>`

Show the full event timeline for a specific run.

`reygent dashboard export`

Export telemetry data for offline analysis.

bash

reygent dashboard export [--format csv|xlsx] [--output <file>]

See Dashboard for full options on each subcommand.

`reygent review-work`

Review the current branch's changes and optionally post the review to an open PR or MR.

bash

reygent review-work [--spec <source>] [--insecure]

Option	Description
`--spec <source>`	Optional spec to review the diff against (provides context for the review)
`--insecure`	Skip SSL certificate verification for GitLab API calls

What it does:

Detects the current branch and git platform (GitHub or GitLab)
Checks for an open PR/MR on the current branch
Gets the diff between the current branch and the default branch
Runs the pr-reviewer agent to review the diff
If a PR/MR exists, posts the review as a comment

Examples:

bash

# Review current branch
reygent review-work

# Review with spec context
reygent review-work --spec feature-spec.md

# Review on GitLab with self-signed certs
reygent review-work --insecure

Platform behavior:

GitHub: Uses gh pr view to detect PRs and gh pr comment to post reviews
GitLab: Uses the GitLab API to detect MRs and post review notes
No PR/MR found: Review is printed to the console only

`reygent review-comments`

Fetch review comments from an open PR/MR and run the dev agent to address them.

bash

reygent review-comments [--insecure] [--auto-approve]

Option	Description
`--insecure`	Skip SSL certificate verification for GitLab API calls
`--auto-approve`	Skip plan approval prompt and execute immediately

What it does:

Detects the current branch and git platform
Finds the open PR/MR and fetches all review comments
Displays a summary of the comments
Runs the planner agent to create a plan addressing the comments
Presents the plan for approval (unless --auto-approve)
Runs the dev agent to implement the fixes
Commits and pushes the changes

Examples:

bash

# Address review comments interactively
reygent review-comments

# Fully autonomous — no approval prompt
reygent review-comments --auto-approve

# GitLab with self-signed certs
reygent review-comments --insecure

Approval loop: When not using --auto-approve, you can:

Approve — execute the plan
Provide feedback — regenerate the plan with your notes
Reject — exit without changes

`reygent config`

Interactively configure provider, model, and per-agent overrides.

bash

reygent config

What it does:

Shows current provider and model settings
Checks which providers are available on your machine (green checkmark or red cross)
Prompts you to select a default provider (claude, gemini, codex, openrouter)
Prompts you to select a default model from that provider's supported list
Walks through each agent, grouped by category (Development, Testing & Review, Planning), and shows:
- Role badge, description, and available tools
- Current provider and model
- Three choices: Keep current, Customize (pick a different provider/model), or Clear overrides (remove per-agent overrides)
Writes the updated config to .reygent/config.json

Requires a .reygent/ directory. Run reygent init first if you haven't already.

Example agent grouping output:

── Development ──

Dev  developer
  Implementation agent for writing code
  Tools: read, write, edit
  Provider: claude
  Model:    claude-sonnet-4-5
? Configure Dev: (Use arrow keys)
❯ Keep current
  Customize
  Clear overrides

── Testing & Review ──

QE  quality-engineer
  Writes and runs functional tests
  Tools: read, write, bash
  Provider: claude
  Model:    claude-opus-4-6
? Configure QE: (Use arrow keys)
❯ Keep current
  Customize
  Clear overrides

── Planning ──

Planner  planner
  Creates implementation plans
  Tools: read, grep, glob
  Provider: claude
  Model:    claude-sonnet-4-5

Available Claude models:

Model ID	Label
`claude-sonnet-4-5-20250929`	Sonnet 4.5 (recommended)
`claude-opus-4-6`	Opus 4.6
`claude-haiku-4-5-20251001`	Haiku 4.5
`claude-sonnet-4-20250514`	Sonnet 4
`claude-3-5-sonnet-20241022`	3.5 Sonnet
`claude-3-5-haiku-20241022`	3.5 Haiku
`claude-3-opus-20240229`	3 Opus

Short aliases are supported (e.g., claude-sonnet-4-5 resolves to claude-sonnet-4-5-20250929).

Example:

bash

# Initialize, then configure
reygent init
reygent config

Per-agent overrides allow mixing providers — for example, use Claude for the dev agent but Gemini for the planner:

json

{
  "provider": "claude",
  "model": "claude-sonnet-4-5-20250929",
  "agents": [
    {
      "name": "planner",
      "provider": "gemini",
      "model": "gemini-2.5-pro",
      "..."
    }
  ]
}

For providers with no fixed model list (like OpenRouter), you'll be prompted to type a model ID instead of selecting from a list.

`reygent skills`

Manage skills from the reygent-skills registry.

`reygent skills list`

List all available skills in the registry.

bash

reygent skills list

Shows each skill's name, description, version, and license. Already-installed skills display an [installed] badge. Checks both local .reygent/skills/ and global ~/.reygent/skills/.

`reygent skills add <name>`

Install a skill from the registry.

bash

reygent skills add <name> [--global]

Argument/Option	Description
`name`	Skill name to install (e.g., `code-reviewer`)
`--global`	Install to `~/.reygent/skills/` instead of local `.reygent/skills/`

Examples:

bash

# Install to local project
reygent skills add code-reviewer

# Install globally (available to all projects)
reygent skills add code-reviewer --global

Checks compatibility with your reygent version before installing. Warns (but still installs) if the skill requires a newer version.

Requires a local .reygent/ directory for local installs. Run reygent init first, or use --global.

`reygent skills remove <name>`

Remove an installed skill.

bash

reygent skills remove <name> [--global]

Argument/Option	Description
`name`	Skill name to remove
`--global`	Remove from `~/.reygent/skills/` instead of local

Examples:

bash

reygent skills remove code-reviewer
reygent skills remove code-reviewer --global

`reygent telemetry`

Manage telemetry data and configuration. Telemetry captures workflow execution details, agent calls, costs, and errors to help debug failures and optimize workflows.

bash

reygent telemetry [command]

Defaults

When no telemetry block exists in .reygent/config.json, Reygent applies these defaults:

Field	Default	Notes
`enabled`	`undefined`	Triggers a one-time opt-in prompt on first interactive run. Use `enable`/`disable` to set explicitly.
`level`	`verbose`	Captures all events including `llm.request`, `llm.response`, `usage.tokens`, `performance.metric`, and `tool.invoke.full`. Override per-run with `--telemetry-level <minimal\|standard\|verbose>`.
`backend`	`sqlite`	Stored at `.reygent/chesstrace.db`.
`retention`	`30`	Days of events kept before pruning.

reygent telemetry enable and reygent telemetry disable only flip the enabled flag; if level, backend, or retention are missing they're written with the defaults above.

Subcommands

`reygent telemetry status`

Show telemetry configuration and storage status.

bash

reygent telemetry status

Displays:

Current telemetry level (minimal, standard, verbose)
Database location and size
Number of runs stored
Retention policy

`reygent telemetry runs`

List recent telemetry runs.

bash

reygent telemetry runs [--limit <count>] [--failed] [--successful]

Option	Description
`--limit <count>`	Max number of runs to show (default: 10)
`--failed`	Show only failed runs
`--successful`	Show only successful runs

Displays table with:

Run ID
Timestamp
Command
Status (success/failure)
Duration
Total cost

`reygent telemetry show <runId>`

Show detailed event log for a specific run.

bash

reygent telemetry show <runId>

Displays full event log including:

All agent calls with timestamps
Input/output tokens
Costs per agent
Errors and warnings
Stage transitions

`reygent telemetry export <runId>`

Export run data to JSON or CSV.

bash

reygent telemetry export <runId> [--format <type>] [--output <file>]

Option	Description
`--format <type>`	Export format: `json` or `csv` (default: `json`)
`--output <file>`	Output file path (default: stdout)

`reygent telemetry prune`

Delete old telemetry data.

bash

reygent telemetry prune [--older-than <days>] [--keep-count <count>]

Option	Description
`--older-than <days>`	Delete runs older than N days
`--keep-count <count>`	Keep only the N most recent runs

`reygent telemetry enable`

Enable telemetry in configuration.

bash

reygent telemetry enable

Sets telemetry.enabled = true in .reygent/config.json. If no telemetry block exists, one is created with the defaults from the Defaults table (level: verbose, backend: sqlite, retention: 30). Existing level, backend, and retention values are preserved.

Writes to the local config (.reygent/config.json) if found by walking up from the current directory; otherwise writes to the global config (~/.reygent/config.json).

`reygent telemetry disable`

Disable telemetry in configuration.

bash

reygent telemetry disable

Sets telemetry.enabled = false in .reygent/config.json. Same defaults and local/global scoping rules as enable — only the enabled flag changes; other fields are left as-is or seeded with defaults if missing.

`reygent analyze`

Analyze telemetry data for insights into failures, successes, costs, and performance.

bash

reygent analyze [command]

Subcommands

`reygent analyze failures`

Show common failure patterns from telemetry.

bash

reygent analyze failures [--limit <count>] [--since <date>]

Option	Description
`--limit <count>`	Max number of failures to analyze (default: 20)
`--since <date>`	Only analyze failures since date (ISO format)

Identifies:

Common error messages
Failing stages (unit tests, functional tests, security)
Agent-specific failures
Suggested fixes based on patterns

`reygent analyze success`

Extract patterns from successful runs.

bash

reygent analyze success [--limit <count>] [--since <date>]

Option	Description
`--limit <count>`	Max number of successful runs to analyze (default: 20)
`--since <date>`	Only analyze runs since date (ISO format)

Identifies:

Average completion time per stage
Token usage patterns
Cost efficiency metrics
Common spec characteristics

`reygent analyze costs`

Cost breakdown and optimization recommendations.

bash

reygent analyze costs [--since <date>] [--by-agent] [--by-stage]

Option	Description
`--since <date>`	Only analyze costs since date (ISO format)
`--by-agent`	Group costs by agent
`--by-stage`	Group costs by workflow stage

Shows:

Total cost breakdown
Cost per run (average, min, max)
Most expensive agents/stages
Token usage efficiency
Caching effectiveness (if supported by provider)
Recommendations for cost reduction

`reygent analyze agents`

Agent-specific performance breakdown.

bash

reygent analyze agents [--agent <name>] [--since <date>]

Option	Description
`--agent <name>`	Focus on specific agent (`dev`, `qe`, `planner`, etc.)
`--since <date>`	Only analyze runs since date (ISO format)

Shows per-agent:

Average duration
Token usage (input/output)
Cost per invocation
Success rate
Common failure modes

`reygent last`

Show details of the most recent run.

bash

reygent last [options]

Option	Description
`--verbose`	Show full event log with timestamps and details
`--output`	Show only the final output from the run
`--errors`	Show only errors from the run
`--json`	Output as JSON for machine parsing

Examples:

bash

# Quick summary of last run
reygent last

# Full event log with timestamps
reygent last --verbose

# Just show errors
reygent last --errors

# Get structured JSON (useful for scripts)
reygent last --json

Default output includes:

Run ID
Command
Status (success/failure)
Duration
Total cost
High-level summary of stages completed

`reygent knowledge`

Manage living documentation in .reygent/knowledge/. The knowledge system automatically learns from telemetry data to improve future runs. See docs/knowledge.md for full details.

bash

reygent knowledge [command]

Subcommands

`reygent knowledge list`

List all knowledge files.

bash

reygent knowledge list

Shows:

File names
File sizes
Last modified dates
Number of entries (for structured files)

`reygent knowledge show <file>`

Show specific knowledge file.

bash

reygent knowledge show <file>

Displays full contents of:

failures.md — documented failure patterns and solutions
patterns.md — successful workflow patterns
optimizations.md — performance and cost optimizations
Custom knowledge files

`reygent knowledge search <query>`

Search knowledge files for a query.

bash

reygent knowledge search <query>

Full-text search across all knowledge files. Highlights matches and shows surrounding context.

`reygent knowledge edit <file>`

Edit knowledge file in $EDITOR.

bash

reygent knowledge edit <file>

Opens specified knowledge file in your configured editor. Falls back to vi if $EDITOR not set.

`reygent knowledge add-failure`

Document a failure pattern interactively.

bash

reygent knowledge add-failure [--from-run <runId>]

Option	Description
`--from-run <runId>`	Pre-populate from a specific telemetry run

Interactive prompts:

Error pattern — what went wrong
Root cause — why it happened
Solution — how to fix it
Prevention — how to avoid it in future

Appends structured entry to .reygent/knowledge/failures.md.

`reygent knowledge add-pattern`

Document a success pattern interactively.

bash

reygent knowledge add-pattern [--from-run <runId>]

Option	Description
`--from-run <runId>`	Pre-populate from a specific telemetry run

Interactive prompts:

Pattern description — what worked well
Context — when to apply this pattern
Implementation — how to replicate
Benefits — why it's effective

Appends structured entry to .reygent/knowledge/patterns.md.

`reygent knowledge stats`

Show knowledge base statistics and effectiveness.

bash

reygent knowledge stats [--since <date>]

Option	Description
`--since <date>`	Only analyze effectiveness since date (ISO format)

Displays:

Total number of documented patterns/failures
Knowledge base growth over time
Success rate improvement (before/after knowledge addition)
Most referenced knowledge entries
Suggested knowledge gaps based on recent failures

Environment Variables

Set these in a .env file in your project root (or export in your shell).

Variable	Used For
`LINEAR_API_KEY`	Linear issue tracker integration
`JIRA_BASE_URL`	Jira instance URL (e.g., `https://company.atlassian.net`)
`JIRA_USERNAME`	Jira account email
`JIRA_TOKEN`	Jira API token
`GITHUB_TOKEN`	GitHub API authentication for `reygent skills` commands (raises rate limit from 60 to 5,000 req/hr)
`GIT_SSL_NO_VERIFY`	Skip SSL verification globally
`NODE_TLS_REJECT_UNAUTHORIZED`	Node.js TLS override (set to `0` to skip)

Commands Reference ​

Global Flags ​

reygent init ​

reygent generate-spec ​

reygent spec <source> ​

reygent agent [name] ​

reygent run ​

Reygent Workflow Stages ​

Interactive Prompts ​

reygent continue ​

reygent dashboard ​

Subcommands ​

reygent dashboard generate ​

reygent dashboard runs ​

reygent dashboard trends ​

reygent dashboard agent-failures ​

reygent dashboard run <runId> ​

reygent dashboard export ​

reygent review-work ​

reygent review-comments ​

reygent config ​

reygent skills ​

reygent skills list ​

reygent skills add <name> ​

reygent skills remove <name> ​

reygent telemetry ​

Defaults ​

Subcommands ​

reygent telemetry status ​

reygent telemetry runs ​

reygent telemetry show <runId> ​

reygent telemetry export <runId> ​

reygent telemetry prune ​

reygent telemetry enable ​

reygent telemetry disable ​

reygent analyze ​

Subcommands ​

reygent analyze failures ​

reygent analyze success ​

reygent analyze costs ​

reygent analyze agents ​

reygent last ​

reygent knowledge ​

Subcommands ​

reygent knowledge list ​

reygent knowledge show <file> ​

reygent knowledge search <query> ​

reygent knowledge edit <file> ​

reygent knowledge add-failure ​

reygent knowledge add-pattern ​

reygent knowledge stats ​

Environment Variables ​

Commands Reference

Global Flags

`reygent init`

`reygent generate-spec`

`reygent spec <source>`

`reygent agent [name]`

`reygent run`

Reygent Workflow Stages

Interactive Prompts

`reygent continue`

`reygent dashboard`

Subcommands

`reygent dashboard generate`

`reygent dashboard runs`

`reygent dashboard trends`

`reygent dashboard agent-failures`

`reygent dashboard run <runId>`

`reygent dashboard export`

`reygent review-work`

`reygent review-comments`

`reygent config`

`reygent skills`

`reygent skills list`

`reygent skills add <name>`

`reygent skills remove <name>`

`reygent telemetry`

Defaults

Subcommands

`reygent telemetry status`

`reygent telemetry runs`

`reygent telemetry show <runId>`

`reygent telemetry export <runId>`

`reygent telemetry prune`

`reygent telemetry enable`

`reygent telemetry disable`

`reygent analyze`

Subcommands

`reygent analyze failures`

`reygent analyze success`

`reygent analyze costs`

`reygent analyze agents`

`reygent last`

`reygent knowledge`

Subcommands

`reygent knowledge list`

`reygent knowledge show <file>`

`reygent knowledge search <query>`

`reygent knowledge edit <file>`

`reygent knowledge add-failure`

`reygent knowledge add-pattern`

`reygent knowledge stats`

Environment Variables