CodexBar Configuration Options: Complete Guide to JSON Settings and CLI Commands

CodexBar stores all user-controllable settings in a single JSON config file supporting provider-specific options for API keys, enterprise hosts, authentication modes, and multi-account tokens, editable via both manual editing and CLI commands.

The open-source steipete/CodexBar repository provides a unified interface for interacting with various LLM providers through both a GUI app and the codexbar CLI. All configuration options are centralized in a JSON file that controls provider availability, authentication methods, and runtime behavior. Understanding the configuration schema allows you to customize API endpoints, manage multiple accounts, and secure sensitive credentials.

Configuration File Location and Format

CodexBar reads configuration from a JSON file that follows a strict hierarchy for file discovery.

File Paths and Precedence

The application searches for config.json in the following order:

1. $CODEXBAR_CONFIG – Environment variable pointing directly to a custom config file
2. $XDG_CONFIG_HOME/codexbar/config.json – XDG Base Directory specification path
3. ~/.config/codexbar/config.json – Default location for new installations
4. ~/.codexbar/config.json – Legacy location for backward compatibility

The configuration directory is created automatically if missing, and file permissions are forced to 0600 on macOS and Linux to ensure API keys remain secure.

JSON Schema Structure

The root object requires a version field and a providers array:

{
  "version": 1,
  "providers": []
}

The providers array contains one object per LLM provider. The array order determines both the menu item sequence in the GUI and the display order in CLI outputs.

Provider Configuration Options

Each provider object in the providers array supports the following fields as defined in docs/configuration.md:

• id (String, required): Provider identifier matching constants defined in Sources/CodexBarCore/Providers/Providers.swift (e.g., openai, codex, cursor, claude, grok)
• enabled (Bool): Toggles provider availability; defaults to true for most built-in providers
• source (String): Authentication mode preference: auto, web, cli, oauth, or api; defaults to auto following provider-specific fallback chains
• apiKey (String): Raw API token for providers supporting API-only operation (OpenAI, Groq, LLM-Proxy, etc.)
• enterpriseHost (String): Base URL override for self-hosted or enterprise deployments (Azure OpenAI, Copilot, LiteLLM, ClawRouter)
• cookieSource (String): Cookie acquisition method: auto (import from browsers), manual (use cookieHeader), or off (disable cookies); defaults to auto
• cookieHeader (String): Raw Cookie: HTTP header value when cookieSource is set to manual
• region (String): Provider-specific region identifier (e.g., zai, minimax)
• workspaceID (String): Workspace, deployment, or project identifier (e.g., Azure OpenAI deployment name, OpenAI project ID)
• tokenAccounts (Object): Multi-account configuration for providers supporting token switching

Multi-Account Token Support

The tokenAccounts field enables switching between multiple credentials for a single provider. This feature is supported by providers listed in TokenAccountSupportCatalog (e.g., z.ai, openai in certain modes):

{
  "version": 1,
  "activeIndex": 0,
  "accounts": [
    {
      "id": "UUID-string",
      "label": "user@example.com",
      "token": "sk-...",
      "addedAt": 1735123456,
      "lastUsed": 1735220000
    }
  ]
}

The activeIndex specifies which account is currently selected, while the accounts array stores distinct credentials with metadata for tracking usage.

Supported Provider IDs

All valid provider identifiers are enumerated in Sources/CodexBarCore/Providers/Providers.swift. The complete list includes:

• Cloud providers: openai, azureopenai, claude, gemini, grok, copilot, deepseek, mistral, perplexity
• IDE-integrated: cursor, windsurf, zed, augment, jetbrains, codex
• Regional/API proxies: zai, minimax, moonshot, kimi, doubao, sakana, stepfun
• Self-hosted/Routing: ollama, openrouter, litellm, llmproxy, clawrouter, bedrock
• Specialized: elevenlabs, deepgram, devin, manus, poe, chutes

Each id must exactly match the constants defined in the source code to be recognized by the configuration parser.

CLI Configuration Commands

Rather than manually editing JSON, use the codexbar config subcommands implemented in Sources/CodexBarCore/CLI/ConfigCommands.swift:

# List all configured providers

codexbar config providers

# Enable or disable specific providers

codexbar config enable --provider grok
codexbar config disable --provider cursor

# Set API keys securely via stdin

printf '%s' "$OPENAI_API_KEY" | codexbar config set-api-key --provider openai --stdin
printf '%s' "$GROQ_API_KEY" | codexbar config set-api-key --provider groq --stdin

These commands validate input against the provider schemas and ensure proper JSON formatting without risking syntax errors from manual edits.

Configuration Examples

Minimal API Configuration

{
  "version": 1,
  "providers": [
    {
      "id": "openai",
      "enabled": true,
      "source": "api",
      "apiKey": "sk-proj-xxxxxxxx",
      "workspaceID": "proj_12345"
    }
  ]
}

This configuration enables OpenAI in API mode with project scoping via workspaceID.

Enterprise Self-Hosted Setup

{
  "version": 1,
  "providers": [
    {
      "id": "azureopenai",
      "enabled": true,
      "source": "api",
      "apiKey": "xxxxxxxx",
      "enterpriseHost": "https://mycompany.openai.azure.com",
      "workspaceID": "my-deployment-name"
    },
    {
      "id": "cursor",
      "enabled": false,
      "cookieSource": "off"
    }
  ]
}

This example configures Azure OpenAI with a custom enterprise endpoint while explicitly disabling the Cursor provider and blocking cookie imports.

Summary

• Single JSON file: All settings reside in config.json located via environment variables or standard XDG paths
• Provider array: The providers array controls visibility, ordering, and authentication for each LLM service
• Flexible authentication: Support for API keys, cookies, OAuth, and enterprise URL overrides via enterpriseHost
• Multi-account ready: The tokenAccounts object enables credential switching for compatible providers
• CLI management: Use codexbar config commands to avoid manual JSON editing and prevent syntax errors
• Security focused: File permissions default to 0600 and sensitive values can be piped via stdin

Frequently Asked Questions

Where is the CodexBar config file stored?

The configuration file location follows a precedence chain: first checking the $CODEXBAR_CONFIG environment variable, then $XDG_CONFIG_HOME/codexbar/config.json, defaulting to ~/.config/codexbar/config.json for new installations, with legacy support for ~/.codexbar/config.json.

How do I add multiple API keys for different accounts?

Use the tokenAccounts field in your provider configuration to define an array of account objects, each containing a unique id, label, and token. Set activeIndex to specify which account is currently active. This feature is available for providers listed in the TokenAccountSupportCatalog such as z.ai and certain OpenAI configurations.

What is the difference between source and cookieSource?

The source field determines the primary authentication mode (auto, web, cli, oauth, api) for API requests, while cookieSource specifically controls how browser cookies are obtained (auto, manual, off) for providers that support web-based authentication. They operate independently, allowing combinations like API-only mode with cookie imports disabled.

How do I disable a provider in CodexBar?

Set the enabled field to false in the provider's configuration object, or use the CLI command codexbar config disable --provider <id>. When disabled, the provider does not appear in the GUI menu or CLI provider lists, and no authentication attempts are made for that service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}