CodexBar Configuration Options: Complete JSON Schema and CLI Reference

CodexBar stores all user settings in a hierarchical JSON file that supports environment-variable overrides, per-provider API credentials, and multi-account token switching, manageable via both direct editing and the native codexbar CLI.

CodexBar unifies access to dozens of LLM providers through a single macOS menu bar application and command-line interface. Mastering the available CodexBar configuration options enables you to customize provider precedence, secure sensitive credentials with strict file permissions, and automate deployments across development environments.

Configuration File Location and Precedence

CodexBar resolves its settings file using a strict priority order. The first existing path from the following list is loaded:

• $CODEXBAR_CONFIG – Environment variable override for CI/CD pipelines.
• $XDG_CONFIG_HOME/codexbar/config.json – XDG Base Directory compliance.
• ~/.config/codexbar/config.json – Default location for new installations.
• ~/.codexbar/config.json – Legacy fallback path.

The containing directory is created automatically if missing. On macOS and Linux, file permissions are forced to 0600 (owner read/write only) to prevent unauthorized access to API keys stored within.

JSON Structure and Provider Schema

The top-level configuration object requires exactly two fields:

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

The providers array contains one object per LLM provider. The array order dictates both the menu bar item sequence and the CLI provider priority.

Provider-Level Configuration Fields

Each provider object in Sources/CodexBarCore/Providers/Providers.swift accepts the following fields:

Field	Type	Description
id	String (required)	Provider identifier from Providers.swift (e.g., openai, cursor, grok).
enabled	Bool	Toggles the provider. Defaults to built-in values defined in ProviderMetadata.swift.
source	String	Authentication mode: auto, web, cli, oauth, or api.
apiKey	String	Raw API token for providers supporting key-based access (OpenAI, Groq, LLM-Proxy).
enterpriseHost	String	Base URL override for self-hosted deployments (Azure OpenAI, LiteLLM, ClawRouter).
cookieSource	String	Cookie import behavior: auto (browser import), manual (static header), or off.
cookieHeader	String	Static Cookie: header value when cookieSource is manual.
region	String	Provider-specific region identifier (e.g., zai, minimax).
workspaceID	String	Workspace or deployment ID (Azure OpenAI deployment name, OpenAI project ID).
tokenAccounts	Object	Multi-account credentials for providers listed in TokenAccountSupportCatalog.

Multi-Account Token Management

The tokenAccounts field enables rapid switching between identities for providers like z.ai or openai. The schema structure stored in the configuration file is:

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

The activeIndex integer specifies which account is currently selected, while the accounts array holds distinct credentials with Unix timestamps for audit tracking.

Managing Configuration via CLI

Instead of manual JSON editing, use the codexbar binary to modify settings safely. These commands are implemented in Sources/CodexBarCore/CLI/ConfigCommands.swift:

# List all configured providers

codexbar config providers

# Toggle provider availability

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

# Securely set API keys via stdin (prevents shell history leakage)

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

Supported Provider Identifiers

All valid id strings are enumerated in Sources/CodexBarCore/Providers/Providers.swift. Current production identifiers include:

• codex, openai, azureopenai, claude, cursor
• copilot, grok, gemini, deepseek, mistral
• groq, llmproxy, litellm, openrouter
• ollama, elevenlabs, perplexity, zai, minimax
• windsurf, zed, warp, bedrock, vertexai

Practical Configuration Examples

Minimal API-Only Setup

{
  "version": 1,
  "providers": [
    {
      "id": "openai",
      "enabled": true,
      "source": "api",
      "apiKey": "sk-proj-...",
      "workspaceID": "proj_12345"
    },
    {
      "id": "cursor",
      "enabled": false,
      "cookieSource": "off"
    }
  ]
}

This configuration activates OpenAI in API mode with project scoping while explicitly disabling Cursor to prevent browser cookie importing.

Enterprise Multi-Account Configuration

{
  "version": 1,
  "providers": [
    {
      "id": "azureopenai",
      "enabled": true,
      "source": "api",
      "enterpriseHost": "https://mycompany.openai.azure.com",
      "workspaceID": "gpt-4-deployment",
      "apiKey": "..."
    },
    {
      "id": "zai",
      "enabled": true,
      "tokenAccounts": {
        "version": 1,
        "activeIndex": 1,
        "accounts": [
          {"id": "acc-1", "label": "Personal", "token": "zai-...", "addedAt": 1735123456, "lastUsed": 1735220000},
          {"id": "acc-2", "label": "Work", "token": "zai-...", "addedAt": 1735123456, "lastUsed": 1735230000}
        ]
      }
    }
  ]
}

Summary

• CodexBar configuration resides in a JSON file resolved via $CODEXBAR_CONFIG, XDG paths, or ~/.config/codexbar/config.json.
• The providers array controls availability, authentication mode, and credentials for each LLM service.
• Sensitive fields like apiKey and cookieHeader are protected by 0600 file permissions on Unix systems.
• Use tokenAccounts to maintain multiple identities for single providers without editing the full configuration repeatedly.
• The codexbar config CLI commands provide a secure interface for updates, particularly when piping keys via --stdin.

Frequently Asked Questions

Where is the CodexBar config file stored on macOS?

By default, CodexBar creates and reads ~/.config/codexbar/config.json. You can override this location by setting the $CODEXBAR_CONFIG environment variable to an absolute file path, or follow XDG Base Directory standards by defining $XDG_CONFIG_HOME.

How do I add multiple API keys to CodexBar for the same provider?

Configure the tokenAccounts object within the provider entry. This schema supports an accounts array where each element contains a label, token, and UUID-based id. The activeIndex integer determines which account is currently active for API requests.

Can I disable specific providers in CodexBar without deleting their settings?

Yes. Set the enabled field to false in the provider object, or run codexbar config disable --provider <id> from the terminal. Disabled providers remain in the configuration file but are excluded from the menu bar and CLI suggestions.

How do I secure my CodexBar API keys from other users on the system?

CodexBar automatically enforces 0600 permissions (owner read/write only) on the configuration file at ~/.config/codexbar/config.json on macOS and Linux. When setting keys via CLI, always use the --stdin flag with printf or echo piped input to prevent credentials from appearing in your shell history.

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