CLI Reference

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

For startup troubleshooting, use codebuddy --startup-prof-md to generate Markdown and JSON reports automatically when startup is ready. The current session does not need to exit. See Startup Profiling for usage.

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
codebuddy project purge [path]	Remove local project state (transcripts, tasks, logs, history, and more)	codebuddy project purge ~/work/repo --dry-run
codebuddy agents [--json]	List all configured sub-agents grouped by source	codebuddy agents --json
codebuddy daemon start	Start the Daemon process	codebuddy daemon start --port 8080
codebuddy daemon stop	Stop the Daemon	codebuddy daemon stop
codebuddy daemon status	View Daemon status	codebuddy daemon status
codebuddy daemon restart	Restart the 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 the 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	Use a lite model to critique your custom auto rules	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 a background Worker	codebuddy attach feature-x
codebuddy kill <pid|name>	Terminate a Worker process	codebuddy kill feature-x

Purging Local Project Data

codebuddy project purge [path] removes the runtime state that CodeBuddy stores locally for a project. When [path] is omitted, an interactive terminal first opens a project selector. Pass --all to remove local state for all projects.

Common Options

Option	Description
[path]	Specify the project path to purge; omit it to select a project in an interactive terminal
--dry-run	Preview the purge plan without deleting anything
-y, --yes	Skip the final confirmation and delete immediately
-i, --interactive	Confirm deletion for each cleanup category
--all	Remove local state for all projects
-h, --help	Print command usage

Constraints: -i/--interactive cannot be used together with --all. Interactive confirmation covers at most four logical categories: Project state, Prompt history, Project configuration, and Project trust. Within each category, underlying targets are still deleted individually and safely. The project selector and category-by-category confirmation are available only in the full interactive CLI. In headless environments, explicitly pass [path] or --all. Actual deletion in a non-TTY environment also requires --yes; you can use --dry-run first to preview the plan.

What Single-Project Mode Removes

• Transcripts whose ownership of the project has been verified, related sub-agent transcript artifacts, task lists, debug logs, file edit history, and file rollback sidecars
• Input history lines belonging to the project in ~/.codebuddy/history.jsonl
• The project's projects[<path>] configuration in ~/.codebuddy.json
• Matching trustedDirectories rules in ~/.codebuddy/settings.json

Safety boundary: To prevent accidental deletion, single-project mode removes only data that can be reliably attributed to the project. It conservatively skips and warns about legacy project memory directories inferred only from compressed paths, unverified project directories, and anomalous sessions whose names collide with project-level memory, sessions, or storage.json state.

What --all Removes in Addition

• All project state under ~/.codebuddy/projects/
• All session task lists, file edit history, debug logs, and history.jsonl
• All project-level configuration entries in ~/.codebuddy.json
• All project trust rules in ~/.codebuddy/settings.json
• Legacy project memory directories, while preserving ~/.codebuddy/memories/global/

Examples

# Preview what would be removed for the current project
codebuddy project purge --dry-run

# Purge the specified project and skip the final confirmation
codebuddy project purge ~/work/repo --yes

# Confirm each cleanup category in the specified project's purge plan
codebuddy project purge ~/work/repo --interactive

# Preview local state cleanup for all projects
codebuddy project purge --all --dry-run

project purge removes only local CodeBuddy state. It does not modify your project's source repository, delete global MCP server configuration, or remove global memories under ~/.codebuddy/memories/global/.

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
--agent	Main Agent for new sessions in this process (TUI / --serve Web / ACP). Built-in: cli, ptc, minimal, create, or a custom agent name. multitask is not a standing mode; it only enables the overlay (tool calls go through the coordinator while the picker identity remains the current mode). The Minimal standing mode cannot enable the overlay. Overrides codebuddy.mainAgent.lastUsed; does not write codebuddy.mainAgent.default or settings agent. Pass cli explicitly for Standard. In the TUI, use /agent-mode to switch modes (blank sessions only). multitask is interactive TUI only (stdout and stdin must be TTYs); mutually exclusive with -p / stream-json / --acp / --serve / piped stdin — process exits non-zero. ACP hosts should use session/set_config_option (configId=multitask). Cheat sheet: Web UI	codebuddy --agent multitask
--multitask	Normalized to --agent multitask, then enables the overlay and runs through the same entry guard. Does not change the current mode. The Minimal standing mode does not receive the overlay. Explicit --multitask wins over any other --agent. Interactive TUI only	codebuddy --multitask
--agents	Dynamically define custom Sub-Agents 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	"Bash(git log:*)" "Bash(git diff:*)" "Read"
--disallowedTools	List of tools to disallow, in addition to settings.json file	"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. Supports Defer(X) / NoDefer(X) modifiers to adjust tool deferred loading status on demand; 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	Only use MCP explicitly provided through --mcp-config or the SDK, ignoring Plugin MCP and user, project, and local configurations. Explicit --agents / SDK Agents retain only inline MCP objects; string references by name are still ignored. When this option is not passed, all regular sources continue to load	codebuddy --serve --strict-mcp-config
--no-session-persistence	Keep session context in memory only, without creating or updating local transcripts; existing sessions can still be loaded read-only, and this does not affect user-message echoing already enabled by --replay-user-messages in stream-json mode	codebuddy --serve --no-session-persistence
--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
--brief	Enable the SendUserMessage tool so the agent can send user-facing messages (also CODEBUDDY_BRIEF); the tool is hidden when off	codebuddy --brief "implement the login page"
--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
--autocompact	Auto-compact window size: auto follows the model window, or a token count (e.g. 400000, 400k, 1m; clamped to 100k–1M)	codebuddy --autocompact 400k
--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	Default permission mode for new sessions in this process. Help lists 6: default, acceptEdits, auto, dontAsk, plan, bypassPermissions; runtime also accepts fullAccess. --serve Web stamps this on new chats; does not write an unchanged startup value to permissions.defaultMode. Do not pair minimal with plan. Cheat sheet: Web UI	codebuddy --serve --permission-mode bypassPermissions
--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 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 most permission prompts (use with caution). This is not a true full pass: HIGH/CRITICAL commands may still require confirmation in interactive mode. In an isolated sandbox, set the process environment variable CODEBUDDY_IS_SANDBOX=1 together with this option to skip those confirmations. Full permission bypass is high risk, so it is intentionally an environment variable rather than a CLI argument. See Sandbox full pass (high risk)	codebuddy -y or export CODEBUDDY_IS_SANDBOX=1 && codebuddy -y
--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 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)	codebuddy --worktree or codebuddy --worktree my-feature
--tmux	Run in a tmux session (used together with --worktree)	codebuddy --worktree --tmux
--plugin-dir <dirs...>	Load plugins from local directories (for development/testing), multiple paths supported. See Plugin documentation	codebuddy --plugin-dir ./my-plugin ../other-plugin
--bg	Run the session in the background (on Windows, it still exits with its owning CLI), with logs written to ~/.codebuddy/logs/. See Daemon documentation	codebuddy --bg "implement login page"
--name <name>	Background session name (used with --bg, makes it easy to find via ps/logs/kill)	codebuddy --bg --name feature-x "implement feature"
--serve	Start the HTTP server (Web UI, REST API, ACP). Without --acp, ACP uses HTTP SSE and does not write session/update to process stdout	codebuddy --serve --port 8080
--port <number>	HTTP listen port (--serve only). Auto-assigned by default	codebuddy --serve --port 7890
--host <string>	HTTP bind address (--serve only). Default 127.0.0.1; non-loopback forces auth unless --auth none	codebuddy --serve --host 0.0.0.0
--auth <mode>	--serve auth: password (default) or none. CODEBUDDY_GATEWAY_AUTH wins. --auth none can override non-loopback forceAuth	codebuddy --serve --auth none
--base-path <path>	Public path prefix for the --serve Web UI (e.g. /cnb-5gg-1k09dqp5v-001). Use when a reverse proxy mounts the instance under a subpath. Also CODEBUDDY_GATEWAY_BASE_PATH. Invalid values fail at startup; unset or / means site root	codebuddy --serve --base-path /cnb-5gg-1k09dqp5v-001
--open	Open a browser after --serve starts	codebuddy --serve --open
--acp	Start as an ACP server (default: stdio NDJSON). Do not confuse with --serve alone, which uses HTTP ACP for the Web UI	codebuddy --acp
--acp-transport	Honored only with --acp: stdio (default) or streamable-http. Commander's default stdio does not override --serve HTTP transport when --acp is omitted	codebuddy --acp --acp-transport streamable-http
--a2a	Receive A2A JSON-RPC requests over stdio. SendMessage is supported, while the in-process TaskStore supports GetTask, ListTasks, and CancelTask. Other methods are handled by the A2A SDK according to server capabilities and return protocol errors when unavailable. Used alone, A2A exclusively owns stdio; combined with --input-format stream-json, the two protocols are routed line by line and share the same session. Cannot be combined with --acp	codebuddy -p --a2a --input-format stream-json --output-format stream-json
--prewarm	Start in prewarm standby mode: complete startup initialization then suspend, waiting for external wake-up via IPC (working directory is bound only upon wake-up). Used to eliminate cold-start latency when spinning up sessions. Disabled by default.	codebuddy --prewarm --prewarm-id pool1
--prewarm-id <id>	Prewarm IPC endpoint identifier (defaults to the process PID), used to construct local socket/pipe addresses. Used with the cbc-prewarm management command.	codebuddy --prewarm --prewarm-id pool1

Important Note: When using -p/--print for non-interactive execution, operations involving file reading/writing, command execution, network requests, etc. must have an explicit permission strategy: the most common approach is -y / --dangerously-skip-permissions, but you can also use --permission-mode auto, --permission-mode dontAsk, pre-configured permissions.allow rules, or a dedicated permission prompt MCP tool. Otherwise, operations requiring human confirmation will be blocked. With -y alone, HIGH/CRITICAL dangerous commands may still require confirmation.

⚠️ Risk Notice: CODEBUDDY_IS_SANDBOX=1 + -y skips confirmation for dangerous commands and must only be used in isolated sandboxes without internet access. This variable is read only from the process environment and is not injected from the env field of settings.json. Do not use it on your local machine or in environments that can access production credentials.

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
disallowedTools	No	Array of tools the Sub-Agent is forbidden to use (blacklist), unioned with the session-level --disallowedTools
model	No	Model ID, name or alias, scenario variant lite / reasoning, or inherit / default. When omitted or set to inherit / default, the model is selected through the normal sub-agent resolution chain
effort	No	Reasoning effort: minimal / low / medium / high / xhigh / max. Omit to inherit the session effort
maxTurns	No	Maximum execution turns for the Sub-Agent (positive integer). Priority: env CODEBUDDY_CODE_SUBAGENT_MAX_TURNS > Agent tool max_turns parameter > this field
background	No	When set to true, this Sub-Agent always runs in the background (equivalent to run_in_background: true)
initialPrompt	No	When this agent runs as the main session agent (--agent or settings agent), automatically prepended to the first user message
memory	No	Persistent memory scope: user / project / local; see Sub-Agents documentation

Example:

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."
  }
}'

For more details on creating and using Sub-Agents, see the Sub-Agents documentation.

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.

  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.

  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.

  codebuddy --append-system-prompt "Always use TypeScript and include JSDoc comments"

Sandbox Mode (Beta)

Beta Feature: The Sandbox functionality is currently in Beta.

Detailed Documentation: See the Bash Sandbox for sandbox isolation features.

Sandbox Parameters

--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

# 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

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 - Master keyboard shortcuts and tips
• Explore Slash Commands - Learn about built-in commands
• Skills System - Extend AI professional capabilities
• Learn MCP Integration - Extend tool capabilities

---

Precise command-line operations are the foundation of efficient development