br — Bitrise CLI

A gh-style CLI for accessing Bitrise build history and logs from your terminal or AI assistants (Claude / Cursor).

Unofficial tool: This is a community CLI, not affiliated with Bitrise's official product (bitrise-io/bitrise). Bitrise is a trademark of Bitrise Ltd. It uses the Bitrise API v0.1; behavior is not guaranteed.

Installation

brew install novr/taps/br          # macOS (Apple Silicon / Intel)

On Linux, download from Releases (br_<version>_linux_<arch>.tar.gz):

VERSION=0.1.0
ARCH=$(uname -m)   # x86_64 → amd64, aarch64 → arm64
case "${ARCH}" in x86_64) ARCH=amd64 ;; aarch64|arm64) ARCH=arm64 ;; esac
curl -fsSL "https://github.com/novr/bitrise-cli/releases/download/v${VERSION}/br_${VERSION}_linux_${ARCH}.tar.gz" | tar -xz
sudo mv br /usr/local/bin/

Or:

go install github.com/novr/bitrise-cli/cmd/br@latest

Or build / install manually:

make install                 # installs to /usr/local/bin/br
go build -o br ./cmd/br      # builds br in the current directory

Authentication

Create a Bitrise Personal Access Token, then:

br auth login
# Create a Personal Access Token at https://app.bitrise.io/me/profile#/security
# ? Paste your Bitrise Personal Access Token: ********************
# ✓ Logged in

The login flow prints the token URL only; it does not open a browser. For CI and scripts, pipe the token on stdin:

echo "$BITRISE_API_TOKEN" | br auth login --with-token

Environment variables take precedence (no br auth login required). Use BITRISE_API_TOKEN (recommended) or BITRISE_TOKEN:

export BITRISE_API_TOKEN=<your-token>

To isolate multiple Bitrise accounts without built-in profiles, set BR_CONFIG_DIR (see Config files).

Usage

List builds

The Bitrise app is resolved from --app, BITRISE_APP_SLUG, .br.yml, or the git remote (see App auto-detection).

br build list
br build list --limit 20
br build list --branch main --status failed   # status: success/failed/error/running/aborted
br build list --branch @current               # current git branch

If a git remote exists but matches no accessible Bitrise app, the command errors (to avoid targeting the wrong app). Override with --app <slug> or .br.yml.

JSON output for AI assistants (Claude / Cursor):

br build list --limit 3 --json status,buildNumber,branch,workflow

[
  {"status": "success", "buildNumber": 124, "branch": "main", "workflow": "primary"},
  {"status": "failed",  "buildNumber": 123, "branch": "feature/auth", "workflow": "deploy"},
  {"status": "running", "buildNumber": 122, "branch": "main", "workflow": "primary"}
]

--json all returns every field. Unknown field names produce an error.

Build details

br build view 123
br build view 123 --json status,buildNumber,failedSteps

{
  "status": "error",
  "buildNumber": 123,
  "failedSteps": [{"name": "run-xcode-tests@2.4.1", "exitCode": 1}]
}

Human output example:

br build view 123
# ✗ failed  #123  deploy  (branch: feature/auth)
#   Commit:    add-login  (abc1234)
#   Triggered: 15m ago
#   Duration:  5m32s
#
#   ✗ Step failed: run-xcode-tests@2.4.1 (exit code: 1)
#
#   To see full logs:   br build logs 123
#   To see errors only: br build logs 123 --failed-only

Logs

br build logs 123               # full log
br build logs 123 --failed-only # failed steps only
br build logs 123 --json steps,failedStepLogs

--failed-only is especially useful when asking Claude / Cursor to analyze logs and suggest fixes.

Watch a running build

br build watch 123
br build watch 123 --exit-status          # exit 1 on failure (for CI)
br build watch 123 --json status,buildNumber,failedSteps

Polls until the build finishes. Use --interval (minimum 3s) to control polling frequency.

GitHub Action

Gate a workflow on a Bitrise build with the bundled composite action. build-number is required — resolving "the latest build" by branch is unreliable and can pass on an unrelated build.

- uses: novr/bitrise-cli/.github/actions/check@v0.2.0
  with:
    token: ${{ secrets.BITRISE_API_TOKEN }}
    build-number: ${{ needs.trigger.outputs.build-number }}
    app: <app-slug>          # optional; falls back to .br.yml / git remote
    version: v0.2.0          # optional; defaults to the latest release tag
    exit-status: "true"      # optional; fail the step on non-success (default)
    interval: "5s"           # optional; minimum 3s

The action downloads the matching br release binary (Linux amd64/arm64, macOS universal) and runs br build watch <n> --exit-status --json ….

App list

br app list
br app list --json slug,title   # fields: slug, title, repoURL, or all

Version

br version

Configuration

br config show                # global config + effective .br.yml path/app
br config set app <app-slug>  # write .br.yml in the current directory

Diagnostics

br doctor   # check auth, app resolution, and API reachability (CI-friendly)

Common flags

Flag	Description
--app <slug>	Bitrise app slug (overrides auto-detection)
BITRISE_APP_SLUG	App slug via environment variable

App auto-detection

br build commands resolve the app in this order:

1. --app flag
2. BITRISE_APP_SLUG environment variable
3. .br.yml (current directory upward to git root)
4. git remote get-url origin matched against Bitrise app repo_url

Global default_app was removed. A single home-dir fallback could silently target the wrong app in monorepos and multi-repo setups.

Project-local config (.br.yml)

Commit app slugs to the repo so the team shares the same target. Discovery walks up to git root (not bitrise.yml), because Bitrise monorepos usually centralize CI at the repo root and subpackages should inherit the root .br.yml.

app: <app-slug>

monorepo/
  .br.yml          # used when a subdirectory has no .br.yml
  ios/
    .br.yml        # point at a different Bitrise app on the same origin

Run br config set app <slug> to write the file in the current directory. Use --app when the fork's origin does not match Bitrise. Slug/git mismatches are easy to miss in daily use; run br doctor in CI.

Agent skill (Cursor / Claude)

Install the br skill so agents know how to use this CLI (requires this repo on GitHub):

npx skills add novr/bitrise-cli --skill br -g -y   # global (~/.cursor/skills/, etc.)
npx skills add novr/bitrise-cli --skill br -y      # project-local only

AI assistant workflow

Ask Claude or Cursor something like:

Check whether the latest Bitrise build failed; if it did, analyze the logs and suggest fixes.

br build list --limit 1 --json status,buildNumber
br build logs 123 --failed-only

Config files

Global config path resolution:

1. BR_CONFIG_DIR (empty string is treated as unset)
2. Default ~/.config/br ($HOME/.config/br)

The global config.yml in that directory stores the token only. App slugs live in project .br.yml (commit recommended for team sharing and monorepo switching).

token: <your-token>

Switch configs per project with direnv (or any env manager). Relative BR_CONFIG_DIR values are resolved from the process working directory at startup.

# .envrc
export BR_CONFIG_DIR="$HOME/.config/br-work"

BR_CONFIG_DIR="$HOME/.config/br-work" br auth login
BR_CONFIG_DIR="$HOME/.config/br-personal" br auth status

Security note: Tokens are stored in plain text with mode 0600 (owner read/write only). Like gh, there is no OS keychain encryption. On shared machines, prefer the BITRISE_API_TOKEN environment variable.