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

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.

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 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.
• --account <label> – Target a specific token-account label defined in your 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.

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 (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, 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:

# 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	Defines UsageOptions, ProviderSelection, and OutputFormat structs containing all argument definitions.
Sources/CodexBarCLI/CLIEntry.swift	Entry point wiring Commander to parse UsageOptions and execute commands.
Sources/CodexBarCLI/CLIHelp.swift	Generates help text displayed by codexbar --help.
Sources/CodexBarCore/ProviderDescriptorRegistry.swift	Maps provider CLI names to internal descriptors.
Tests/CodexBarTests/CLIArgumentParsingTests.swift	Unit tests validating argument parsing logic.

Summary

• CodexBar command-line arguments are centralized in 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.

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, 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, specifically within the UsageOptions struct which implements CommanderParsable. The parsing logic and entry point reside in 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.

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