CLI Reference ​

The complete reference manual for the CodeBuddy Code command-line tool, providing accurate usage instructions based on the real command structure.

Note: Some commands are placeholders and are not fully implemented in the current version. Calls to these commands will prompt that they are unsupported. Please refer to the actual output via --help.

🚀 Basic Syntax ​

bash
codebuddy [options] [command] [prompt]
cbc [options] [command] [prompt]

By default, CodeBuddy Code starts an interactive session. Use -p/--print for non-interactive output.

Important Tip: When using the -p/--print parameter, if a tool requiring authorization (such as file operations, network requests, etc.) is needed, the --dangerously-skip-permissions parameter must be explicitly specified, otherwise, it will be blocked by the permission check.

📋 Global Options ​

Basic Options ​

bash
-V, --version                         Outputs the version number
-h, --help                            Displays help information
-d, --debug                           Enables debug mode (default: false)
  --verbose                           Overrides the verbose mode setting in the configuration (default: false)
-p, --print                           Prints the response and exits (for piping) (default: false)

Input/Output Formats ​

bash
--output-format <format>              Output format (only works with --print):
                                      "text" (default), "json" (single result),
                                      or "stream-json" (real-time streaming)
--input-format <format>               Input format (only works with --print):
                                      "text" (default), or "stream-json"
                                      (real-time streaming input)

Session Management ​

bash
-c, --continue                        Continues the most recent session (default: false)
-r, --resume [sessionId]              Resumes a session - provides session ID or interactively selects
    --session-id <uuid>               Uses a specific session ID (must be a valid UUID)

AI Model Options ​

bash
--model <model>                       The model for the current session. Provide the model name
                                      (e.g., 'gpt-5' or 'gpt-4')
--fallback-model <model>              Automatically falls back to the specified model when the default model is overloaded
                                      (only works with --print)

Security and Permissions ​

bash
--dangerously-skip-permissions        Skips all permission checks. Recommended only for sandboxes with no network access
--permission-mode <mode>              Permission mode: "acceptEdits", "bypassPermissions",
                                      "default", "plan"
                                      Supports session-level dynamic management, with real-time UI display of current status
--allowedTools <tools...>             List of allowed tools (e.g., "Bash(git:*) Edit")
--disallowedTools <tools...>          List of disallowed tools (e.g., "Bash(git:*) Edit")
--add-dir <directories...>            Additional directories allowed for tool access

MCP Integration ​

bash
--mcp-config <fileOrString>           Loads MCP server from a JSON file or string
--strict-mcp-config                   Uses only the MCP server in --mcp-config,
                                      ignoring other MCP configurations (default: false)

IDE Integration ​

bash
--ide                                 If exactly one valid IDE is available,
                                      automatically connects upon startup (default: false)

🎯 Main Commands ​

Interactive Mode ​

bash
# Start interactive conversation
codebuddy
# Start with a specified model
codebuddy --model gpt-5
# Continue the most recent conversation
codebuddy -c
# Resume a specific session
codebuddy -r session-id-12345
# Automatically connect to IDE
codebuddy --ide

Single Execution Mode ​

bash
# Basic query
codebuddy -p "Explain the function's purpose"
# JSON format output
codebuddy -p "Analyze the code structure" --output-format json
# Streaming output
codebuddy -p "Generate large code" --output-format stream-json
# Pipe input
cat error.log | codebuddy -p "Analyze these error logs"
# Operations requiring tool authorization (must add --dangerously-skip-permissions)
codebuddy -p "Modify this file" --dangerously-skip-permissions
codebuddy -p "Run test command" --dangerously-skip-permissions

Models and Fallback ​

bash
# Use a specific model
codebuddy --model gpt-5 -p "Complex code analysis task"
# Set fallback model
codebuddy --model gpt-5 --fallback-model gpt-4 -p "Query"

Configuration Commands (config) ​

bash
# List configuration (supported)
codebuddy config list
# Get configuration (supported)
codebuddy config get model
# Set configuration (supported, limited to keys: permissions, model, env, apiKeyHelper)
codebuddy config set model gpt-5

MCP Commands (mcp) ​

bash
# List MCPs (supported)
codebuddy mcp list
# Other subcommands (help available, but may be unavailable due to missing configurations)
codebuddy mcp add <name> <commandOrUrl> [args...]
codebuddy mcp remove <name>
codebuddy mcp get <name>
codebuddy mcp add-json <name> <json>

🛠️ Utility Commands ​

Installation and Updates ​

bash
# Install (currently unsupported, will prompt that it is unsupported)
codebuddy install [options] [target]
# Check for updates (supported)
codebuddy update
# Migrate from global npm installation (currently unsupported, will prompt that it is unsupported)
codebuddy migrate-installer
# Health check (currently unsupported, will prompt that it is unsupported)
codebuddy doctor

🎨 Output Format Details ​

text format (default) ​

bash
codebuddy -p "Hello" --output-format text
# Output: Plain text response

json format ​

bash
codebuddy -p "Analyze the code" --output-format json
# Output: {"response": "...", "metadata": {...}}

stream-json format ​

bash
codebuddy -p "Generate long code" --output-format stream-json
# Output: Real-time streaming JSON response

🔒 Security and Permission Control ​

Key Note: When using the -p/--print parameter for single execution, any operation that requires tool authorization must explicitly add the --dangerously-skip-permissions parameter, otherwise it will be blocked by the permission check.

Tool Permission Control ​

bash
# Allow only specific tools
codebuddy --allowedTools "Read Edit" -p "Modify file" --dangerously-skip-permissions
# Disallow specific tools
codebuddy --disallowedTools "Bash" -p "Analyze code"
# Allow specific Git operations
codebuddy --allowedTools "Bash(git:status,git:diff)" -p "Check Git status" --dangerously-skip-permissions
# Skip permission check (caution, required for -p mode)
codebuddy --dangerously-skip-permissions -p "Perform authorized operation"

Directory Access Control ​

bash
# Add directories allowed for access
codebuddy --add-dir /path/to/project --add-dir /tmp -p "Process file"

📝 Practical Examples ​

Daily Development ​

bash
# Code review (pipe input)
git diff | codebuddy -p "Review these code changes"
# Generate commit message (requires authorization)
git diff --cached | codebuddy -p "Generate commit message" --output-format text --dangerously-skip-permissions
# Error log analysis
tail -f error.log | codebuddy -p "Real-time analyze errors" --input-format stream-json

Project Analysis ​

bash
# Project structure analysis
codebuddy -p "Analyze project structure and suggest improvements" --output-format json
# Dependency analysis
cat package.json | codebuddy -p "Analyze dependencies and suggest optimizations"

Session Management ​

bash
# Start a session with a specific ID
codebuddy --session-id "550e8400-e29b-41d4-a716-446655440000"
# Continue the previous session
codebuddy -c
# Resume a specific session (interactive selection)
codebuddy -r

MCP Workflow ​

bash
# Configure filesystem MCP server
codebuddy mcp add filesystem npx -y @modelcontextprotocol/server-filesystem ./src
# Start with MCP configuration
codebuddy --mcp-config mcp-servers.json
# Strict MCP mode (use only specified config)
codebuddy --strict-mcp-config --mcp-config servers.json

⚡ Performance Optimization Tips ​

Model Selection Strategy ​

bash
# Use fast model for simple tasks
codebuddy --model gpt-4 -p "Simple question"
# Use advanced model for complex tasks
codebuddy --model gpt-5 -p "Complex analysis task"
# Set fallback model to prevent overload
codebuddy --model gpt-5 --fallback-model gpt-4 -p "Query"

Output Optimization ​

bash
# Streaming output for immediate feedback
codebuddy -p "Generate large code" --output-format stream-json
# JSON format for easier program handling
codebuddy -p "Analyze data" --output-format json | jq '.response'

🚨 Troubleshooting ​

Debug Options ​

bash
# Enable debug mode
codebuddy --debug -p "Test query"
# Verbose output
codebuddy --verbose -p "Query requiring detailed information"
# Combine debug options
codebuddy --debug --verbose -p "Complete debug information"

Common Issues Resolution ​

bash
# Permission issues (must add --dangerously-skip-permissions)
codebuddy --allowedTools "Read Edit Bash" -p "Operation requiring multiple tools" --dangerously-skip-permissions
# Session issues
codebuddy --session-id "new-uuid" -p "Start new session"
# MCP connection issues
codebuddy mcp list  # Check MCP server status
codebuddy --strict-mcp-config --mcp-config config.json  # Use specific configuration

🔄 Command Combination and Piping ​

Pipe Operations ​

bash
# Multi-stage processing
find . -name "*.js" | head -5 | xargs cat | codebuddy -p "Analyze code patterns"
# Combine with Git operations
git log --oneline -10 | codebuddy -p "Analyze commit history"
# Real-time log analysis
tail -f app.log | codebuddy -p "Monitor and analyze logs" --input-format stream-json

Batch Operations ​

bash
# Batch file processing
for file in *.js; do
    codebuddy -p "Add comments to file: $file" --output-format json >> results.json
done

🚀 Next Steps ​

After mastering the CLI commands, you can:

  • Learn Interactive Mode - Master keyboard shortcuts and tips
  • Explore Slash Commands - Learn about built-in commands
  • Learn MCP Integration - Expand tool capabilities Precise command-line operations are the foundation of efficient development ⚡