☕ CoffeeBreak CLI Installation Guide

Get the CoffeeBreak CLI running on your device using signed, portable builds for macOS, Windows, and Linux. This guide complements the in-app onboarding quick-start card so workspace owners can share the same download links with their teams.

Note: Platform-native installers (MSI / PKG) are planned. The current distribution uses portable archives for maximum compatibility and transparency.

Downloads (Latest Stable)

Platform	Package	Checksums	Notes
macOS (Apple Silicon)	`coffeebreak-cli-osx-arm64.tar.gz`	`checksums.txt`	Portable archive. Includes `coffeebreak` launcher.
macOS (Intel)	`coffeebreak-cli-osx-x64.tar.gz`	`checksums.txt`	Same experience as Apple Silicon.
Windows 64-bit	`coffeebreak-cli-win-x64.zip`	`checksums.txt`	Portable ZIP. Includes `coffeebreak.cmd`.
Linux (glibc)	`coffeebreak-cli-linux-x64.tar.gz`	`checksums.txt`	Works on most modern distributions.
Linux (musl)	`coffeebreak-cli-linux-musl-x64.tar.gz`	`checksums.txt`	Alpine-compatible build.

ℹ️ Download links always point to the latest stable release. To pin a specific version, replace latest with a semantic version (for example, v1.6.0). Use latest.json in the same directory to resolve versions programmatically.

Verifying a download

Each release includes a shared checksum file:

curl -fsSL https://downloads.coffeebreakai.dev/cli/stable/latest/checksums.txt | \
  grep "coffeebreak-cli-linux-x64.tar.gz"

If signatures are published for your artifact, you can also download the corresponding .sig file and verify it using the public certificate included in the manifest.

Installation

macOS & Linux

tar -xzf coffeebreak-cli-<platform>.tar.gz
cd coffeebreak-cli-<platform>
./coffeebreak --version

Optional: add the directory to your PATH:

export PATH="$PATH:/path/to/coffeebreak-cli"

You may want to add this line to ~/.bashrc, ~/.zshrc, or your shell profile.

Windows

Extract coffeebreak-cli-win-x64.zip
Open the extracted folder
Run:

coffeebreak.cmd --version

Optional: add the folder to your system PATH so coffeebreak is available from any terminal.

README included in every archive

Each download includes a README.txt with:

Platform-specific run instructions
PATH setup examples
Documentation links
Notes on signatures and future installers

This ensures offline installs remain self-contained and support-friendly.

Configure authentication

The CLI needs a workspace ID and access token to authenticate. Retrieve these from your workspace admin settings:

Open Admin → Version control.
Copy the workspace ID and generate a workspace access token.

Set the canonical environment variables:

export COFFEEBREAK__WORKSPACE__ID="00000000-0000-0000-0000-000000000000"
export COFFEEBREAK__ACCESS__TOKEN="cb_pat_your_token_here"
export COFFEEBREAK__API__BASE_URL="https://api.coffeebreakai.dev"

Prefer environment variables for automation, or save these values in ~/.coffeebreak/config.json if you are using profiles:

{
  "defaultProfile": "production",
  "profiles": {
    "production": {
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "accessToken": "cb_pat_your_token_here",
      "apiBaseUrl": "https://api.coffeebreakai.dev"
    }
  }
}

Verifying your installation

After installation, confirm connectivity and agent availability:

coffeebreak doctor run \
  --workspace-id 00000000-0000-0000-0000-000000000000 \
  --api-base-url https://api.coffeebreakai.dev \
  --access-token cb_pat_your_token_here \
  --output table

The command validates authentication, enumerates enabled agents, and reports any policy mismatches. See CoffeeBreak CLI Doctor for full diagnostics coverage.

Updating to newer releases

Download and extract the newer archive — existing binaries can be replaced in place.
latest.json exposes version, hashes, and signing metadata for automation.
Internal or branded builds can be generated using:

scripts/package-cli.sh

This emits signed artifacts, checksums, and release metadata suitable for CI/CD and compliance pipelines.

Troubleshooting

Symptom	Resolution
`coffeebreak` not found	Ensure the extracted directory is on your `PATH`, or invoke via `./coffeebreak` / `coffeebreak.cmd`.
Permission denied on macOS/Linux	Run `chmod +x coffeebreak`.
TLS errors when fetching packages	Confirm your proxy trusts CoffeeBreak’s certificate chain and allows outbound access to `downloads.coffeebreakai.dev`.
Authentication failures	Generate a new workspace access token from Admin → Version control and set `COFFEEBREAK__ACCESS__TOKEN`.
Workspace not found	Confirm `COFFEEBREAK__WORKSPACE__ID` is the workspace you expect and matches the token’s workspace.
API base URL mismatch	Set `COFFEEBREAK__API__BASE_URL` to the API host for your workspace deployment.

Need additional help? Visit the in-app Support page or email support@coffeebreakai.dev

ℹ️ COFFEEBREAK_ACCESS_TOKEN is still accepted for legacy scripts, but COFFEEBREAK__ACCESS__TOKEN is the canonical variable going forward.

What’s coming next (no action required)

Native Windows MSI (PATH + uninstall support)
macOS PKG installer
Optional Linux .deb / .rpm

These will be additive — existing automation and portable installs will continue to work.

Documentation