From 0b3e4ee2c00e910cf406dd3826f15c108536d290 Mon Sep 17 00:00:00 2001
From: Daniel Hofheinz <daniel@danielhofheinz.com>
Date: Wed, 8 Oct 2025 11:50:20 -0700
Subject: [PATCH] docs: add CLI options reference to README

---
 README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/README.md b/README.md
index 46045e83f..9199e1920 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,33 @@ Then just tell Codebuff what you want and it handles the rest:
 
 Codebuff will find the right files, makes changes across your codebase, and runs tests to make sure nothing breaks.
 
+### CLI Options
+
+Control how Codebuff runs with these flags:
+
+**Quality & Performance**:
+- `--lite` - Use budget models and fetch fewer files (faster, lower cost)
+- `--max` - Use higher quality models and fetch more files (thorough, slower)
+
+**Modes**:
+- `--ask` - Ask mode, won't change code (safe for exploration)
+- `--print, -p` - Print-only mode, run once and exit (for scripts/CI)
+
+**Agent Control**:
+- `--agent <id>` - Run specific agent (e.g., `--agent file-picker`)
+- `--spawn <id>` - Spawn agent directly (e.g., `--spawn reviewer`)
+- `--params <json>` - Pass JSON parameters to agent
+
+**Debugging**:
+- `--trace` - Log all subagent activity to `.agents/traces/*.log`
+- `--cwd <dir>` - Run in specific directory instead of current
+
+**Project Setup**:
+- `--init` - Initialize Codebuff for your project
+- `--create <template>` - Create new project from template
+
+Run `codebuff --help` for full details and examples.
+
 ## Create custom agents
 
 To get started building your own agents, run: