CLI Configuration

The Codebuff CLI can be configured through environment variables, configuration files, and command-line options. This guide covers all available configuration options.

Configuration Files

Settings File

User preferences are stored in:

~/.config/codebuff/settings.json

This file is automatically created on first run with default values:

{
  "mode": "DEFAULT",
  "adsEnabled": true
}

Available settings:

mode

string

default:"DEFAULT"

Default agent mode: DEFAULT, FREE, MAX, or PLAN

adsEnabled

boolean

default:"true"

Whether to show promotional messages in the CLI

Authentication

Authentication tokens are stored in:

~/.config/codebuff/credentials.json

This file contains sensitive credentials. Never commit it to version control.

Log Files

CLI logs are written to:

~/.config/codebuff/cli.log

Use --clear-logs flag to remove old logs on startup:

codebuff --clear-logs

Environment Variables

Configure the CLI and SDK behavior with environment variables. Create a .env file in your project root or set them in your shell profile.

AI API Keys

The Codebuff platform handles model routing, but you can configure your own API keys for direct usage:

ANTHROPIC_API_KEY

string

Anthropic API key for Claude models

export ANTHROPIC_API_KEY="sk-ant-..."

OPENAI_API_KEY

string

OpenAI API key for GPT models

export OPENAI_API_KEY="sk-..."

OPEN_ROUTER_API_KEY

string

OpenRouter API key for accessing multiple models

export OPEN_ROUTER_API_KEY="sk-or-..."

When using Codebuff’s hosted service, API keys are not required. They’re only needed if you’re self-hosting or using custom model configurations.

CLI Configuration

CODEBUFF_CLI_VERSION

string

Override the CLI version number (for development)

export CODEBUFF_CLI_VERSION="1.0.0-dev"

CODEBUFF_APP_URL

string

Override the Codebuff backend URL (for development)

export CODEBUFF_APP_URL="http://localhost:3000"

Analytics & Telemetry

NEXT_PUBLIC_POSTHOG_API_KEY

string

PostHog API key for analytics

export NEXT_PUBLIC_POSTHOG_API_KEY="phc_..."

NEXT_PUBLIC_POSTHOG_HOST_URL

string

PostHog host URL

export NEXT_PUBLIC_POSTHOG_HOST_URL="https://us.i.posthog.com"

API Key Setup

To use your own API keys with Codebuff:

Get API keys

Anthropic: https://console.anthropic.com/
OpenAI: https://platform.openai.com/api-keys
OpenRouter: https://openrouter.ai/keys

Create .env file

In your project directory:

touch .env

Add your keys:

ANTHROPIC_API_KEY="sk-ant-..."
OPENAI_API_KEY="sk-..."

Add to .gitignore

Prevent committing secrets:

echo ".env" >> .gitignore

Restart the CLI

Environment variables are loaded on startup:

codebuff

Always add .env to your .gitignore to prevent accidentally committing API keys to version control.

Model Selection

Codebuff automatically selects appropriate models based on the agent mode:

Agent Mode Models

# Balanced performance
codebuff --mode default
# or
/mode:default

Persistent Mode Preference

Save your preferred mode:

/mode:max

The CLI remembers your choice for future sessions. Override on startup:

codebuff --free  # Start in FREE mode regardless of saved preference

Custom Agent Loading

Codebuff loads custom agents from multiple locations, with later directories taking precedence:

Agent Directory Priority

Global agents (~/.agents/)
- Available in all projects
- Lowest priority
Monorepo agents (../.agents/)
- Shared across monorepo packages
- Medium priority
Project agents ({project}/.agents/)
- Project-specific agents
- Highest priority (overrides global and monorepo)

Creating Agent Directories

Initialize agent directory structure:

/init

This creates:

project/
├── knowledge.md
└── .agents/
    ├── types/
    │   ├── agent-definition.ts
    │   ├── tools.ts
    │   └── util-types.ts
    └── my-agent.ts  # Your custom agents here

Agent File Structure

Custom agent files should export an AgentDefinition:

// .agents/my-agent.ts
import type { AgentDefinition } from './types/agent-definition'

export const agent: AgentDefinition = {
  id: 'my-agent',
  displayName: 'My Custom Agent',
  description: 'Does something specific',
  publisher: 'username',
  instructions: `You are a specialized agent that...`,
  // ... more configuration
}

export default agent

Loading Agents

Agents are automatically loaded from all three locations on CLI startup:

codebuff

Skip local agent overrides: Load only built-in agents:

codebuff --agent base2

This is useful for testing or when local agents cause issues.

MCP Server Configuration

Configure MCP (Model Context Protocol) servers in .agents/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "API_KEY": "..."
      }
    }
  }
}

MCP servers provide additional tools and context to agents.

Advanced Configuration

Working Directory

Override the working directory:

codebuff --cwd /path/to/project

This is useful for:

Running Codebuff from a different directory
Scripting and automation
Testing agents in specific project contexts

Conversation Continuation

Continue from a previous conversation:

# Continue last conversation
codebuff --continue

# Continue specific conversation by ID
codebuff --continue abc123def456

Agent Override

Run a specific agent, bypassing local overrides:

codebuff --agent base2
codebuff --agent my-publisher/my-agent

Initial Prompt

Provide an initial prompt on the command line:

codebuff "add unit tests for the auth module"

The CLI will start and immediately send this prompt to the agent.

Configuration Tips

Use project-specific .env files for API keys and configuration that shouldn’t be shared across projects.

Global agent directory (~/.agents/) is perfect for personal utility agents you use across all projects.

Monorepo shared agents (../.agents/) let you share custom agents across packages while keeping them versioned.

Override agent modes per prompt using flags like --free or --max without changing your saved preference.

Troubleshooting

Agent Not Loading

If your custom agent isn’t loading:

Check the file exports default or named export agent
Verify the id field is unique
Ensure TypeScript types are correct
Check CLI logs: ~/.config/codebuff/cli.log

# Clear logs and restart to see fresh output
codebuff --clear-logs

API Key Issues

If API keys aren’t working:

Verify the keys are in .env with correct names
Check for typos or extra whitespace
Ensure .env is in the project root or parent
Restart the CLI after changing .env

Configuration Not Persisting

If settings don’t persist:

Check write permissions on ~/.config/codebuff/
Verify the JSON format in settings.json
Look for errors in CLI logs

Theme Detection Issues

If the CLI theme doesn’t match your terminal:

/theme:toggle

The CLI attempts automatic detection but may need manual adjustment.

Next Steps

Workflows

Learn common CLI workflows and best practices

Creating Agents

Build custom agents for your workflows

Commands Reference

Complete list of all CLI commands

SDK Guide

Use Codebuff programmatically with the SDK

Get Started

Core Concepts

CLI Guide

SDK Guide

Agent Development

Advanced

​Configuration Files

​Settings File

​Authentication

​Log Files

​Environment Variables

​AI API Keys

​CLI Configuration

​Analytics & Telemetry

​API Key Setup

​Model Selection

​Agent Mode Models

​Persistent Mode Preference

​Custom Agent Loading

​Agent Directory Priority

​Creating Agent Directories

​Agent File Structure

​Loading Agents

​MCP Server Configuration

​Advanced Configuration

​Working Directory

​Conversation Continuation

​Agent Override

​Initial Prompt

​Configuration Tips

​Troubleshooting

​Agent Not Loading

​API Key Issues

​Configuration Not Persisting

​Theme Detection Issues

​Next Steps

Workflows

Creating Agents

Commands Reference

SDK Guide

Build docs developers (and LLMs) love

Configuration Files

Settings File

Authentication

Log Files

Environment Variables

AI API Keys

CLI Configuration

Analytics & Telemetry

API Key Setup

Model Selection

Agent Mode Models

Persistent Mode Preference

Custom Agent Loading

Agent Directory Priority

Creating Agent Directories

Agent File Structure

Loading Agents

MCP Server Configuration

Advanced Configuration

Working Directory

Conversation Continuation

Agent Override

Initial Prompt

Configuration Tips

Troubleshooting

Agent Not Loading

API Key Issues

Configuration Not Persisting

Theme Detection Issues

Next Steps