How to Configure API Keys for CodexBar Using the CLI

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 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.

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.

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.

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:

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:

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:

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:

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:

codexbar config dump

Or export as formatted JSON for scripting:

codexbar config dump --format json --pretty

Core Implementation Files

The configuration flow relies on these specific source files:

• Sources/CodexBarCLI/CLIConfigCommand.swift: Implements runConfigSetAPIKey, resolveConfigAPIKeyInput, and configSettingAPIKey for command processing and validation
• Sources/CodexBarCore/Config/CodexBarConfigStore.swift: Provides the save method for atomic writes to ~/.codexbar/config.json
• Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift: Declares provider capabilities via supportsAPIKeyOverride(for:)
• Sources/CodexBarCore/Config/CodexBarConfig.swift: Defines serializable configuration structures
• 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 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.

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