> ## 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 with AI agents

> A CLI-first workflow for AI coding agents that need stable LogBrew telemetry context before changing code.

AI coding agents should use LogBrew as a read-first observability source. Start
with stable JSON, gather release and trace context, then decide whether a code
change is justified.

<Note>
  Use `--json` for every automated read. Human-readable output is for terminal
  browsing and can change for readability.
</Note>

## Read the public docs first

When an agent joins a LogBrew project, start from the public docs map before
calling product APIs or changing code.

```bash theme={null}
curl -sS https://logbrew.co/llms.txt
```

Use `llms.txt` as the website-owned agent entry point, then follow the linked
docs page or Markdown mirror when you need exact command examples. Treat all
example values as placeholders.

## Ask the CLI for examples

When an agent needs current command examples, start with the built-in examples
guide before composing a longer workflow.

```bash theme={null}
logbrew examples
logbrew help examples
```

The examples guide covers first-run checks, troubleshooting, live watch, and
machine-readable workflows.

## Set up SDK telemetry from the CLI

CLI v0.1.32 or newer can create a backend-owned project or issue a key for an
existing project without dashboard interaction. Keep the flow short and safe.

<Steps>
  <Step title="Check approved account access">
    ```bash theme={null}
    logbrew status --json
    logbrew whoami --json
    ```

    If authentication is missing, ask a human to run `logbrew login`. Do not
    start a new login when approved authentication already works.
  </Step>

  <Step title="Select or create the project securely">
    ```bash theme={null}
    install -d -m 700 "$HOME/.logbrew"
    logbrew projects --json
    ```

    If the intended project already exists, do not create a duplicate:

    ```bash theme={null}
    logbrew projects keys create <project_id> \
      --ingest-key-file "$HOME/.logbrew/checkout-api.ingest" \
      --label "Checkout SDK" \
      --kind sdk \
      --json
    ```

    Otherwise create the project and its first key:

    ```bash theme={null}
    logbrew projects create checkout-api \
      --runtime node \
      --environment development \
      --ingest-key-file "$HOME/.logbrew/checkout-api.ingest" \
      --json
    ```

    Both commands change account state. The CLI creates the destination file
    with owner-only permissions before it reports success and never prints the
    key or its path. Repeat an ambiguous attempt only with the exact same
    command.
  </Step>

  <Step title="Inspect the setup plan and install">
    ```bash theme={null}
    logbrew setup --json
    npm install @logbrew/sdk @logbrew/node
    export LOGBREW_SERVER_API_KEY="$(< "$HOME/.logbrew/checkout-api.ingest")"
    ```

    Use only the project-scoped key as SDK configuration. Do not substitute
    account or session authentication.
  </Step>

  <Step title="Send one info event">
    Follow the exact released Node.js snippet in the
    [quickstart](/quickstart#first-project-success-path). Keep `release` and
    `environment` explicit, omit private data, then unset the SDK key variable.
  </Step>

  <Step title="Verify readiness and readback">
    ```bash theme={null}
    logbrew doctor --project <project_id> --json
    logbrew read logs --project <project_id> \
      --release quickstart@1 \
      --environment development \
      --since 1h \
      --json
    ```
  </Step>
</Steps>

## Investigation loop

<Steps>
  <Step title="Check access and project state">
    ```bash theme={null}
    logbrew status --json
    logbrew projects --json
    logbrew projects setup <project_id> --source cli --environment production --json
    logbrew usage --json
    logbrew read releases --environment production --json
    ```

    `projects setup` records setup-observed state for an existing project.
    CLI v0.1.32 or newer reads and creates backend-owned projects and can issue
    a key for an existing project without duplicate project creation;
    `logbrew setup --create-project` is help only. `usage` is a read and does
    not calculate quota state locally. If authentication is missing, run
    `logbrew login` before continuing.
  </Step>

  <Step title="Find current unresolved issues">
    ```bash theme={null}
    logbrew read issues --status unresolved --environment production --json
    logbrew read issues --release api@1.2.3 --status unresolved --json
    ```

    Start broad, then add release and environment filters.
  </Step>

  <Step title="Collect evidence before editing code">
    ```bash theme={null}
    logbrew read issue <issue_id> --json
    logbrew explain issue <issue_id> --json
    logbrew read trace <trace_id> --json
    logbrew read logs --trace <trace_id> --json
    ```

    Treat issue details, trace spans, and related logs as the evidence set for
    the fix.
  </Step>

  <Step title="Check product actions when behavior changed">
    ```bash theme={null}
    logbrew read actions --name checkout_failed --since 24h --json
    logbrew read actions --release api@1.2.3 --environment production --json
    ```

    Actions help connect runtime signals to user-visible workflows.
  </Step>

  <Step title="Update issue status only after verification">
    ```bash theme={null}
    logbrew set issue <issue_id> resolved --json
    logbrew set issue <issue_id> ignored --json
    logbrew set issue <issue_id> unresolved --json
    ```

    Only mark an issue resolved after the change is shipped or otherwise
    verified by the team workflow.
  </Step>
</Steps>

## Watch live events

Use live watch for active debugging sessions where new logs or issues may appear
while the agent is testing a fix.

```bash theme={null}
logbrew watch --json
logbrew watch logs --json
logbrew watch issues --json
logbrew watch actions --json
logbrew watch --severity error,critical --json
```

Use `logbrew watch --json` for all live events. Use `logs`, `issues`, or
`actions` when the agent should follow one live stream type. Trace and span
terms are detail-read workflows that require a trace ID, not watch resources.

Severity filtering for watch is client-side today. Keep
`--severity error,critical` in the command when the agent should focus on
actionable live events. The stream reconnects after transient disconnects with
backoff.

## Reliable filters

| Question                         | Start with                                                       |
| -------------------------------- | ---------------------------------------------------------------- |
| What changed in this release?    | `logbrew read releases --environment production --json`          |
| Which issues are still active?   | `logbrew read issues --status unresolved --json`                 |
| What happened in one request?    | `logbrew read trace <trace_id> --json`                           |
| Which logs belong to this trace? | `logbrew read logs --trace <trace_id> --json`                    |
| Which product action failed?     | `logbrew read actions --name checkout_failed --since 24h --json` |

## Agent rules

* Prefer `--json` and parse structured output.
* Accept `--json` before or after a command, such as `logbrew --json status`
  and `logbrew status --json`.
* Use `logbrew status --json` to detect missing auth. If auth is missing, ask a
  human to run `logbrew login` before continuing.
* Expect JSON errors to include `ok`, `error`, `message`, and `next`.
* Read before proposing code changes.
* Keep release and environment filters explicit.
* Use trace IDs to connect logs, spans, issues, and actions.
* Do not expose stored auth material in logs, prompts, tickets, or summaries.
* Do not use an account bearer token as SDK or ingest configuration.
* Do not create local-only project, install, setup, or quota state.
* Do not treat human-readable CLI output as an automation contract.