# CodexBar Configuration Options: Complete JSON Schema and CLI Reference

> Explore CodexBar configuration options with our complete JSON schema and CLI reference. Manage settings easily with environment variables and API credentials.

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

---

**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:

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

| Field | Type | Description |
|-------|------|-------------|
| `id` | **String** (required) | Provider identifier from [`Providers.swift`](https://github.com/steipete/CodexBar/blob/main/Providers.swift) (e.g., `openai`, `cursor`, `grok`). |
| `enabled` | **Bool** | Toggles the provider. Defaults to built-in values defined in [`ProviderMetadata.swift`](https://github.com/steipete/CodexBar/blob/main/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:

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

```bash

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

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

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