# Does CodexBar Have a GUI or Is It CLI Only? Complete Interface Guide > CodexBar offers both a macOS GUI and a CLI for monitoring AI coding usage. Access features via a visual menu bar or terminal commands for ultimate flexibility. - Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar) - Tags: how-to-guide - Published: 2026-07-07 --- **CodexBar provides both a native macOS menu-bar GUI and a fully-featured command-line interface, allowing users to monitor AI coding usage through either a visual status bar or terminal commands.** CodexBar is a macOS 14+ utility designed to track usage and costs across multiple AI coding providers. Unlike tools that force you to choose between graphical and terminal interfaces, this open-source application delivers both experiences through a unified architecture. The primary interface runs as a lightweight menu-bar application, while a bundled `codexbar` executable offers headless automation capabilities and Linux support. ## The Primary Interface: Native macOS Menu-Bar GUI CodexBar functions primarily as a **macOS menu-bar application** that displays usage meters, reset timers, and status icons for various AI-coding providers. The application runs as an `LSUIElement`, meaning it operates without a Dock icon and persists only as a custom status item in the system menu bar. ### Architecture and Implementation The GUI implementation centers on [`Sources/CodexBar/StatusItemController.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemController.swift), which constructs the `NSStatusBar` item, handles menu interactions, and renders the icon. The application entry point in [`Sources/CodexBar/AppDelegate.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/AppDelegate.swift) initializes this controller alongside the Sparkle updater framework. Key characteristics of the GUI implementation include: - **LSUIElement configuration**: No Dock icon appears when the app launches - **NSStatusBar integration**: Native macOS menu-bar rendering via `StatusItemController` - **Visual indicators**: Real-time usage meters and provider status icons According to [`docs/ui.md`](https://github.com/steipete/CodexBar/blob/main/docs/ui.md), the interface provides immediate visual feedback for API usage quotas and billing cycles without requiring terminal interaction. ## The Command-Line Interface (CLI) In addition to the graphical front-end, CodexBar ships with a **bundled command-line interface** accessible via the `codexbar` binary. The CLI sources reside under `Sources/CodexBarCLI/`, with argument parsing and command dispatch handled in [`Sources/CodexBarCLI/CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIEntry.swift). ### CLI Commands and Usage The CLI supports configuration management and cost queries that mirror the GUI's functionality: ```bash # Launch the GUI (macOS) open CodexBar.app # builds the app with ./Scripts/package_app.sh # Use the bundled CLI to list enabled providers codexbar config providers # → prints the provider list read from the config file # Enable a provider from the command line codexbar config enable --provider grok # Run a cost‑usage scan from the terminal (works on macOS and Linux) codexbar cost --provider openai # prints OpenAI spend/credits summary ``` These commands execute the same core logic as the GUI buttons, reading from identical configuration stores and API endpoints. ## Shared Architecture and Data Layer Both interfaces consume the same underlying **usage-store and provider logic**, ensuring consistency whether you click a menu item or run a shell script. As documented in [`docs/architecture.md`](https://github.com/steipete/CodexBar/blob/main/docs/architecture.md), the project separates concerns into distinct modules: - **GUI modules** (`CodexBar`): AppKit-dependent code for macOS UI rendering - **CLI modules** (`CodexBarCLI`): Argument parsing and terminal output formatting via [`CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/CLIEntry.swift) - **Shared core**: Business logic for API querying and data persistence This architecture enables Linux builds that leverage the CLI functionality without requiring macOS-specific UI frameworks. ## Platform Availability and Launch Methods Users can access CodexBar through multiple entry points depending on their platform and workflow: ```bash # macOS: Launch the GUI (menu bar appears automatically, no Dock icon shown) open CodexBar.app # macOS/Linux: Execute CLI commands for automation codexbar cost --provider openai codexbar config enable --provider anthropic ``` The menu-bar GUI appears automatically after launching the `.app` bundle, while CLI commands execute immediately and exit without spawning the graphical interface. Linux distributions receive only the CLI components, as the GUI relies on macOS-specific `NSStatusBar` APIs. ## Summary - **CodexBar offers both GUI and CLI interfaces**, not just one or the other. - The **primary interface** is a macOS menu-bar app (`LSUIElement`) implemented in [`Sources/CodexBar/StatusItemController.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemController.swift). - The **CLI** provides headless automation via [`Sources/CodexBarCLI/CLIEntry.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCLI/CLIEntry.swift) and works on both macOS and Linux. - Both interfaces share identical **usage-store and provider logic** for consistent data across platforms. - The GUI runs without a Dock icon, appearing only in the system status bar. ## Frequently Asked Questions ### Can I use CodexBar without the macOS GUI? Yes. The `codexbar` CLI functions independently on macOS and Linux systems, allowing you to query costs and manage providers entirely from the terminal. The CLI shares the same configuration files and API logic as the graphical interface. ### Does CodexBar show a Dock icon when running? No. CodexBar runs as an `LSUIElement` (background-only application), so it displays only in the menu bar without appearing in the Dock or Command-Tab switcher. This behavior is implemented in [`Sources/CodexBar/AppDelegate.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/AppDelegate.swift) and confirmed in [`docs/ui.md`](https://github.com/steipete/CodexBar/blob/main/docs/ui.md). ### How do I access the CLI if I only downloaded the GUI app? The CLI binary is bundled inside the CodexBar application bundle. You can typically access it at `CodexBar.app/Contents/MacOS/codexbar` or install it to your system path using the provided installation scripts. The CLI is documented separately in [`docs/cli.md`](https://github.com/steipete/CodexBar/blob/main/docs/cli.md). ### Is the Linux version of CodexBar CLI-only? Yes. Linux builds provide only the command-line interface located in `Sources/CodexBarCLI/`, as the menu-bar GUI relies on macOS-specific AppKit frameworks (`NSStatusBar`) found in [`Sources/CodexBar/StatusItemController.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/StatusItemController.swift).