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

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 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	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	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 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 session in the background (detached mode), logs output 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 HTTP server (Web UI, REST API, ACP protocol)	codebuddy --serve --port 8080

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.

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:

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.

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"

NOTE

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

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.

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