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

# CLI reference

> Command grammar for the native LogBrew CLI.

Use `--json` for machine-readable output.

| Command                                                                                 | Purpose                                                                                       |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `logbrew login [--provider github\|gitlab\|bitbucket] [--no-open] [--json]`             | Start account login. GitHub is the default provider.                                          |
| `logbrew whoami [--json]`                                                               | Read the authenticated account identity.                                                      |
| `logbrew me [--json]`                                                                   | Alias for `logbrew whoami`.                                                                   |
| `logbrew logout [--json]`                                                               | Revoke the stored server session when possible and remove local credentials.                  |
| `logbrew setup [--auto] [--yes] [--json]`                                               | Detect manifests and print a non-mutating SDK setup plan.                                     |
| `logbrew setup --create-project [--json]`                                               | Show project creation help without creating a project.                                        |
| `logbrew status [--json]`                                                               | Check local auth and API reachability.                                                        |
| `logbrew doctor --project <project_id> [--json]`                                        | Read canonical setup readiness for one account-owned project.                                 |
| `logbrew version [--json]`                                                              | Print the installed native CLI version and platform metadata.                                 |
| `logbrew examples`                                                                      | Show compact first-run, troubleshooting, live watch, and agent JSON examples.                 |
| `logbrew projects [--json]`                                                             | Read the authenticated active project catalog.                                                |
| `logbrew project [--json]`                                                              | Alias for `logbrew projects`.                                                                 |
| `logbrew projects create <name> --ingest-key-file <path> [options] [--json]`            | Create a project and store its one-time ingest key in a new private file.                     |
| `logbrew projects keys create <project_id> --ingest-key-file <path> [options] [--json]` | Store a new one-time ingest key for an existing project without creating a duplicate project. |
| `logbrew projects setup <project_id> [options] [--json]`                                | Record setup observed for an existing project.                                                |
| `logbrew project setup <project_id> [options] [--json]`                                 | Alias for setup-observed tracking.                                                            |
| `logbrew usage [--json]`                                                                | Read account usage, limits, quota state, and reset dates.                                     |
| `logbrew account usage [--json]`                                                        | Alias for `logbrew usage`.                                                                    |
| `logbrew read logs [filters] [--json]`                                                  | Read structured logs.                                                                         |
| `logbrew read issues [filters] [--json]`                                                | Read grouped issues.                                                                          |
| `logbrew read actions [filters] [--json]`                                               | Read product actions.                                                                         |
| `logbrew read releases [filters] [--json]`                                              | Read release summaries.                                                                       |
| `logbrew read trace <trace_id> [--json]`                                                | Read spans for one trace.                                                                     |
| `logbrew read issue <issue_id> [--json]`                                                | Read one grouped issue.                                                                       |
| `logbrew debug-artifacts upload <path> [options] [--json]`                              | Validate, upload, and verify Apple debug objects.                                             |
| `logbrew debug-artifacts lookup [options] [--json]`                                     | Verify one uploaded Apple image identity.                                                     |
| `logbrew explain issue <issue_id> [--json]`                                             | Fetch issue context for explanation.                                                          |
| `logbrew set issue <issue_id> <status> [--json]`                                        | Set status to `unresolved`, `resolved`, or `ignored`.                                         |
| `logbrew watch [filters] [--json]`                                                      | Open a live event stream for active debugging.                                                |
| `logbrew watch logs [--json]`                                                           | Watch live log events.                                                                        |
| `logbrew watch issues [--json]`                                                         | Watch live issue events.                                                                      |
| `logbrew watch actions [--json]`                                                        | Watch live action events.                                                                     |

## Common filters

| Filter                        | Supported by                           |
| ----------------------------- | -------------------------------------- |
| `--release <release>`         | logs, issues, actions, releases, trace |
| `--environment <environment>` | logs, issues, actions, releases, trace |
| `--project <project_id>`      | logs, issues, actions, releases, trace |
| `--limit 100`                 | list reads                             |
| `--since 24h`                 | logs and actions                       |
| `--trace <trace_id>`          | logs                                   |
| `--severity error`            | logs                                   |
| `--severity error,critical`   | watch                                  |
| `--status unresolved`         | issues                                 |
| `--service <service_name>`    | issues                                 |
| `--since 24h`                 | issues                                 |
| `--name checkout_failed`      | actions                                |
| `--user <distinct_id>`        | actions                                |

## First-run examples

```bash theme={null}
logbrew examples
logbrew help examples
logbrew status
logbrew login
logbrew setup
logbrew projects --json
logbrew projects keys create <project_id> --ingest-key-file <path> --kind sdk --json
logbrew projects setup <project_id> --source cli --environment production --json
logbrew usage --json
logbrew logs error checkout failed --release checkout@1 --environment production
logbrew issues open --release checkout@1 --environment production
logbrew explain issue issue_123
logbrew watch --json
logbrew watch logs --json
logbrew watch issues --json
logbrew watch actions --json
logbrew watch --severity error,critical --json
logbrew --json status
```

`example`, `examples`, `sample`, `samples`, `recipe`, and `recipes` all open
the examples guide.

## Login behavior

`logbrew login` uses GitHub by default. Select GitLab or Bitbucket when the
account uses another provider.

```bash theme={null}
logbrew login --provider github
logbrew status --json
logbrew whoami --json
```

`--no-open` prints the login URL without opening a browser. `--json` returns
the same handoff as machine-readable JSON and also keeps the browser closed.
`logbrew auth login` is an alias for `logbrew login`.

Use `logbrew status --json` to check API reachability and authentication. Use
`logbrew whoami --json` or `logbrew me --json` to read the exact validated
account object from `GET /api/auth/account`:

```json theme={null}
{
  "id": "123e4567-e89b-42d3-a456-426614174000",
  "email": "developer@example.com",
  "display_name": "Example Developer",
  "tier": "free"
}
```

Account identity requires account authentication. A project-scoped
`lbw_ingest_` key cannot read it. CLI output must not print stored auth
material.

## SDK setup planning

`logbrew setup` detects supported manifests and prints a plan without changing
project files. `--auto` and `--yes` record planning preferences; they do not
authorize file changes.

For a detected SwiftPM or XcodeGen project, JSON output sets `install_ready` to
`true`. The `install_plan` uses the public SDK repository and these stable
values:

| Field                                 | Value                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------- |
| `ecosystem`                           | `swiftpm`                                                              |
| `mode`                                | `non_mutating`                                                         |
| `package_url`                         | `https://github.com/LogBrewCo/sdk.git`                                 |
| `product`                             | `LogBrew`                                                              |
| `version`                             | `0.1.6`                                                                |
| `version_requirement.kind`            | `up_to_next_major`                                                     |
| `version_requirement.minimum_version` | `0.1.6`                                                                |
| `dependency_declaration`              | `.package(url: "https://github.com/LogBrewCo/sdk.git", from: "0.1.6")` |
| `next_action.code`                    | `add_swift_package_dependency`                                         |
| `next_action.target`                  | `project_manifest`                                                     |

The `version` field remains available for clients that read the original setup
plan. New clients should use `version_requirement` to understand the compatible
release range. `logbrew init`, `logbrew install`, `logbrew configure`, and
`logbrew sdk` use the same non-mutating plan.

For a detected CMake project, CLI v0.1.39 or newer also sets
`install_ready` to `true`. The detected entry uses `runtime: "cpp"`,
`package_manager: "cmake"`, and `manifest: "CMakeLists.txt"`. The stable
plan fields are:

| Field                            | Value                                  |
| -------------------------------- | -------------------------------------- |
| `ecosystem`                      | `cmake`                                |
| `mode`                           | `non_mutating`                         |
| `package_url`                    | `https://github.com/LogBrewCo/sdk.git` |
| `release_tag`                    | `cpp/logbrew-cpp/v0.2.3`               |
| `source_subdirectory`            | `cpp/logbrew-cpp`                      |
| `version`                        | `0.2.3`                                |
| `targets.core`                   | `LogBrew::LogBrew`                     |
| `targets.http_transport`         | `LogBrew::HttpTransport`               |
| `http_transport.cmake_option`    | `LOGBREW_BUILD_HTTP_TRANSPORT`         |
| `http_transport.default_enabled` | `false`                                |
| `http_transport.requires`        | `libcurl`                              |
| `next_action.code`               | `add_cmake_fetch_content`              |
| `next_action.target`             | `CMakeLists.txt`                       |

`dependency_declaration` contains the pinned CMake `FetchContent` block.
The CLI does not edit the manifest, invoke CMake, enable the optional
transport, or install libcurl.

For a detected Python project, JSON output also sets `install_ready` to `true`.
The plan selects the detected package manager and uses these stable fields:

| Field                                 | Value                                     |
| ------------------------------------- | ----------------------------------------- |
| `ecosystem`                           | `pypi`                                    |
| `mode`                                | `non_mutating`                            |
| `package_manager`                     | `pip`, `uv`, `poetry`, or `pipenv`        |
| `integration`                         | `python`, `django`, `flask`, or `fastapi` |
| `packages[].version_requirement.kind` | `latest_compatible`                       |
| `compatibility.status`                | `review_required`                         |
| `compatibility.requires_python`       | `>=3.10`                                  |
| `next_action.code`                    | `review_compatibility_and_install`        |
| `next_action.target`                  | `project_environment`                     |

`compatibility.requires_framework` is `null` for the core Python plan. It is
`Django>=4.2.30,<6`, `Flask>=3.1`, or `FastAPI>=0.111.1` when that released
framework integration is detected. The `install_command` uses the selected
package manager and includes `logbrew-sdk` plus the matching framework
package. The CLI does not execute that command.

## Project setup tracking

`logbrew projects setup <project_id>` records that setup was observed for an
existing project. It calls `POST /api/projects/{project_id}/setup/seen` and
returns the LogBrew project setup state as JSON.

| Option                        | Use it for                                                    |
| ----------------------------- | ------------------------------------------------------------- |
| `--runtime <runtime>`         | Optional runtime label when your setup flow knows one.        |
| `--source api\|cli\|sdk`      | Setup source. With normal account auth, the default is `cli`. |
| `--environment <environment>` | Environment associated with setup progress.                   |
| `--env <environment>`         | Alias for `--environment`.                                    |

```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
```

Human output starts with:

```text theme={null}
Project setup seen: <status>
```

It may also include `Last seen: ...` and `Next: ...`.

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.

## Project catalog, creation, and usage

The CLI reads the active project catalog from `GET /api/projects`.
`logbrew projects --json` preserves the exact validated bare array. Human
output is bounded to project identity, setup status, and latest activity.

```bash theme={null}
logbrew projects --json
logbrew project --json
```

CLI v0.1.32 or newer can issue a key for an existing project without dashboard
interaction or duplicate project creation:

```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
```

This command uses account authentication and calls
`POST /api/projects/{project_id}/ingest-keys`. `--kind` accepts `sdk`,
`browser`, `server`, or `cli` and defaults to `sdk`. The default label is
`CLI-created SDK key`.

The destination file must not exist. The CLI creates an owner-only file,
stores the one-time key before reporting success, and never prints the key or
its file path.

Project creation uses the same key-file guarantees:

```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 the result of either request is ambiguous, repeat the exact command. The
CLI reuses that operation's pending request identity and keeps project
creation retry state separate from existing-project key creation. Use
`--abandon-retry` only when you intend to discard that pending request and
start a changed request. `logbrew setup --create-project --json` returns the
project command help; it does not create a project.

CLI v0.1.30 or newer can create the project without dashboard interaction.
After creation, read canonical setup state with the project ID from the safe
JSON response:

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

Read account usage from `GET /api/account/usage`:

```bash theme={null}
logbrew usage --json
logbrew account usage --json
```

JSON preserves the exact validated account-usage object, including plan,
limits, totals, quota state, reset dates, per-project totals, per-stream
totals, and the next action. The CLI 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>

## JSON behavior

* `--json` can appear before or after commands.
* JSON errors include `ok`, `error`, `message`, and `next`.
* `logbrew version --json` includes `binary`, `os`, and `arch`.
* Human `logbrew version` output stays short.
* CLI output must not print stored auth material.

## Live watch behavior

`logbrew watch --json` opens a live stream.
`logbrew watch --severity error,critical --json` keeps the live view focused on
actionable severities. The watch stream reconnects after transient disconnects
with backoff.

Supported target forms are `logbrew watch logs --json`,
`logbrew watch issues --json`, and `logbrew watch actions --json`. Trace and
span terms are not watch resources because trace detail reads require a trace
ID.

<Note>
  Watch severity filtering is client-side today. Keep server-side read filters
  explicit when querying stored telemetry.
</Note>

## Watch recovery example

If an agent tries to watch traces directly, JSON output returns a parse error
with a trace-specific next step.

```json theme={null}
{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "watch streams logs, issues, and actions; use logbrew trace <trace_id> to read a trace"
}
```

## Popular terms

The CLI intentionally uses terms agents already know: logs, issues, traces,
spans, actions, releases, environments, projects, services, and status.