# CLI Reference

> Complete reference manual for the CodeBuddy Code command-line tool, including all commands and parameter descriptions.

## CLI Commands

| Command                                | Description                                     | Example                                           |
| :------------------------------------- | :---------------------------------------------- | :------------------------------------------------ |
| `codebuddy`                            | Start interactive REPL                          | `codebuddy`                                       |
| `codebuddy "query"`                    | Start REPL with initial prompt                  | `codebuddy "explain this project"`                |
| `codebuddy -p "query"`                 | Query via SDK and exit                          | `codebuddy -p "explain this function"`            |
| `cat file \| codebuddy -p "query"`     | Process piped content                           | `cat logs.txt \| codebuddy -p "analyze logs"`     |
| `codebuddy -c`                         | Continue the most recent conversation           | `codebuddy -c`                                    |
| `codebuddy -c -p "query"`              | Continue conversation via SDK                   | `codebuddy -c -p "check for type errors"`         |
| `codebuddy -r "<session-id>" "query"`  | Resume session by ID                            | `codebuddy -r "abc123" "complete this MR"`        |
| `codebuddy update`                     | Update to the latest version                    | `codebuddy update`                                |
| `codebuddy mcp`                        | Configure Model Context Protocol (MCP) servers  | See [CodeBuddy Code MCP docs](./mcp.md)           |

## CLI Parameters

Command-line parameters to customize CodeBuddy Code behavior:

| Parameter                        | Description                                                                                                                       | Example                                                                                            |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `--add-dir`                      | Add additional working directories for CodeBuddy to access (validates each path for existence)                                    | `codebuddy --add-dir ../apps ../lib`                                                               |
| `--agents`                       | Dynamically define custom [Sub-Agents](./sub-agents.md) via JSON (format described below)                                        | `codebuddy --agents '{"reviewer":{"description":"Review code","prompt":"You are a code reviewer"}}'` |
| `--allowedTools`                 | List of tools allowed without prompting the user, in addition to [settings.json file](./settings.md)                             | `"Bash(git log:*)" "Bash(git diff:*)" "Read"`                                                      |
| `--disallowedTools`              | List of tools to disallow, in addition to [settings.json file](./settings.md)                                                    | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"`                                                      |
| `--tools`                        | Restrict available built-in tool set (whitelist). Empty string `""` disables all built-in tools, `"default"` uses all tools, or specify comma-separated tool names | `codebuddy --tools "Bash,Read,Edit"`                                                               |
| `--print`, `-p`                  | Print response and exit without entering interactive mode                                                                        | `codebuddy -p "query"`                                                                             |
| `--settings`                     | Load additional settings configuration from a JSON file or JSON string                                                           | `codebuddy --settings '{"model":"gpt-5"}' "query"`                                                 |
| `--setting-sources`              | Specify which settings sources to load, comma-separated (options: `user`, `project`, `local`). Default: `user,project,local`    | `codebuddy --setting-sources project,local "query"`                                                |
| `--system-prompt`                | Replace the entire system prompt with custom text (available in both interactive and print modes)                                | `codebuddy --system-prompt "You are a Python expert"`                                              |
| `--system-prompt-file`           | Load system prompt from file, replacing the default (print mode only)                                                            | `codebuddy -p --system-prompt-file ./custom-prompt.txt "query"`                                    |
| `--append-system-prompt`         | Append custom text to the end of the default system prompt (available in both interactive and print modes)                       | `codebuddy --append-system-prompt "Always use TypeScript"`                                         |
| `--output-format`                | Specify output format for print mode (options: `text`, `json`, `stream-json`)                                                    | `codebuddy -p "query" --output-format json`                                                        |
| `--input-format`                 | Specify input format for print mode (options: `text`, `stream-json`)                                                             | `codebuddy -p --output-format json --input-format stream-json`                                     |
| `--json-schema`                  | Validate structured output with JSON Schema. Example: `'{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}'` | `codebuddy -p --output-format json --json-schema '{"type":"object","properties":{...}}' "query"`    |
| `--include-partial-messages`     | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`)                                | `codebuddy -p --output-format stream-json --include-partial-messages "query"`                      |
| `--verbose`                      | Enable verbose logging, showing complete turn output (helpful for debugging in both print and interactive modes)                 | `codebuddy --verbose`                                                                              |
| `--max-turns`                    | Limit the number of agent turns in non-interactive mode                                                                          | `codebuddy -p --max-turns 3 "query"`                                                               |
| `--model`                        | Set the model for the current session using an alias, such as the latest model alias (`sonnet` or `opus`) or full model name    | `codebuddy --model gpt-5`                                                                          |
| `--text-to-image-model`          | Set the model ID for text-to-image generation                                                                                     | `codebuddy --text-to-image-model your-image-model`                                                 |
| `--image-to-image-model`         | Set the model ID for image-to-image generation                                                                                    | `codebuddy --image-to-image-model your-edit-model`                                                 |
| `--permission-mode`              | Start with specified [permission mode](./iam.md#permission-modes)                                                                | `codebuddy --permission-mode plan`                                                                 |
| `--permission-prompt-tool`       | Specify MCP tool to handle permission prompts in non-interactive mode                                                            | `codebuddy -p --permission-prompt-tool mcp_auth_tool "query"`                                      |
| `--resume`                       | Resume a specific session by ID, or select interactively in interactive mode                                                     | `codebuddy --resume abc123 "query"`                                                                |
| `--continue`                     | Load the most recent conversation in the current directory                                                                       | `codebuddy --continue`                                                                             |
| `-y` / `--dangerously-skip-permissions` | Skip permission prompts (use with caution)                                                                                       | `codebuddy -y` or `codebuddy --dangerously-skip-permissions`                                       |
| `--ide`                          | Automatically connect to IDE on startup (if exactly one valid IDE is available and has the current working directory open)       | `codebuddy --ide`                                                                                  |
| `--sandbox`                      | Run CodeBuddy in a sandbox (see [Sandbox Mode](#sandbox-mode-beta) below for details)                                            | `codebuddy --sandbox "analyze project"`                                                            |
| `--debug`                        | Enable debug mode with optional category filtering                                                                               | `codebuddy --debug`                                                                                |
| `--worktree [name]`              | Run in an isolated git worktree (see [Worktree documentation](./worktree.md))                                                    | `codebuddy --worktree` or `codebuddy --worktree my-feature`                                        |
| `--tmux`                         | Run in a tmux session (used together with `--worktree`)                                                                          | `codebuddy --worktree --tmux`                                                                      |

> **Important Note**: When using the `-p/--print` parameter for non-interactive execution, operations involving file reading/writing, command execution, network requests, etc. typically require adding the `-y` (or `--dangerously-skip-permissions`) parameter to execute, otherwise the operations will be blocked.

<Tip>
  The `--output-format json` parameter is particularly useful for scripting and automation, allowing you to programmatically parse CodeBuddy's responses.
</Tip>

### Agents Parameter Format

The `--agents` parameter accepts a JSON object defining one or more custom Sub-Agents. Each Sub-Agent requires a unique name (as the key) and a definition object containing the following fields:

| Field         | Required | Description                                                                                      |
| :------------ | :------- | :----------------------------------------------------------------------------------------------- |
| `description` | Yes      | Natural language description of when the Sub-Agent should be invoked                             |
| `prompt`      | Yes      | System prompt that guides the Sub-Agent's behavior                                               |
| `tools`       | No       | Array of specific tools the Sub-Agent can use (e.g., `["Read", "Edit", "Bash"]`). Omit to inherit all tools |
| `model`       | No       | Model alias to use: `sonnet`, `opus`, or `haiku`. Omit to use the default Sub-Agent model       |

Example:

```bash
codebuddy --agents '{
  "code-reviewer": {
    "description": "Professional code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging expert for errors and test failures.",
    "prompt": "You are a professional debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'
```

For more details on creating and using Sub-Agents, see the [Sub-Agents documentation](./sub-agents.md).

### System Prompt Parameters

CodeBuddy Code provides three parameters for customizing the system prompt, each with different purposes:

| Parameter                | Behavior                          | Modes                | Use Case                                                    |
| :----------------------- | :-------------------------------- | :------------------- | :---------------------------------------------------------- |
| `--system-prompt`        | **Replaces** entire default prompt | Interactive + Print | Complete control over CodeBuddy's behavior and instructions |
| `--system-prompt-file`   | **Replaces** with file content     | Print mode only     | Load prompts from file for reproducibility and version control |
| `--append-system-prompt` | **Appends** to default prompt      | Interactive + Print | Add specific instructions while retaining default CodeBuddy Code behavior |

**When to use:**

* **`--system-prompt`**: Use when you need complete control over CodeBuddy's system prompt. This removes all default CodeBuddy Code instructions, giving you a blank canvas.
  ```bash
  codebuddy --system-prompt "You are a Python expert who only writes code with type annotations"
  ```

* **`--system-prompt-file`**: Use when you want to load a custom prompt from a file, suitable for team consistency or version-controlled prompt templates.
  ```bash
  codebuddy -p --system-prompt-file ./prompts/code-review.txt "review this MR"
  ```

* **`--append-system-prompt`**: Use when you want to add specific instructions while retaining CodeBuddy Code's default functionality. This is the safest option for most use cases.
  ```bash
  codebuddy --append-system-prompt "Always use TypeScript and include JSDoc comments"
  ```

<Note>
  `--system-prompt` and `--system-prompt-file` are mutually exclusive. You cannot use both parameters simultaneously.
</Note>

<Tip>
  For most use cases, `--append-system-prompt` is recommended as it preserves CodeBuddy Code's built-in functionality while adding custom requirements. Only use `--system-prompt` or `--system-prompt-file` when complete control over the system prompt is needed.
</Tip>

## Sandbox Mode (Beta)

> **Beta Feature**: The Sandbox functionality is currently in Beta.
>
> **Detailed Documentation**: See the [Sandboxing Guide](./sandboxing.md) for complete sandbox usage instructions, best practices, and troubleshooting.

### Sandbox Parameters

```bash
--sandbox [url]                       Run CodeBuddy in a sandbox:
                                      - Without argument or "container": Use container (Docker/Podman)
                                      - Provide full E2B API URL: Use cloud sandbox
--sandbox-upload-dir                  Upload current working directory to sandbox (E2B only)
--sandbox-new                         Force creation of new sandbox (ignore cached sandbox)
--sandbox-id <id>                     Connect to specified sandbox ID or alias
--sandbox-kill                        Terminate sandbox on exit (default: keep running for reuse)
--teleport <value>                    Teleport mode: Connect to remotely created sandbox
```

### Sandbox Usage Examples

```bash
# Container sandbox (Docker/Podman, auto-mount current directory)
codebuddy --sandbox "analyze this project"

# E2B cloud sandbox (auto-reuse)
codebuddy --sandbox https://api.e2b.dev "create Python web app"

# Force creation of new sandbox
codebuddy --sandbox --sandbox-new "start from scratch"

# Connect to specified sandbox
codebuddy --sandbox --sandbox-id sb_abc123 "continue work"

# Clean up sandbox on exit
codebuddy --sandbox --sandbox-kill "temporary test"

# Teleport mode - Connect to remotely created sandbox
codebuddy --teleport session_abc123XYZ4567890 "connect to remote sandbox"
```

### Sandbox Environment Variables

```bash
E2B_API_KEY                          E2B API key (required for E2B sandbox)
E2B_TEMPLATE                         E2B template ID (default: base)
CODEBUDDY_SANDBOX_IMAGE              Custom Docker image (container sandbox)
```

## Next Steps

After mastering CLI commands, you can:

- **[Learn Interactive Mode](./interactive-mode.md)** - Master keyboard shortcuts and tips
- **[Explore Slash Commands](./slash-commands.md)** - Learn about built-in commands
- **[Skills System](./skills.md)** - Extend AI professional capabilities
- **[Learn MCP Integration](./mcp.md)** - Extend tool capabilities

---

*Precise command-line operations are the foundation of efficient development*
