# Cross-Platform Differences for CodexBar CLI Builds: macOS vs Linux Guide

> Discover cross-platform differences for CodexBar CLI builds between macOS and Linux. Learn about packaging, installation, and feature variations. Essential guide from steipete/CodexBar.

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

---

**CodexBarCLI ships with different binary packaging, installation methods, and feature capabilities between macOS and Linux, primarily due to macOS-exclusive WebKit integration for browser cookie import and the need for musl versus glibc variants on Linux.**

The **steipete/CodexBar** repository distributes **CodexBarCLI** as both a bundled helper within the macOS menu-bar app and a standalone command-line tool. While the core Swift codebase compiles across platforms using standard Swift Package Manager commands, the build artifacts, supported features, and installation workflows diverge significantly between Apple's ecosystem and Linux distributions.

## Binary Packaging and Architecture Support

Distribution artifacts are platform-specific, reflecting different linker requirements and system library dependencies.

### macOS Tarballs

macOS distributes two architecture-specific archives following the naming convention `CodexBarCLI-v<version>-macos-arm64.tar.gz` and `CodexBarCLI-v<version>-macos-x86_64.tar.gz`. These binaries link against system Apple frameworks including **AppKit** and **WebKit**, as documented in the CLI release section at [`cli.md#L22-L24`](https://github.com/steipete/CodexBar/blob/main/docs/cli.md#L22-L24).

### Linux Variants

Linux ships four distinct artifacts to accommodate different C library implementations:

- **glibc builds**: `CodexBarCLI-v<version>-linux-aarch64.tar.gz` and `CodexBarCLI-v<version>-linux-x86_64.tar.gz`
- **static-musl builds**: `CodexBarCLI-v<version>-linux-musl-aarch64.tar.gz` and `CodexBarCLI-v<version>-linux-musl-x86_64.tar.gz`

According to [`cli.md#L23-L24`](https://github.com/steipete/CodexBar/blob/main/docs/cli.md#L23-L24), the musl variants provide broader distribution compatibility by embedding the C library, while glibc builds depend on the host system's libc.

## Installation Methods and Paths

### macOS App-Based Installation

When running the menu-bar app, users can navigate to **Preferences → Advanced → Install CLI** to automatically create symlinks at `/usr/local/bin/codexbar` and `/opt/homebrew/bin/codexbar`. Manual linking is also supported:

```bash
ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

```

### Linux Homebrew and Manual Setup

Linux users install via the Homebrew tap `steipete/tap/codexbar`, which pulls the glibc variant as specified in [`releasing-homebrew.md#L35-L39`](https://github.com/steipete/CodexBar/blob/main/docs/releasing-homebrew.md#L35-L39). No automatic symlink creation exists from a GUI app; users must manually copy or link the binary:

```bash
brew install steipete/tap/codexbar

# Or manual extraction

tar -xzf CodexBarCLI-v1.0.0-linux-x86_64.tar.gz
sudo mv CodexBarCLI /usr/local/bin/codexbar

```

## Build Configuration

Both platforms use the same Swift build command:

```bash
swift build -c release --product CodexBarCLI

```

On macOS, the resulting binary is bundled into `CodexBar.app/Contents/Helpers/` by the [`./Scripts/package_app.sh`](https://github.com/steipete/CodexBar/blob/main/./Scripts/package_app.sh) script. For Linux static builds, the musl variant requires explicit target specification:

```bash
swift build -c release --product CodexBarCLI -target x86_64-unknown-linux-musl

```

## Feature Parity and Limitations

### Browser Cookie Import

**WebKit-based browser cookie import is macOS-only**. On macOS, the `web` source mode can automatically fall back to browser import using native WebKit APIs. Linux lacks this capability entirely, requiring users to rely on **manual cookie configuration** or local SQLite usage databases (such as those provided by OpenCode Go).

### File System Permissions

When writing configuration or cache files, both platforms set permissions to `0600` for consistency, ensuring sensitive credential data remains accessible only to the owner regardless of operating system.

## Runtime Dependencies

macOS binaries depend on Apple-provided system libraries. Linux presents two distinct runtime profiles:

- **glibc builds**: Require the host system to provide the standard C library
- **musl builds**: Self-contained with embedded libc, runnable on any Linux distribution without additional packages

## Summary

- **Packaging**: macOS provides two architecture builds; Linux provides four (glibc and musl for both arm64 and x86_64)
- **Installation**: macOS supports GUI-based symlink creation; Linux relies on Homebrew or manual extraction
- **Features**: Browser cookie import and automatic `web` source mode are exclusive to macOS due to WebKit dependency
- **Portability**: Linux musl builds offer maximum portability by embedding the C library, while glibc builds have external dependencies

## Frequently Asked Questions

### Can I use browser cookie import on Linux?

**No.** Browser cookie import requires WebKit frameworks that are only available on macOS. Linux users must configure cookies manually or use local SQLite databases for authentication.

### What is the difference between glibc and musl builds for Linux?

**glibc builds** link against the host system's GNU C Library, requiring compatible system versions. **musl builds** statically link the musl libc implementation, creating a self-contained binary that runs on any Linux distribution without external dependencies.

### How do I install CodexBarCLI manually on macOS without Homebrew?

Extract the appropriate tarball and create a symbolic link to the binary location inside the app bundle:

```bash
ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

```

This bypasses the automatic installation available in the app's Preferences menu.

### Why does the Linux version lack automatic symlink creation from the GUI?

The Linux build of CodexBar does not include the menu-bar app helper that manages `/usr/local/bin` and `/opt/homebrew/bin` symlinks on macOS. Linux installation requires explicit manual copying or Homebrew formula management, as the platform typically lacks the standardized GUI-to-CLI integration paths available on macOS.