CLI reference - LogBrew

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

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. logbrew login uses GitHub by default. Select GitLab or Bitbucket when the account uses another provider.

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:

{
  "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`.

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:

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.

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:

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:

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:

logbrew doctor --project <project_id> --json

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

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.

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

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.

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

Watch recovery example

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

{
  "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.

​Common filters

​First-run examples

​Login behavior

​SDK setup planning

​Project setup tracking

​Project catalog, creation, and usage

​JSON behavior

​Live watch behavior

​Watch recovery example

​Popular terms

Common filters

First-run examples

Login behavior

SDK setup planning

Project setup tracking

Project catalog, creation, and usage

JSON behavior

Live watch behavior

Watch recovery example

Popular terms