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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.