CLI

Full command reference for ralphy-spec.

Quick start

npx ralphy-spec init
ralphy-spec run --dry-run
ralphy-spec run
ralphy-spec status
ralphy-spec budget --json

Commands

ralphy-spec init [--dir <path>] [--tools <cursor,claude-code,opencode>] [--force]
ralphy-spec update [--dir <path>] [--tools <cursor,claude-code,opencode>] [--force]

ralphy-spec validate [--dir <path>] [--tools <cursor,claude-code,opencode>]
ralphy-spec validate --task <taskId> [--dir <path>]

ralphy-spec run [--backend <cursor|opencode|claude-code|noop>] [--workspace <worktree|patch>]
              [--artifact-dir <dir>] [--task <taskId>] [--no-stream-backend] [--dry-run] [--json]

ralphy-spec status [--json]
ralphy-spec budget [--json]
ralphy-spec report [--out <filepath>] [--json]
ralphy-spec tail [--interval-ms <n>]

ralphy-spec checkpoint --task <taskId> --message <message>

Essential user journey

  1. Initialize: ralphy-spec init
  2. Describe work in openspec/project.yml (tasks, validators, budgets, sprint)
  3. Dry-run: ralphy-spec run --dry-run (safe)
  4. Run: ralphy-spec run
  5. Observe: status/tail/budget/report

Backend notes

  • Cursor: --backend cursor uses Cursor Agent. Run cursor agent login (or set CURSOR_API_KEY) before running ralphy-spec run.

Logs & artifacts

  • ralphy-spec/STATUS.md: live status snapshot (updates during a run)
  • ralphy-spec/runs/<runId>.md: immutable run log after completion
  • ralphy-spec/logs/<runId>/...: backend transcripts (stdout/stderr + metadata)

Useful links