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
update	Update Chief to the latest version

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 the agent 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	Dynamic
--no-retry	Disable auto-retry on agent crashes	false
--verbose	Show raw agent 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 --verbose

Dynamic iteration limit

When --max-iterations is not specified, Chief calculates a dynamic limit based on the number of remaining stories plus a buffer. You can adjust the limit at runtime with +/- in the TUI.

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 the agent CLI with a preloaded prompt to help you define your project requirements interactively.

chief new [name] [context]

Arguments:

Argument	Description
name	PRD name (optional, defaults to main). Must contain only letters, numbers, hyphens, and underscores.
context	Additional context to pass to the agent (optional). Included in the PRD creation prompt.

How it works:

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

What it creates:

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

Examples:

# Create a new PRD (defaults to name "main")
chief new

# Create a named PRD
chief new auth-system

# Create a PRD with additional context
chief new auth-system "We use Express.js with JWT tokens"

# The agent 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 the agent CLI.

chief edit

Launches the agent 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

---

chief update

Update Chief to the latest version. Downloads and installs the newest release from GitHub.

chief update

Chief checks the GitHub releases API, compares your current version to the latest, and downloads the appropriate binary for your platform if an update is available.

Examples:

# Update to latest version
chief update

# Example output:
#   Checking for updates...
#   Downloading v0.5.2 (you have v0.4.0)...
#   Updated to v0.5.2.

Automatic update check

Chief performs a non-blocking version check every time you launch the TUI. If a newer version is available, you'll see a message like:

Chief v0.5.2 available (you have v0.5.1). Run 'chief update' to upgrade.

---

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 agent process)

View Switching

Key	Action
t	Toggle between Dashboard and Log views
d	Toggle Diff view (shows the selected story's commit diff)

PRD Management

Key	Action
n	Open PRD picker in create mode (switch PRDs or create new)
l	Open PRD picker in selection mode (switch between existing PRDs)
1-9	Quick switch to PRD tabs 1-9
e	Edit current PRD (from any main view)
m	Merge completed PRD's branch into main (in picker or completion screen)
c	Clean worktree and optionally delete branch (in picker or completion screen)

Settings

Key	Action
,	Open Settings overlay (from any view)

Navigation

Key	Action
j / ↓	Move down (stories in Dashboard, scroll in Log/Diff)
k / ↑	Move up (stories in Dashboard, scroll in Log/Diff)
Ctrl+D / PgDn	Page down (Log/Diff view)
Ctrl+U / PgUp	Page up (Log/Diff view)
g	Jump to top (Log/Diff view)
G	Jump to bottom (Log/Diff view)
+ / =	Increase max iterations by 5
- / _	Decrease max iterations by 5

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 three views: Dashboard showing stories and progress, Log streaming the agent's output in real time, and Diff showing the commit diff for the selected story. Press t to toggle Dashboard/Log, or d to open the Diff view.

Exit Codes

Chief uses standard exit codes:

Code	Meaning
0	Success
1	Error