# How to Install steipete/CodexBar on macOS and Linux

> Install steipete CodexBar on macOS and Linux using Homebrew Cask, GitHub releases, or the CLI helper. Get started with CodexBar quickly and easily.

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

---

**You can install CodexBar via Homebrew Cask on macOS, download pre-built binaries from GitHub Releases for macOS and Linux, or install the bundled CLI helper after setting up the UI app.**

**CodexBar** is a lightweight menu-bar application for macOS 14+ that tracks AI-coding quota usage across multiple providers. The repository at `steipete/CodexBar` distributes both a graphical UI app and a command-line interface (CLI), with installation methods varying by platform and use case.

## Installation Methods Overview

CodexBar supports three primary installation paths depending on your operating system and whether you need the menu-bar UI or just the CLI:

- **Homebrew Cask** (macOS only): Installs the signed UI app (`CodexBar.app`) to `/Applications`
- **GitHub Releases** (macOS and Linux): Provides universal macOS zips and architecture-specific CLI tarballs
- **Bundled CLI Installer** (macOS only): Creates symlinks to the CLI helper embedded within the UI app bundle at `/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI`

## Install CodexBar on macOS

### Using Homebrew Cask (Recommended)

The fastest way to install CodexBar on macOS is through the official Homebrew Cask. This method disables Sparkle auto-updates to ensure version management remains controlled through Homebrew.

```bash
brew install --cask codexbar

```

After installation completes, launch the app:

```bash
open -a CodexBar

```

According to the **Homebrew release playbook** at [`docs/releasing-homebrew.md`](https://github.com/steipete/CodexBar/blob/main/docs/releasing-homebrew.md), the cask downloads `CodexBar-macos-universal-<version>.zip` from GitHub Releases and extracts it to `/Applications`. The build process specifically disables Sparkle updates for Homebrew installs, routing update notifications to use `brew upgrade` instead.

### Manual Installation from GitHub Releases

If you prefer not to use Homebrew, download the universal binary directly from the releases page:

```bash

# Download the latest universal build

curl -L -o CodexBar.zip \
  https://github.com/steipete/CodexBar/releases/latest/download/CodexBar-macos-universal.zip

# Extract and move to Applications

unzip CodexBar.zip
mv CodexBar.app /Applications/
open -a CodexBar

```

### Installing the Bundled CLI Helper

Once the UI app resides in `/Applications`, you can expose the `codexbar` command-line tool to your system `PATH` using the provided installer script in [`bin/install-codexbar-cli.sh`](https://github.com/steipete/CodexBar/blob/main/bin/install-codexbar-cli.sh):

```bash

# From the cloned repository or downloaded source

./bin/install-codexbar-cli.sh

```

This script uses AppleScript (`osascript`) to request administrative privileges, then creates symbolic links at standard binary locations defined in the script's `TARGETS` variable—specifically `/usr/local/bin/codexbar` and `/opt/homebrew/bin/codexbar`—pointing to `/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI`.

Verify the installation by checking the version:

```bash
codexbar version

```

## Install CodexBar CLI on Linux

Linux users can only install the CLI component, as the menu-bar UI requires macOS 14+. The GitHub Releases page provides four architecture-specific tarballs:

| Asset | Architecture |
|-------|--------------|
| `CodexBarCLI-v<tag>-linux-x86_64.tar.gz` | x86_64 |
| `CodexBarCLI-v<tag>-linux-aarch64.tar.gz` | ARM64 |

Download and extract the appropriate binary for your system:

```bash

# Example for x86_64 Linux

curl -L -o codexbar.tar.gz \
  https://github.com/steipete/CodexBar/releases/latest/download/CodexBarCLI-v<version>-linux-x86_64.tar.gz

sudo tar -xzf codexbar.tar.gz -C /usr/local/bin
codexbar usage

```

## Post-Installation Setup

After installation, configure CodexBar to track your AI provider usage. The application stores resolved configuration at `~/.config/codexbar/config.json` (modern installs) or `~/.codexbar/config.json` (legacy).

1. Launch the app (`open -a CodexBar`) or run the CLI
2. Navigate to **Settings → Providers** in the UI or use CLI commands
3. Enable desired providers:

```bash

# List available providers

codexbar config providers

# Enable specific providers

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

# Store API keys securely (example for ElevenLabs)

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

```

The UI app (`Sources/CodexBar`) and CLI (`Sources/CodexBarCLI`) share the same underlying state management through `UsageStore` and `SettingsStore`, ensuring synchronized configuration regardless of which interface you use.

## Summary

- **Homebrew Cask** provides the easiest macOS installation: `brew install --cask codexbar`
- **Manual downloads** work for both macOS UI and Linux CLI installations from GitHub Releases
- **CLI helper installation** requires running [`bin/install-codexbar-cli.sh`](https://github.com/steipete/CodexBar/blob/main/bin/install-codexbar-cli.sh) after placing the app in `/Applications`
- Configuration persists in `~/.config/codexbar/config.json` and syncs between UI and CLI components
- Both interfaces rely on the same core modules: `Sources/CodexBar` for the UI and `Sources/CodexBarCLI` for command-line operations

## Frequently Asked Questions

### Can I run the CodexBar UI on Linux?

No. The graphical menu-bar application requires macOS 14 or later. Linux users should download the `CodexBarCLI` tarball from GitHub Releases and use the command-line interface exclusively. The CLI provides full quota tracking capabilities via terminal commands.

### How do I update CodexBar when installed via Homebrew?

Run `brew upgrade --cask codexbar` to update to the latest version. The Homebrew cask intentionally disables Sparkle automatic updates to prevent conflicts with Homebrew's package management system. The About panel in the app will display a message directing you to update via Homebrew rather than through the built-in updater.

### Where does CodexBar store its configuration files?

CodexBar stores resolved configuration at `~/.config/codexbar/config.json` for new installations. Legacy installs may still use `~/.codexbar/config.json`. Both the UI app in `Sources/CodexBar` and the CLI in `Sources/CodexBarCLI` read from this location, ensuring settings remain consistent across interfaces.

### Do I need to install the CLI separately if I use the Homebrew Cask?

Yes, if you want command-line access. The Homebrew Cask only installs the UI app bundle. To enable the `codexbar` command in your terminal, run the bundled installer script at [`bin/install-codexbar-cli.sh`](https://github.com/steipete/CodexBar/blob/main/bin/install-codexbar-cli.sh) after the UI app is installed, or manually symlink `/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI` to a directory in your `PATH`.