@tencent-ai/agent-sdk 0.3.98 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/cli-reference.md

@@ -0,0 +1,187 @@
+# 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*