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

> Explore CodexBar configuration options with our guide to JSON settings and CLI commands. Manage API keys, hosts, auth, and tokens for seamless Codium and GitHub integration.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: complete-guide
- Published: 2026-07-10

---

**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`](https://github.com/steipete/CodexBar/blob/main/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:

```json
{
  "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`](https://github.com/steipete/CodexBar/blob/main/docs/configuration.md):

- **`id`** (String, required): Provider identifier matching constants defined in [`Sources/CodexBarCore/Providers/Providers.swift`](https://github.com/steipete/CodexBar/blob/main/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):

```json
{
  "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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/CLI/ConfigCommands.swift):

```bash

# 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

```json
{
  "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

```json
{
  "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`](https://github.com/steipete/CodexBar/blob/main/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.