CLI Reference

Chief provides a minimal but powerful CLI. All commands operate on the current working directory's .chief/ folder.

Usage

chief [command] [flags]

Available Commands:

Command	Description
(default)	Run the Ralph Loop on the active PRD
new	Create a new PRD in the current project
edit	Open the PRD for editing
status	Show current PRD progress
list	List all PRDs in the project

Commands

chief (default)

Launch the TUI dashboard for the active PRD. This opens Chief in Ready state—press s to start the Ralph Loop, which then reads your PRD, selects stories, and invokes Claude Code iteratively.

chief [name]

Arguments:

Argument	Description
name	PRD name to run (optional, auto-detects if omitted)

Flags:

Flag	Description	Default
--max-iterations <n>, -n	Maximum loop iterations	10
--no-sound	Disable completion sound	false
--verbose	Show raw Claude output in log	false

Examples:

# Run with auto-detected PRD
chief

# Run a specific PRD by name
chief auth-system

# Increase iteration limit for large PRDs
chief --max-iterations 200

# Combine flags
chief auth-system -n 50 --no-sound

TIP

If your project has only one PRD, Chief auto-detects it. Pass a name when you have multiple PRDs.

---

chief new

Create a new PRD in the current project. This command launches Claude Code with a preloaded prompt to help you define your project requirements interactively.

chief new

How it works:

1. Chief launches Claude Code with a specialized PRD-creation prompt
2. You describe your project, goals, and user stories conversationally
3. Claude helps structure your requirements and writes prd.md
4. When done, type /exit to leave Claude Code
5. Chief parses prd.md and generates prd.json

What it creates:

.chief/
└── prds/
    └── <name>/
        ├── prd.md       # Markdown PRD (written by Claude)
        └── prd.json     # Structured stories (generated by Chief)

Examples:

# Create a new PRD
chief new

# Claude Code opens - describe what you want to build
# Type /exit when done - Chief generates the PRD files

INFO

Run chief new from the root of your project. Chief creates the .chief/ directory if it doesn't exist.

---

chief edit

Open an existing PRD for editing via Claude Code.

chief edit

Launches Claude Code with your PRD loaded, allowing you to refine requirements, add stories, or update prd.md conversationally. When you /exit, Chief regenerates prd.json from the updated prd.md.

Arguments:

Argument	Description
name	PRD name to edit (optional, auto-detects if omitted)

Flags:

Flag	Description
--merge	Auto-merge progress on conversion conflicts
--force	Auto-overwrite on conversion conflicts

Examples:

# Edit the auto-detected PRD
chief edit

# Edit a specific PRD
chief edit auth-system

# Edit and auto-merge progress
chief edit auth-system --merge

---

chief status

Show progress for the current PRD. Displays a summary of story completion at a glance.

chief status

Output includes:

• Current PRD name
• Total number of stories
• Completed / In Progress / Pending counts
• Next story to be worked on

Examples:

# Check progress on the auto-detected PRD
chief status

# Example output:
#   PRD: auth-system
#   Stories: 8 total
#     ✓ 5 completed
#     → 1 in progress
#     ○ 2 pending
#   Next: US-006 - Password Reset Flow

---

chief list

List all PRDs in the current project.

chief list

Scans .chief/prds/ and shows each PRD with its completion status.

Examples:

# List all PRDs
chief list

# Example output:
#   auth-system    5/8 stories complete
#   landing-page   12/12 stories complete ✓
#   api-v2         0/6 stories complete

---

Keyboard Shortcuts (TUI)

When Chief is running, the TUI provides real-time feedback and interactive controls:

Loop Control

Key	Action
s	Start the loop (when Ready, Paused, Stopped, or Error)
p	Pause the loop (finishes current iteration gracefully)
x	Stop the loop immediately (kills Claude process)

View Switching

Key	Action
t	Toggle between Dashboard and Log views

PRD Management

Key	Action
n	Open PRD picker (switch PRDs or create new)
1-9	Quick switch to PRD tabs 1-9
e	Edit selected PRD (in picker)

Navigation

Key	Action
j / ↓	Move down (stories in Dashboard, scroll in Log)
k / ↑	Move up (stories in Dashboard, scroll in Log)
Ctrl+D	Page down (Log view)
Ctrl+U	Page up (Log view)
g	Jump to top (Log view)
G	Jump to bottom (Log view)

General

Key	Action
?	Show help overlay (context-aware)
Esc	Close modals/overlays
q	Quit (gracefully stops all loops)
Ctrl+C	Force quit

TIP

The TUI has two main views: Dashboard showing stories and progress, and Log view streaming Claude's output in real time. Press t to toggle between them.

Exit Codes

Chief uses standard exit codes:

Code	Meaning
0	Success
1	Error