Merge pull request #3219 from Kilo-Org/melanie/docs-kilocode-cli

Pulls in richer documentation for autonomous mode and new CLI features

apps/kilocode-docs/docs/cli.md

@@ -8,18 +8,25 @@ The Kilo Code CLI uses the same underlying technology that powers the IDE extens
 
 `npm install -g @kilocode/cli`
 
-Next, `cd` to change directories into the project where you'd like to work with Kilo.
+Change directory to where you want to work and run kilocode:
 
-Run:
+```
+# Start interactive chat session
+kilocode
 
-`kilocode`
+# Start with a specific mode
+kilocode --mode architect
+
+# Start with a specific workspace
+kilocode --workspace /path/to/project
+```
 
 to start the CLI and begin a new task with your preferred model and relevant mode.
 
 ## What you can do with Kilo Code CLI
 
 - **Plan and execute code changes without leaving your terminal.** Use your command line to make edits to your project without opening your IDE.
-- **Switch between 400+ LLMs without constraints.** Other CLI tools only work with one model or curate opinionated lists. With Kilo, you can switch between hundreds of models without booting up another tool.
+- **Switch between hundreds of LLMs without constraints.** Other CLI tools only work with one model or curate opinionated lists. With Kilo, you can switch models without booting up another tool.
 - **Choose the right mode for the task in your workflow.** Select between Architect, Ask, Debug, Orchestrator, or custom agent modes.
 - **Automate tasks.** Get AI assistance writing shell scripts for tasks like renaming all of the files in a folder or transforming sizes for a set of images.
 
@@ -39,12 +46,6 @@ to start the CLI and begin a new task with your preferred model and relevant mod
 | `/help`         | List available commands and how to use them                      |                             |
 | `/exit`         | Exit the CLI                                                     |                             |
 
-### CLI flags
-
-| Flag     | Description                                                                                           | Example |
-| -------- | ----------------------------------------------------------------------------------------------------- | ------- |
-| `--auto` | Prompts the AI agents to work autonomously without interaction or user input until a task is complete |         |
-
 ## Config reference for providers
 
 Kilo gives you the ability to bring your own keys for a number of model providers and AI gateways, like OpenRouter and Vercel AI Gateway. Each provider has unique configuration options and some let you set environment variables.
@@ -54,3 +55,170 @@ You can reference the [Provider Configuration Guide](https://github.com/Kilo-Org
 `kilocode config`
 
 to complete configuration with an interactive workflow on the command line.
+
+## Autonomous mode (Non-Interactive)
+
+Autonomous mode allows Kilo Code to run in automated environments like CI/CD pipelines without requiring user interaction.
+
+```bash
+# Run in autonomous mode with a prompt
+kilocode --auto "Implement feature X"
+
+# Run in autonomous mode with piped input
+echo "Fix the bug in app.ts" | kilocode --auto
+
+# Run in autonomous mode with timeout (in seconds)
+kilocode --auto "Run tests" --timeout 300
+```
+
+### Autonomous Mode Behavior
+
+When running in Autonomous mode (`--auto` flag):
+
+1. **No User Interaction**: All approval requests are handled automatically based on configuration
+2. **Auto-Approval/Rejection**: Operations are approved or rejected based on your auto-approval settings
+3. **Follow-up Questions**: Automatically responded with a message instructing the AI to make autonomous decisions
+4. **Automatic Exit**: The CLI exits automatically when the task completes or times out
+
+### Auto-Approval Configuration
+
+Autonomous mode respects your auto-approval configuration. Edit your config file with `kilocode config` to customize:
+
+```json
+{
+	"autoApproval": {
+		"enabled": true,
+		"read": {
+			"enabled": true,
+			"outside": true
+		},
+		"write": {
+			"enabled": true,
+			"outside": false,
+			"protected": false
+		},
+		"execute": {
+			"enabled": true,
+			"allowed": ["npm", "git", "pnpm"],
+			"denied": ["rm -rf", "sudo"]
+		},
+		"browser": {
+			"enabled": false
+		},
+		"mcp": {
+			"enabled": true
+		},
+		"mode": {
+			"enabled": true
+		},
+		"subtasks": {
+			"enabled": true
+		},
+		"question": {
+			"enabled": false,
+			"timeout": 60
+		},
+		"retry": {
+			"enabled": true,
+			"delay": 10
+		},
+		"todo": {
+			"enabled": true
+		}
+	}
+}
+```
+
+**Configuration Options:**
+
+- `read`: Auto-approve file read operations
+    - `outside`: Allow reading files outside workspace
+- `write`: Auto-approve file write operations
+    - `outside`: Allow writing files outside workspace
+    - `protected`: Allow writing to protected files (e.g., package.json)
+- `execute`: Auto-approve command execution
+    - `allowed`: List of allowed command patterns (e.g., ["npm", "git"])
+    - `denied`: List of denied command patterns (takes precedence)
+- `browser`: Auto-approve browser operations
+- `mcp`: Auto-approve MCP tool usage
+- `mode`: Auto-approve mode switching
+- `subtasks`: Auto-approve subtask creation
+- `question`: Auto-approve follow-up questions
+- `retry`: Auto-approve API retry requests
+- `todo`: Auto-approve todo list updates
+
+### Command Approval Patterns
+
+The `execute.allowed` and `execute.denied` lists support hierarchical pattern matching:
+
+- **Base command**: `"git"` matches any git command (e.g., `git status`, `git commit`, `git push`)
+- **Command + subcommand**: `"git status"` matches any git status command (e.g., `git status --short`, `git status -v`)
+- **Full command**: `"git status --short"` only matches exactly `git status --short`
+
+**Example:**
+
+```json
+{
+	"execute": {
+		"enabled": true,
+		"allowed": [
+			"npm", // Allows all npm commands
+			"git status", // Allows all git status commands
+			"ls -la" // Only allows exactly "ls -la"
+		],
+		"denied": [
+			"git push --force" // Denies this specific command even if "git" is allowed
+		]
+	}
+}
+```
+
+### Interactive Command Approval
+
+When running in interactive mode, command approval requests now show hierarchical options:
+
+```
+[!] Action Required:
+> ✓ Run Command (y)
+  ✓ Always run git (1)
+  ✓ Always run git status (2)
+  ✓ Always run git status --short --branch (3)
+  ✗ Reject (n)
+```
+
+Selecting an "Always run" option will:
+
+1. Approve and execute the current command
+2. Add the pattern to your `execute.allowed` list in the config
+3. Auto-approve matching commands in the future
+
+This allows you to progressively build your auto-approval rules without manually editing the config file.
+
+### Autonomous Mode Follow-up Questions
+
+In Autonomous mode, when the AI asks a follow-up question, it receives this response:
+
+> "This process is running in non-interactive Autonomous mode. The user cannot make decisions, so you should make the decision autonomously."
+
+This instructs the AI to proceed without user input.
+
+### Exit Codes
+
+- `0`: Success (task completed)
+- `124`: Timeout (task exceeded time limit)
+- `1`: Error (initialization or execution failure)
+
+### Example CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Run Kilo Code
+  run: |
+      echo "Implement the new feature" | kilocode --auto --timeout 600
+```
+
+## Local Development
+
+### DevTools
+
+In order to run the CLI with devtools, add `DEV=true` to your `pnpm start` command, and then run `npx react-devtools` to show the devtools inspector.