# How to Configure API Keys for CodexBar Using the CLI

> Securely set CodexBar API keys with the CLI. Learn to use the set-api-key command with provider and API key flags or stdin for enhanced security.

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

---

**You can configure API keys for CodexBar by running `codexbar config set-api-key` with the `--provider` and `--api-key` flags, or pipe the key via `--stdin` to avoid shell history logging.**

The **steipete/CodexBar** repository provides a Swift-based command-line interface that manages LLM provider credentials through a structured configuration system. Understanding how to configure API keys for CodexBar using the CLI ensures your credentials are validated, securely stored, and properly formatted for immediate use.

## Understanding the Configuration Storage

CodexBar stores provider credentials in a **per-user configuration file** located at `~/.codexbar/config.json`. This JSON structure maintains an array of provider objects under the `providers` key, where each entry contains the provider ID, API key, enabled status, and optional token account metadata.

When you execute configuration commands, the `CodexBarConfigStore` class in [`Sources/CodexBarCore/Config/CodexBarConfigStore.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/CodexBarConfigStore.swift) handles the atomic read/write operations to this file. The configuration persists as structured data conforming to the `CodexBarConfig` and `ProviderConfig` types defined in [`Sources/CodexBarCore/Config/CodexBarConfig.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/CodexBarConfig.swift).

## Setting API Keys via the Command Line

The `codexbar config set-api-key` subcommand follows a seven-step validation and persistence flow implemented in [`Sources/CodexBarCLI/CLIConfigCommand.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIConfigCommand.swift).

### Basic Syntax and Validation

The CLI entry point `runConfigSetAPIKey` (lines 98-112) parses arguments including `--provider`, `--api-key`, `--stdin`, and `--no-enable`. Before accepting input, the system validates that the specified provider supports API key overrides through `ProviderConfigEnvironment.supportsAPIKeyOverride(for:)` in [`Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift).

Available providers include `openai`, `anthropic`, and `zai`, among others defined in the internal enum mappings.

### Handling API Key Input

The `resolveConfigAPIKeyInput` method (lines 172-187) handles two input modes:

1. **Direct argument**: Passing `--api-key sk-...` inline
2. **Standard input**: Using `--stdin` to read from a piped line

When using `--stdin`, the helper `cleanConfigSecret` strips surrounding quotes and whitespace to prevent formatting errors. This approach is recommended for production environments to avoid leaking keys into shell history files.

### Provider-Specific Options (z.ai Team Mode)

For z.ai team deployments, the `resolveConfigAPIKeyAccountOptions` method (lines 229-267) constructs token account configurations requiring additional flags:

- `--label`: Human-readable account identifier
- `--usage-scope`: Either `personal` or `team`
- `--organization-id`: Organization identifier (required for team scope)
- `--workspace-id`: Workspace identifier (required for team scope)

The `configSettingAPIKey` method (lines 188-226) then assembles these components into a complete `ProviderConfig` entry before persistence.

## Practical Code Examples

### Direct Key Configuration

Store an OpenAI key and enable the provider immediately:

```bash
codexbar config set-api-key \
    --provider openai \
    --api-key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

### Secure Input via Stdin

Prevent the key from appearing in shell history by piping from stdin:

```bash
echo "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | \
    codexbar config set-api-key --provider openai --stdin

```

### Store Without Enabling

Add a key to the configuration while keeping the provider disabled:

```bash
codexbar config set-api-key \
    --provider openai \
    --api-key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
    --no-enable

```

### z.ai Team Configuration

Configure a z.ai team token account with full organizational context:

```bash
codexbar config set-api-key \
    --provider zai \
    --api-key <team-token> \
    --label "Team-Prod" \
    --usage-scope team \
    --organization-id org-12345 \
    --workspace-id ws-67890

```

### Verify Configuration

Inspect the stored configuration in human-readable format:

```bash
codexbar config dump

```

Or export as formatted JSON for scripting:

```bash
codexbar config dump --format json --pretty

```

## Core Implementation Files

The configuration flow relies on these specific source files:

- **[`Sources/CodexBarCLI/CLIConfigCommand.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIConfigCommand.swift)**: Implements `runConfigSetAPIKey`, `resolveConfigAPIKeyInput`, and `configSettingAPIKey` for command processing and validation
- **[`Sources/CodexBarCore/Config/CodexBarConfigStore.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/CodexBarConfigStore.swift)**: Provides the `save` method for atomic writes to `~/.codexbar/config.json`
- **[`Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift)**: Declares provider capabilities via `supportsAPIKeyOverride(for:)`
- **[`Sources/CodexBarCore/Config/CodexBarConfig.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/CodexBarConfig.swift)**: Defines serializable configuration structures
- **[`Sources/CodexBarCore/Providers/ProviderCLIConfig.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/ProviderCLIConfig.swift)**: Maps CLI provider names to internal enum values

## Summary

- CodexBar stores API keys in `~/.codexbar/config.json` managed by the `CodexBarConfigStore` class
- Use `codexbar config set-api-key` with `--provider` and either `--api-key` or `--stdin` to configure credentials
- The CLI validates provider support through `ProviderConfigEnvironment.supportsAPIKeyOverride` before accepting input
- z.ai team accounts require additional flags: `--label`, `--usage-scope`, `--organization-id`, and `--workspace-id`
- Pipe keys via `--stdin` to prevent exposure in shell history files

## Frequently Asked Questions

### Where does CodexBar store API keys on disk?

CodexBar persists all provider credentials in a JSON file located at `~/.codexbar/config.json`. The `CodexBarConfigStore` class in [`Sources/CodexBarCore/Config/CodexBarConfigStore.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Config/CodexBarConfigStore.swift) handles atomic read and write operations to this per-user configuration file.

### How do I prevent my API key from appearing in shell history?

Use the `--stdin` flag instead of the `--api-key` argument. Pipe your key into the command using `echo "your-key" | codexbar config set-api-key --provider openai --stdin`. The `resolveConfigAPIKeyInput` function processes this input through `cleanConfigSecret` to sanitize whitespace and quotes while keeping the credential out of your shell history.

### Which providers support team or token account configurations?

The z.ai provider supports advanced token account configurations through the `resolveConfigAPIKeyAccountOptions` method. This requires specifying `--usage-scope team` along with `--organization-id` and `--workspace-id` parameters. Other providers like OpenAI and Anthropic use standard single-key authentication without additional account metadata.

### How can I verify that my API key was saved correctly?

Run `codexbar config dump` to display the current configuration in text format, or use `codexbar config dump --format json --pretty` for machine-readable output. The CLI retrieves data directly from `CodexBarConfigStore`, showing the exact contents of the `~/.codexbar/config.json` file including masked or full key values depending on your system permissions.