Use the CLI

The logbrew CLI is the primary LogBrew interface for developers and AI coding agents. Use it to log in, check status, read telemetry, explain failures, and update issue status.

Install choices

Use a native installer when you want the fastest path on a new machine.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.ps1 | iex"

Use a package manager when it fits your workflow.

brew install LogBrewCo/tap/logbrew
npm install -g logbrew-cli
cargo install logbrew-cli

Cargo and source builds require Rust 1.87 or newer. Native installers, npm, Homebrew, and the Windows MSI use release artifacts and do not need a local Rust toolchain.

Update an existing install

Existing CLI installations do not update themselves. Refresh the same install surface before using a newly documented command or setup plan:

brew update && brew upgrade LogBrewCo/tap/logbrew
npm install -g logbrew-cli@latest
cargo install --locked logbrew-cli

Rerun the GitHub Release shell or PowerShell installer when that installer owns the binary. Compare the installed binary with the latest public release:

logbrew version --json

First checks

logbrew status --json
logbrew read releases --environment production --json

If the CLI is not authenticated, it tells you what to do next:

not logged in: run logbrew login

GitHub is the default login provider. Select GitLab or Bitbucket when the account uses another provider.

logbrew login --provider github
logbrew status --json
logbrew whoami --json

Use --no-open to print a login URL without opening a browser. Use --json for the same non-opening handoff in machine-readable form. Agents should not guess auth state or account identity. Run logbrew status --json to check API reachability and authentication. Run logbrew whoami --json to read the authenticated account identity. If auth is missing, ask a human to complete logbrew login --provider <provider>, then continue after both checks pass. CLI output must not print stored auth material.

Built-in examples

Use the examples command when you need a compact command map for first-run checks, troubleshooting, live watch, or agent JSON workflows.

logbrew examples
logbrew help examples

Discovery aliases such as example, sample, samples, recipe, and recipes open the same examples guide.

Plan Swift SDK setup

Run setup from the root of a SwiftPM or XcodeGen project.

logbrew setup --json

The command detects supported manifests and returns a non-mutating install plan. For Swift projects, install_ready is true and the compatible release range starts at 0.1.6. Copy the returned dependency_declaration into the project package list, then add the LogBrew product to the target that sends telemetry. The command does not change project files. logbrew init, logbrew install, logbrew configure, and logbrew sdk return the same plan. See the CLI reference for the complete stable install_plan field contract.

Plan C++ SDK setup

Run setup from the root of a CMake project. CLI v0.1.39 or newer detects a regular root CMakeLists.txt without scanning build or cmake-build-* output directories.

logbrew setup --json \
  | jq '{detected, install_ready, install_plan, next}'

For CMake projects, install_ready is true. The plan pins C++ SDK 0.2.3, returns a copyable FetchContent declaration, and names the LogBrew::LogBrew core target. Optional hosted delivery uses LogBrew::HttpTransport, LOGBREW_BUILD_HTTP_TRANSPORT=ON, and libcurl. If CMakeLists.txt exists but detected is empty, use the update steps above and rerun setup. Do not manually recreate the plan from an older CLI result. Copy the returned dependency_declaration into CMakeLists.txt, then link the required target to the application target. The command does not install a package, edit the manifest, or enable the optional HTTP dependency. See Send SDK telemetry for the complete copy-paste build and verification flow.

Plan Python SDK setup

Run setup from the root of a Python project. The CLI detects pyproject.toml, Pipfile, supported lockfiles, and bounded dependency metadata without following manifest symlinks.

logbrew setup --json \
  | jq '{detected, install_ready, install_plan, next}'

For Python projects, the plan uses released PyPI packages and the detected pip, uv, poetry, or pipenv command. It reports Python >=3.10. Detected framework plans add logbrew-django, logbrew-flask, or logbrew-fastapi next to logbrew-sdk. CLI v0.1.30 reports these framework compatibility requirements:

Integration	Requirement
Django	`Django>=4.2.30,<6`
Flask	`Flask>=3.1`
FastAPI	`FastAPI>=0.111.1`

Review install_plan.compatibility, then run the returned install_command. The setup command does not install packages or change project files.

Track project setup

The CLI can record that setup was observed for an existing project. Use it when a setup screen, CLI flow, or agent has enough context to mark setup progress without guessing from local files.

logbrew projects setup <project_id> --source cli --environment production --json
logbrew project setup <project_id> --runtime <runtime> --source sdk --env production --json

The command calls POST /api/projects/{project_id}/setup/seen and returns the LogBrew project setup state as JSON. Human output starts with Project setup seen: <status> and may include Last seen: ... and Next: .... With normal account auth, --source defaults to cli. If authentication uses a project-scoped ingest key with the public lbw_ingest_ prefix, the CLI omits source so LogBrew can derive the source from the key kind.

Read, create, and configure projects

Read the authenticated active project catalog before selecting a project:

logbrew projects --json

The JSON result is the exact validated bare project array. Human output is bounded to project identity, setup status, and latest activity. If the intended project already exists, create a new SDK key for that project instead of creating a duplicate:

install -d -m 700 "$HOME/.logbrew"

logbrew projects keys create <project_id> \
  --ingest-key-file "$HOME/.logbrew/checkout-api.ingest" \
  --label "Checkout SDK" \
  --kind sdk \
  --json

CLI v0.1.32 or newer calls POST /api/projects/{project_id}/ingest-keys with account authentication. The destination file must not exist. The CLI stores the one-time key in that owner-only file before it reports success, and it never prints the key or file path. --kind accepts sdk, browser, server, or cli; it defaults to sdk. To create a new project and its first key, use the same file safety rules:

install -d -m 700 "$HOME/.logbrew"

logbrew projects create checkout-api \
  --runtime rust \
  --environment production \
  --ingest-key-file "$HOME/.logbrew/checkout-api.ingest" \
  --json

If either key or project creation has an ambiguous result, repeat that exact command so the CLI can reuse its pending request identity. The two operations keep separate retry state. Use --abandon-retry only when you intend to discard the pending request and start a changed request. logbrew setup --create-project --json returns project command help without creating a project. After creation, use the project ID from the safe JSON response to read backend-owned readiness with stored account authentication:

logbrew doctor --project <project_id> --json

Check account usage

Read account usage and limits without changing account or billing state:

logbrew usage --json
logbrew account usage --json

The response includes the plan, configured limits, totals, quota state, reset dates, per-project totals, per-stream totals, and a next action. The CLI reads this state from LogBrew. It does not calculate or persist usage or quota state from local files.

Do not use an account bearer token as SDK or ingest configuration. Use only project-scoped SDK or ingest configuration returned by LogBrew.

Common investigations

Release got worse

logbrew read issues --release api@1.2.3 --status unresolved --json

One request failed

logbrew read trace <trace_id> --json

Logs around a release

logbrew read logs --release api@1.2.3 --since 24h --json

Product action failed

logbrew read actions --name checkout_failed --since 24h --json

Live watch

Use watch mode when an agent needs fresh events while it is debugging a change.

logbrew watch --json
logbrew watch logs --json
logbrew watch issues --json
logbrew watch actions --json
logbrew watch --severity error,critical --json

logbrew watch --json opens a live stream for all live events. Targeted watch forms support logs, issues, and actions. Trace and span terms are not live watch resources; read trace details with a trace ID instead. Severity filtering for watch is client-side today, so keep the filter explicit in the command you run. The stream reconnects after transient disconnects with backoff.

Explain before changing code

Agents should fetch context before proposing a fix.

Read the issue

logbrew read issue <issue_id> --json

Read the trace

logbrew read trace <trace_id> --json

Ask LogBrew for an explanation

logbrew explain issue <issue_id> --json

Resolve only after verification

logbrew set issue <issue_id> resolved --json

JSON contract

Put --json before or after the command, such as logbrew --json status or logbrew status --json.
JSON errors include ok, error, message, and next.
CLI output must not print stored auth material.
logbrew version --json includes binary, os, and arch; human logbrew version stays short.
Do not use CLI output without --json as an automation contract. Human output can change for readability.

Start

Concepts

Workflows

Install choices

Update an existing install

First checks

Built-in examples

Plan Swift SDK setup

Plan C++ SDK setup

Plan Python SDK setup

Track project setup

Read, create, and configure projects

Check account usage

Common investigations

Release got worse

One request failed

Logs around a release

Product action failed

Live watch

Explain before changing code

JSON contract

​Install choices

​Update an existing install

​First checks

​Login from the CLI

​Built-in examples

​Plan Swift SDK setup

​Plan C++ SDK setup

​Plan Python SDK setup

​Track project setup

​Read, create, and configure projects

​Check account usage

​Common investigations

Release got worse

One request failed

Logs around a release

Product action failed

​Live watch

​Explain before changing code

​JSON contract

Install choices

Update an existing install

First checks

Login from the CLI

Built-in examples

Plan Swift SDK setup

Plan C++ SDK setup

Plan Python SDK setup

Track project setup

Read, create, and configure projects

Check account usage

Common investigations

Live watch

Explain before changing code

JSON contract