Skip to content

cli-configuration.md

Latest commit

 

History

History
180 lines (131 loc) · 7.54 KB

cli-configuration.md

File metadata and controls

180 lines (131 loc) · 7.54 KB
Raw
summary CodexBar CLI configuration commands for provider toggles, API keys, and isolated config files.
read_when
Using codexbar config from scripts or CI
Enabling or disabling providers without opening Settings
Storing provider API keys from the command line

CLI configuration

codexbar config edits the same resolved config file used by the app's Settings → Providers pane. New installs use ~/.config/codexbar/config.json; absolute XDG_CONFIG_HOME paths and CODEXBAR_CONFIG are supported, and existing ~/.codexbar/config.json installs keep using the legacy file when no XDG config exists. The CLI stages writes in a private 0700 directory on the destination volume, creates the file with 0600 permissions before writing any bytes, then syncs and atomically replaces the config.

Providers

List persistent provider toggles:

codexbar config providers
codexbar config providers --json --pretty

Enable or disable a provider:

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

These are persistent app/CLI settings. They are different from codexbar usage --provider grok, which is a one-shot command override and does not edit config.

If every provider is disabled, codexbar usage with no --provider prints no text output, and codexbar usage --json prints []. Passing --provider <name> still fetches that provider for the one command.

Copilot device login

codexbar config login --provider copilot
codexbar config login --provider copilot --json

The command prints GitHub's verification URL and user code. Open the URL on any machine, enter the code, and authorize access. CodexBar polls until approval, denial, expiry, or cancellation (Ctrl-C); it does not open a browser or access Keychain. A configured Copilot enterpriseHost selects the matching GitHub issuer.

On approval, CodexBar verifies the GitHub identity, saves it to the existing providers[].tokenAccounts, selects that account, and enables Copilot. Repeating login updates the matching account while preserving its label and settings. The legacy provider-level API key is cleared, just as when adding an account in Settings. If config changes while login is pending, the command fails without overwriting that edit; retry against the updated config. Success is reported only after the private, atomic config write succeeds.

JSON mode emits newline-delimited objects (one object per event; --pretty has no effect):

{"expiresIn":900,"status":"authorization_pending","userCode":"ABCD-EFGH","verificationURI":"https://github.com/login/device"}
{"status":"authorized"}

Failures after argument parsing emit {"status":"failed","error":"..."} and exit nonzero. Neither output mode prints the access token or device code used for polling. This is an interactive setup command; usage and serve never start login automatically. CODEXBAR_CONFIG also applies to login.

API keys

API keys are stored under the provider entry in config:

printf '%s' "$ELEVENLABS_API_KEY" | codexbar config set-api-key --provider elevenlabs --stdin

set-api-key enables the provider by default. Add --no-enable when you only want to save the key:

printf '%s' "$OPENROUTER_API_KEY" | codexbar config set-api-key --provider openrouter --stdin --no-enable

Useful examples:

printf '%s' "$OPENAI_ADMIN_KEY" | codexbar config set-api-key --provider openai --stdin
printf '%s' "$ANTHROPIC_ADMIN_KEY" | codexbar config set-api-key --provider claude --stdin
printf '%s' "$DEEPGRAM_API_KEY" | codexbar config set-api-key --provider deepgram --stdin
printf '%s' "$GROQ_API_KEY" | codexbar config set-api-key --provider groq --stdin
printf '%s' "$LLM_PROXY_API_KEY" | codexbar config set-api-key --provider llmproxy --stdin
printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin
printf '%s' "$XAI_MANAGEMENT_API_KEY" | codexbar config set-api-key --provider xai --stdin

For a z.ai team account:

printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin \
  --label Team \
  --usage-scope team \
  --organization-id org_... \
  --workspace-id proj_...

Use single-line BigModel organization/project IDs; see z.ai.

Only providers that consume config-backed API keys accept this command. Admin API providers may require a key with organization/usage permissions, not a normal inference key. The xai provider reads xAI developer-platform billing with a Management key plus a team ID (set workspaceID in the provider entry, XAI_TEAM_ID, or the app settings pane); inference API keys are not accepted. The separate Grok provider tracks consumer Grok/SuperGrok subscriptions through its own browser/CLI session and takes no API key, so enable it with codexbar config enable --provider grok.

LLM Proxy also needs a base URL. Use LLM_PROXY_BASE_URL for CLI runs, or add "enterpriseHost" to the provider entry in the CodexBar config file.

Manual cookies

Store a provider's Cookie: request header the same way Settings does when you paste a manual cookie:

pbpaste | codexbar config set-cookie --provider claude --stdin

set-cookie writes cookieHeader and sets cookieSource to manual, so browser import is skipped for that provider. Like set-api-key, it trims the value, enables the provider unless you pass --no-enable, and accepts --cookie <header> for one-off scripts. The header must be a single line; see Manual cookies for how to copy it. Only providers whose fetchers read a manual config cookie accept this command; output never includes the cookie.

Clearing credentials

Remove a stored API key and manual cookie, like emptying those fields in Settings:

codexbar config clear-credential --provider claude
codexbar config clear-credential --provider claude --cookie
codexbar config clear-credential --provider openrouter --api-key

Without flags both apiKey and cookieHeader are removed; --api-key or --cookie limits it to one. Provider enablement, source, cookieSource, token accounts, and other fields are unchanged. Manual cookie mode stays selected after its header is cleared. To request browser discovery, choose Automatic explicitly in Settings. Saved accounts and environment credentials are not removed. JSON output lists the removed fields in cleared (apiKey, cookieHeader); when nothing was stored, cleared is empty and the config file is not written.

Isolated config files

For tests, demos, and CI, point CodexBar at a temporary config file:

export CODEXBAR_CONFIG=/tmp/codexbar-config.json
codexbar config enable --provider grok
codexbar config providers --json --pretty

The override applies to both reads and writes for the current process environment.

Cost history window

The app setting controls the menu's local cost-history window. For one-off CLI reports, pass --days:

codexbar cost --provider codex --days 90
codexbar cost --provider claude --days 180 --format json --pretty

The accepted range is 1...365 days.

Validation

After hand-editing config:

codexbar config validate
codexbar config dump --pretty

dump prints normalized config, including providers omitted from a hand-written file.

Missing, empty, or JSON-whitespace-only config files use defaults on macOS and Linux. validate, dump, and usage leave such files unchanged; the next config enable, disable, set-api-key, or set-cookie writes valid JSON. Malformed non-empty JSON still produces a config error and a nonzero exit without overwriting the file.