# CodexBar Command-Line Arguments: Complete CLI Reference for the codexbar Tool

> Explore the CodexBar command-line arguments for the codexbar tool. This complete CLI reference details flags for logging, provider selection, JSON output, and more.

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

---

**CodexBar ships a rich Swift-based CLI (`codexbar`) that supports flags for verbose logging, provider selection, token account management, JSON output formatting, and debug helpers, all defined in [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift).**

The `codexbar` command-line interface in the `steipete/CodexBar` repository is built on the **Commander** library. It exposes a comprehensive set of flags through the `UsageOptions` struct, which implements `CommanderParsable`. Understanding these arguments allows you to automate provider queries, customize output formats, and debug API interactions effectively.


## General Debugging and Logging Options

Control console verbosity and logging behavior with these universal flags:

- **`-v` or `--verbose`** – Enable verbose logging for detailed execution traces.
- **`--json-output`** – Emit machine-readable logs in JSON format instead of plain text.
- **`--log-level <level>`** – Explicitly set the logging severity. Accepted values are: `trace`, `verbose`, `debug`, `info`, `warning`, `error`, or `critical`.

These options are parsed in [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift) within the `UsageOptions` struct, allowing precise control over diagnostic output when scripting the CLI.


## Provider Selection and Account Management

Configure which AI provider CodexBar queries and which credentials it uses:

- **`--provider <name>`** – Select a specific provider (e.g., `anthropic`, `openai`). Valid names are dynamically generated from `ProviderDescriptorRegistry` and listed via `ProviderHelp.list` in [`Sources/CodexBarCore/ProviderDescriptorRegistry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/ProviderDescriptorRegistry.swift).
- **`--account <label>`** – Target a specific token-account label defined in your [`config.json`](https://github.com/steipete/CodexBar/blob/main/config.json).
- **`--account-index <n>`** – Use a 1-based index to select an account from your configuration.
- **`--all-accounts`** – Fetch data from all token accounts or all visible Codex accounts simultaneously.

The `--provider` flag accepts values defined by the `ProviderSelection` enum (`single`, `both`, `all`, or custom lists), which maps CLI names to internal descriptors as implemented in [`CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/CLIOptions.swift).


## Output Formatting Controls

Customize how results appear in your terminal or pipeline:

- **`--format <text|json>`** – Explicitly choose between human-readable text or structured JSON.
- **`--json`** – Convenience alias for `--format json`.
- **`--json-only`** – Emit JSON output exclusively, suppressing all other console output.
- **`--pretty`** – Pretty-print JSON with indentation for easier reading.
- **`--no-credits`** – Omit the "Codex credits" consumption line from output.
- **`--no-color`** – Disable ANSI colors in text output for piping to files.

Output formats are governed by the `OutputFormat` enum defined in [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift) (lines 23-33), ensuring type-safe parsing of format preferences.


## Status Checks and Source Control

Manage data sources and request metadata:

- **`--status`** – Include provider status information in the result payload.
- **`--source <auto|web|cli|oauth|api>`** – Specify the data source strategy. The `auto` behavior varies per provider implementation.
- **`--web`** – Shorthand alias for `--source web`.
- **`--web-timeout <seconds>`** – Set a custom timeout duration for HTTP fetches.
- **`--web-debug-dump-html`** – Dump HTML snapshots to `/tmp` when dashboard data is missing, useful for debugging scrapers.

These flags are processed during the provider initialization phase in [`Sources/CodexBarCLI/CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIEntry.swift), where the Commander framework binds command arguments to the `UsageOptions` configuration.


## Debug Helper Flags

Advanced diagnostics for development and troubleshooting:

- **`--antigravity-plan-debug`** – Emit Antigravity planInfo fields for debugging billing or plan-related issues.
- **`--augment-debug`** – Output raw Augment API responses to inspect intermediate data structures.

These debug flags expose internal API responses that are normally hidden, aiding integration testing and provider-specific troubleshooting.


## Practical Usage Examples

Run the CLI with specific providers and output formats:

```bash

# Query Anthropic provider with verbose logging

codexbar --provider anthropic -v

# Get JSON status from OpenAI and pretty-print

codexbar --provider openai --status --json --pretty

# Use a specific account label with JSON-only output

codexbar --account "my-work-account" --json-only

# Debug web scraping with HTML dumps and extended timeout

codexbar --web --web-timeout 30 --web-debug-dump-html

```


## Key Implementation Files

Understanding the CLI architecture requires examining these specific source files:

| File | Purpose |
|------|---------|
| [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift) | Defines `UsageOptions`, `ProviderSelection`, and `OutputFormat` structs containing all argument definitions. |
| [`Sources/CodexBarCLI/CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIEntry.swift) | Entry point wiring Commander to parse `UsageOptions` and execute commands. |
| [`Sources/CodexBarCLI/CLIHelp.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIHelp.swift) | Generates help text displayed by `codexbar --help`. |
| [`Sources/CodexBarCore/ProviderDescriptorRegistry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/ProviderDescriptorRegistry.swift) | Maps provider CLI names to internal descriptors. |
| [`Tests/CodexBarTests/CLIArgumentParsingTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/CLIArgumentParsingTests.swift) | Unit tests validating argument parsing logic. |


## Summary

- **CodexBar command-line arguments** are centralized in [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift) within the `UsageOptions` struct.
- Use **`--provider`** and **`--account`** flags to select AI providers and credentials dynamically.
- Control output structure with **`--format json`**, **`--pretty`**, and **`--json-only`** for automation pipelines.
- Enable debugging via **`--verbose`**, **`--log-level`**, and provider-specific flags like **`--augment-debug`**.
- The CLI leverages the **Commander** library for type-safe argument parsing, with comprehensive tests in [`CLIArgumentParsingTests.swift`](https://github.com/steipete/CodexBar/blob/main/CLIArgumentParsingTests.swift).


## Frequently Asked Questions

### How do I see all available providers for the `--provider` flag?

Run `codexbar --help` with the verbose flag or inspect the `ProviderHelp.list` output. The available names are generated dynamically from `ProviderDescriptorRegistry` in [`Sources/CodexBarCore/ProviderDescriptorRegistry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/ProviderDescriptorRegistry.swift), and typically include values like `anthropic` and `openai`.

### What is the difference between `--json` and `--json-only`?

The **`--json`** flag (or `--format json`) includes JSON output alongside other console messages, while **`--json-only`** suppresses all non-JSON text, emitting strictly machine-readable JSON suitable for piping to other programs or files.

### Where are the CLI argument definitions located in the source code?

All command-line flags are defined in [`Sources/CodexBarCLI/CLIOptions.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIOptions.swift), specifically within the `UsageOptions` struct which implements `CommanderParsable`. The parsing logic and entry point reside in [`Sources/CodexBarCLI/CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIEntry.swift).

### Can I use multiple accounts in a single command?

Yes. Use the **`--all-accounts`** flag to fetch data across all configured token accounts, or specify individual accounts with **`--account <label>`** or **`--account-index <n>`** for targeted queries.