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

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"
--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	Get validated JSON output matching a JSON Schema after the agent completes workflow	codebuddy -p --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
--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

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 Sandboxing Guide for complete sandbox usage instructions, best practices, and troubleshooting.

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