Command | Description | Example |
codebuddy | Start interactive REPL. | codebuddy |
codebuddy "query" | Start REPL with an initial prompt. | codebuddy "explain this project" |
codebuddy -p "query" | Query through 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 through SDK. | codebuddy -c -p "check 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) server. | |
codebuddy agents [--json] | List all configured subagents grouped by source. | codebuddy agents --json |
codebuddy daemon start | Start the Daemon process. | codebuddy daemon start --port 8080 |
codebuddy daemon stop | Stop Daemon. | codebuddy daemon stop |
codebuddy daemon status | View Daemon status. | codebuddy daemon status |
codebuddy daemon restart | Restart Daemon. | codebuddy daemon restart |
codebuddy daemon install | Register as a system service (auto-start on login). | codebuddy daemon install --port 8080 |
codebuddy daemon uninstall | Remove system service registration. | codebuddy daemon uninstall |
codebuddy auto-mode defaults | Print built-in classification rules for auto mode. | codebuddy auto-mode defaults |
codebuddy auto-mode config | Print the currently active auto mode configuration. | codebuddy auto-mode config |
codebuddy auto-mode critique | Review your custom auto rules with the lite model. | codebuddy auto-mode critique |
codebuddy ps | List all active Worker processes. | codebuddy ps |
codebuddy logs <pid|name> | View Worker logs. | codebuddy logs feature-x |
codebuddy attach <pid|name> | Attach to background Worker. | codebuddy attach feature-x |
codebuddy kill <pid|name> | Terminate Worker process. | codebuddy kill feature-x |
Parameter | Description | Example |
--add-dir | Add extra working directories for CodeBuddy to access (verify that each path exists). | codebuddy --add-dir ../apps ../lib |
--agent | Specifies the agent name used for the current session (built-in or custom agent), with a higher priority than the agent setting in settings.json. | codebuddy --agent my-reviewer |
--agents | codebuddy --agents '{"reviewer":{"description":"Review code","prompt":"You are a code reviewer"}}' | |
--allowedTools | List of tools that can be allowed without prompting the user, in addition to those in the settings.json file | "Bash(git log:*)" "Bash(git diff:*)" "Read" |
--disallowedTools | List of tools that should be disallowed, in addition to those in the settings.json file | "Bash(git log:*)" "Bash(git diff:*)" "Edit" |
--tools | Limit the available built-in tool set (allowlist). An empty string "" disables all built-in tools, "default" uses all tools, or specify comma-separated tool names. Supports Defer(X) / NoDefer(X) modifiers to adjust the deferred loading state of tools as needed. For details, see Tool Deferred Loading Override. | codebuddy --tools "Bash,Read,Defer(Glob)" |
--mcp-config <fileOrString> | Load MCP server configuration from a JSON file or JSON string. | codebuddy --mcp-config ./mcp.json |
--strict-mcp-config | Use only MCP servers provided by --mcp-config or SDK mcpServers, and ignore file-based configurations such as user, project, and local .mcp.json files. If not explicitly passed, interactive mode, --serve, and ACP will continue to load these file-based configurations. | codebuddy --serve --strict-mcp-config |
--no-session-persistence | Keep session context only in memory without creating or updating local transcripts. Existing sessions can still be loaded in read-only mode. | codebuddy --serve --no-session-persistence |
--print, -p | Print the response and exit without entering interactive mode. | codebuddy -p "query" |
--settings | Load additional settings from a JSON file or JSON string. | codebuddy --settings '{"model":"gpt-5"}' "query" |
--setting-sources | Specify the setting sources to load, separated by commas (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 the system prompt from a file to replace the default prompt (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 the output format for print mode (options: text, json, stream-json). | codebuddy -p "query" --output-format json |
--input-format | Specify the 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 the output (requires --print and --output-format=stream-json). | codebuddy -p --output-format stream-json --include-partial-messages "query" |
--verbose | Enable verbose logging to display 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 alias of the latest model ( sonnet or opus) or the full model name. | codebuddy --model gpt-5 |
--text-to-image-model | Set the model ID used by the text-to-image feature. | codebuddy --text-to-image-model your-image-model |
--image-to-image-model | Set the model ID used by the image-to-image feature. | codebuddy --image-to-image-model your-edit-model |
--permission-mode | Start with the specified permission mode. Common values: default, acceptEdits, auto, dontAsk, plan, bypassPermissions | codebuddy --permission-mode auto |
--subagent-permission-mode | Set the default permission mode for subagents/team members, overriding the mode inherited from the main session. Supports acceptEdits, default, plan, auto, dontAsk, bypassPermissions | codebuddy --subagent-permission-mode dontAsk |
--permission-prompt-tool | Specify the MCP tool for handling permission prompts in non-interactive mode. | codebuddy -p --permission-prompt-tool mcp_auth_tool "query" |
--resume | Resume a specific session by ID, or select one 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 the IDE at startup if exactly one valid IDE is available and has the current working directory open. | codebuddy --ide |
--sandbox | Run CodeBuddy in a sandbox. For details, see Sandbox Mode below. | codebuddy --sandbox "Analyze project" |
--debug | Enable debug mode with optional category filtering. | codebuddy --debug |
--worktree [name] | codebuddy --worktree or codebuddy --worktree my-feature | |
--tmux | Run in a tmux session (used with --worktree). | codebuddy --worktree --tmux |
--plugin-dir <dirs...> | Load plugins from local directories for development or testing. Multiple paths can be specified. For details, see the plugin documentation. | codebuddy --plugin-dir ./my-plugin ../other-plugin |
--bg | Run the session in the background in detached mode, with logs written to ~/.codebuddy/logs/. For details, see the Daemon documentation. | codebuddy --bg "Implement login page" |
--name <name> | Background session name (used with --bg for easy lookup via ps/logs/kill) | codebuddy --bg --name feature-x "Implement feature" |
--serve | Start the HTTP service, including the Web UI, REST API, and ACP protocol. | codebuddy --serve --port 8080 |
--prewarm | Start in prewarm standby mode: complete startup initialization, then suspend and wait for external wake-up via IPC. The working directory is bound only upon wake-up. This mode eliminates cold-start latency when sessions are launched. Disabled by default. | codebuddy --prewarm --prewarm-id pool1 |
--prewarm-id <id> | Prewarm IPC endpoint identifier, which defaults to the process PID and is used to construct the local socket/pipe address. Use it with the cbc-prewarm management command. | codebuddy --prewarm --prewarm-id pool1 |
-p/--print is used for non-interactive execution, operations involving file read/write, command execution, and network requests must have an explicit permission policy: the most common options are -y / --dangerously-skip-permissions, or you can use --permission-mode auto, --permission-mode dontAsk, preconfigured permissions.allow rules, or a dedicated permission-prompting MCP tool. Otherwise, operations requiring manual confirmation will be blocked.--output-format json parameter is particularly useful for scripting and automation, allowing you to parse CodeBuddy responses programmatically.--agents parameter accepts a JSON object that defines 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 subagent should be invoked |
prompt | Yes | System prompt that guides subagent behavior |
tools | No | Array of specific tools that the subagent can use (such as ["Read", "Edit", "Bash"]). If the array is omitted, all tools are inherited. |
disallowedTools | No | Array of tools disallowed for the subagent (blocklist), which takes effect as the union with the session-level --disallowedTools. |
model | No | A model ID, name, or alias, a scenario variant lite / reasoning, or inherit / default. When the value is omitted or set to inherit / default, the model continues to be selected through the normal subagent resolution chain. |
effort | No | Reasoning effort: minimal / low / medium / high / xhigh / max. If the reasoning effort is omitted, the session effort is inherited. |
maxTurns | No | Maximum execution turns of the subagent (a positive integer). Priority: env CODEBUDDY_CODE_SUBAGENT_MAX_TURNS > the max_turns parameter of the Agent tool > this field. |
background | No | When set to true, the subagent always runs in the background (equivalent to run_in_background: true). |
initialPrompt | No | When this agent runs as the main session agent ( --agent or the settings agent), it is automatically prefixed to the first user message. |
memory | No |
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": "lite"},"debugger": {"description": "Debugging expert for errors and test failures.","prompt": "You are a professional debugger. Analyze errors, identify root causes, and provide fixes."}}'
Parameter | Action | Mode | Scenario |
--system-prompt | Replace the entire default prompt | Interactive + Print Mode | Fully control CodeBuddy behavior and instructions |
--system-prompt-file | Replace with file content | Print-only Mode | Load prompts from a file to ensure reproducibility and version control |
--append-system-prompt | Append to the default prompt | Interactive + Print Mode | Add specific instructions while preserving default CodeBuddy Code behavior. |
--system-prompt: Use when you need full control over CodeBuddy's system prompt. This removes all default CodeBuddy Code instructions, giving you a blank canvas.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 prompt templates that require team consistency or version control.codebuddy -p --system-prompt-file ./prompts/code-review.txt "Review this MR"
--append-system-prompt: Use when you want to add specific instructions while preserving CodeBuddy Code's default functionality. This is the safest option for most use cases.codebuddy --append-system-prompt "Always use TypeScript and include JSDoc comments"
--system-prompt and --system-prompt-file are mutually exclusive. You cannot use both parameters at the same time.--append-system-prompt is recommended because it preserves CodeBuddy Code's built-in functionality while adding custom requirements. Use --system-prompt or --system-prompt-file only when you need full control over the system prompt.--sandbox [url] Run CodeBuddy in a sandbox:- Without an argument or with "container": use a container (Docker/Podman)- Provide the full E2B API URL: use a cloud sandbox--sandbox-upload-dir Upload the current working directory to the sandbox (E2B only)--sandbox-new Force the creation of a new sandbox (ignore the cached sandbox)--sandbox-id <id> Connect to the specified sandbox ID or alias--sandbox-kill Terminate the sandbox on exit (default: keep it running for reuse)--teleport <value> Teleport mode: connect to a remotely created sandbox
# Container Sandbox (Docker/Podman, automatically mounts the current directory)codebuddy --sandbox "Analyze this project"# E2B Cloud Sandbox (automatically reused)codebuddy --sandbox https://api.e2b.dev "Create a Python web app"# Force the Creation of a New Sandboxcodebuddy --sandbox --sandbox-new "Start from scratch"# Connect to a Specified Sandboxcodebuddy --sandbox --sandbox-id sb_abc123 "Continue working"# Clean Up the Sandbox on Exitcodebuddy --sandbox --sandbox-kill "Temporary test"# Teleport Mode - Connect to a Remotely Created Sandboxcodebuddy --teleport session_abc123XYZ4567890 "Connect to the remote sandbox"
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)
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback