> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the CLI

> Read LogBrew telemetry from the terminal with agent-friendly commands and stable JSON output.

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.

```bash theme={null}
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.sh | sh
```

```powershell theme={null}
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.

```bash theme={null}
brew install LogBrewCo/tap/logbrew
npm install -g logbrew-cli
cargo install logbrew-cli
```

<Note>
  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.
</Note>

## 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:

```bash theme={null}
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](https://github.com/LogBrewCo/cli/releases/latest):

```bash theme={null}
logbrew version --json
```

## First checks

```bash theme={null}
logbrew status --json
logbrew read releases --environment production --json
```

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

```text theme={null}
not logged in: run logbrew login
```

## Login from the CLI

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

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](/reference/cli#sdk-setup-planning) 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.

```bash theme={null}
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](/guides/sdk-ingestion) 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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
logbrew doctor --project <project_id> --json
```

## Check account usage

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

```bash theme={null}
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.

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

## Common investigations

<CardGroup cols={2}>
  <Card title="Release got worse" icon="tag">
    ```bash theme={null}
    logbrew read issues --release api@1.2.3 --status unresolved --json
    ```
  </Card>

  <Card title="One request failed" icon="route">
    ```bash theme={null}
    logbrew read trace <trace_id> --json
    ```
  </Card>

  <Card title="Logs around a release" icon="file-text">
    ```bash theme={null}
    logbrew read logs --release api@1.2.3 --since 24h --json
    ```
  </Card>

  <Card title="Product action failed" icon="mouse-pointer-click">
    ```bash theme={null}
    logbrew read actions --name checkout_failed --since 24h --json
    ```
  </Card>
</CardGroup>

## Live watch

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

```bash theme={null}
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.

<Steps>
  <Step title="Read the issue">
    ```bash theme={null}
    logbrew read issue <issue_id> --json
    ```
  </Step>

  <Step title="Read the trace">
    ```bash theme={null}
    logbrew read trace <trace_id> --json
    ```
  </Step>

  <Step title="Ask LogBrew for an explanation">
    ```bash theme={null}
    logbrew explain issue <issue_id> --json
    ```
  </Step>

  <Step title="Resolve only after verification">
    ```bash theme={null}
    logbrew set issue <issue_id> resolved --json
    ```
  </Step>
</Steps>

## 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.