\n\n# LogBrew CLI\n\nPublic command-line interface for LogBrew.\n\nThe CLI is built for humans and coding agents: stable JSON output, readable\nhuman output, clear `Next:` recovery steps, and token-safe diagnostics.\n\n## Install or update\n\nFor a new package-manager installation:\n\n```bash\ncargo install logbrew-cli\nnpm install -g logbrew-cli@latest\nbrew install LogBrewCo/tap/logbrew\n```\n\nExisting installations do not update themselves. Refresh through the same\npackage manager before relying on a newly documented setup capability:\n\n```bash\ncargo install --locked logbrew-cli\nnpm install -g logbrew-cli@latest\nbrew update && brew upgrade LogBrewCo/tap/logbrew\n```\n\nThe native GitHub Release installers can be run again to replace their prior\nbinary:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.sh | sh\npowershell -ExecutionPolicy Bypass -c \"irm https://github.com/LogBrewCo/cli/releases/latest/download/logbrew-cli-installer.ps1 | iex\"\n```\n\nWindows users can also install the latest MSI from the GitHub Release assets.\nAfter any update, compare `logbrew version --json` with the\n[latest public release](https://github.com/LogBrewCo/cli/releases/latest).\nCMake setup planning requires CLI 0.1.39 or newer; correct Objective-C\nclassification for XcodeGen projects requires CLI 0.1.40 or newer.\n\nCargo installs and source builds require Rust 1.87 or newer. The npm,\nHomebrew, shell, PowerShell, and MSI installers use native release artifacts and\ndo not require a local Rust toolchain.\n\nFor development from this public repository:\n\n```bash\ncargo install --git https://github.com/LogBrewCo/cli logbrew-cli\n```\n\n## Distribution\n\nLogBrew CLI is a Rust native binary. Cargo builds a platform-native `logbrew`\nexecutable for the selected target; npm, Homebrew, shell, PowerShell, and MSI\ninstallers are wrappers around those native release artifacts.\n\nRelease publishing is handled by GitHub Actions:\n\n- GitHub Releases: native archives for Linux x64/ARM64, macOS x64/ARM64, and\n Windows x64 on GitHub-hosted runners.\n- Installers: shell, PowerShell, npm package, Homebrew formula, and Windows MSI.\n- Package managers: crates.io and npm via trusted publishing/OIDC, and Homebrew\n via the `LogBrewCo/homebrew-tap` formula repository.\n\nThe CLI package surface is intentionally separate from the language and\nframework SDK packages in `LogBrewCo/sdk`. SDK packages such as JavaScript\nframework integrations, Python framework middleware, Swift, .NET, Go, Java,\nKotlin, Ruby, Rust SDK crates, and Unity packages remain SDK-owned. This repo\nonly publishes the `logbrew` CLI binary and its install wrappers.\n\nTrusted publishing requires the npm package and crates.io crate to already\nexist, so brand-new package names need one manual first publish before CI release\ntags can publish future versions without long-lived registry tokens. Homebrew\npublishing requires the GitHub Actions secret `HOMEBREW_TAP_TOKEN`.\n\nBefore pushing a release tag, run the release preflight:\n\n```bash\nbash scripts/release-preflight.sh vX.Y.Z\n```\n\nThe preflight checks the tag/version match, clean synced `main`, public\ncrates.io/npm package bootstrap and version collisions, the public Homebrew tap\nrepository, green CI, required GitHub Actions secret names, and existing\nrelease/tag collisions.\n\n## Basic Usage\n\n```bash\nlogbrew examples\nlogbrew status\nlogbrew login\nlogbrew login --provider gitlab\nlogbrew whoami\nlogbrew logout\nlogbrew projects repositories --json\nlogbrew projects repositories discover --provider github --repository --json\nlogbrew logs --release checkout@1 --environment production\nlogbrew issues open --json\nlogbrew explain issue issue_123\nlogbrew deploy ci-run-42 --project --release checkout@1 --environment production --service checkout-api --status succeeded --started-at 2026-08-10T12:00:00Z --finished-at 2026-08-10T12:02:00Z --json\nlogbrew explain release checkout@1 --project --environment production --service checkout-api\nlogbrew watch --json\nlogbrew watch --severity error,critical --json\n```\n\nRun `logbrew examples` for a compact first-run, troubleshooting, live watch, and\nagent JSON workflow guide.\n\nThe default API URL is `https://api.logbrew.co`. Override it with\n`LOGBREW_API_URL` when testing against another LogBrew API.\n\nAuthentication uses either `LOGBREW_TOKEN` or the secured local access/refresh\npair created by `logbrew login`. Interactive login supports GitHub (the\ndefault), GitLab, and Bitbucket through\n`logbrew login --provider github|gitlab|bitbucket`, receives the result on a\nloopback-only callback, and stores the pair under `~/.logbrew`. `logbrew\nwhoami` and `logbrew me` return the authenticated account identity.\nAuthenticated commands rotate local credentials once after an expired-token\nresponse; environment tokens are never persisted or refreshed. `--json` and\n`--no-open` remain non-mutating handoff modes. CLI output never prints token\nmaterial. `logbrew logout` attempts to revoke the stored refresh-backed server\nsession and always removes local credentials; `LOGBREW_TOKEN` must be unset\nseparately.\n\n### Plan SDK installation without changing files\n\nRun `logbrew setup --json` from a project directory to detect nearby manifests\nand receive a stable, non-mutating installation plan. SwiftPM and XcodeGen\nprojects receive the released Swift package declaration. Python projects\nreceive a package-index plan for the core SDK or the detected Django, Flask, or\nFastAPI integration, including the pip, uv, poetry, or pipenv command. Bundler\nprojects receive the released Ruby package plan, and Rails applications are\nidentified from `config/application.rb` without reading application source.\nSvelteKit projects receive the public core, browser, and Svelte integration\npackages with the detected npm, pnpm, yarn, or bun command. Detection requires\nan exact `@sveltejs/kit` dependency in a standard `package.json` dependency map.\nReact and Express dependencies receive the released browser/React or\nNode/Express packages. Mixed projects receive one deduplicated install command\nplus separate browser and server key scopes and explicit service, environment,\nand release requirements on both surfaces.\n\nPython plans report the public package compatibility requirements separately.\nReview them before running the command, especially when a library supports\nolder Python or framework versions. The CLI reads only bounded local metadata,\ndoes not install a package, does not change a manifest, and does not require\nauthentication for this plan.\n\n### Create a project without dashboard sign-in\n\nAfter `logbrew login`, the same authenticated CLI session can create an\naccount-owned project and its first project-scoped ingest key. No additional\ndashboard or browser sign-in is required.\n\nFor a connected source-control provider, list repository candidates and run\nbounded component discovery only for the repository you select:\n\n```bash\nlogbrew projects repositories --json\nlogbrew projects repositories discover \\\n --provider github --repository --json\n```\n\nDiscovery reports its separate read-only contents authorization state and\nnever grants permission silently. A complete response supplies one expiring\ndiscovery ID and component IDs. Repeat `--component` to create the selected\nservices under one project:\n\n```bash\nlogbrew projects create \"Checkout Platform\" \\\n --provider github --repository \\\n --discovery --component \\\n --ingest-key-file \"$HOME/.logbrew/checkout-platform.key\" --json\n```\n\nChoose a new file inside an existing owner-only directory. On macOS and Linux,\nthe owner-only directory created by CLI login is a suitable destination:\n\n```bash\nlogbrew projects create \"FastAPI Template\" \\\n --runtime python \\\n --environment development \\\n --ingest-key-file \"$HOME/.logbrew/fastapi-template.key\" \\\n --json\n```\n\nThe command writes the one-time ingest key to that file before reporting\nsuccess. It never prints the key or its path. Its JSON response contains the\nnew project ID; use that ID with `logbrew doctor --project ` to\ninspect setup readiness. Run `logbrew projects --help` for the complete\nsecurity and retry contract.\n\n### Create an ingest key for an existing project\n\nUse the authenticated CLI when a new app or service needs its own key but the\nLogBrew project already exists:\n\n```bash\nlogbrew projects keys create \\\n --kind sdk \\\n --label \"Mobile SDK key\" \\\n --ingest-key-file \"$HOME/.logbrew/mobile-sdk.key\" \\\n --json\n```\n\nThe default kind is `sdk`; supported kinds are `sdk`, `browser`, `server`,\n`cli`, and `artifact`. An artifact key is project-scoped and write-only. It can\nupload release source maps and native debug files but cannot read artifact\nmetadata or submit telemetry. The command sends one idempotent\naccount-authenticated request and\nstores the one-time key in a new owner-only file before reporting success. It\nnever prints the key or its path and does not create a duplicate project. An\nambiguous retry reuses the same request and idempotency key. Use\n`--abandon-retry` only to intentionally discard that pending attempt.\n\n### Archive an inactive project safely\n\nArchive an account-owned project only after reviewing its UUID:\n\n```bash\nlogbrew projects archive --yes --json\n```\n\nThe command requires explicit `--yes`, sends one account-authenticated archive\nrequest, and reports success only after an empty `204` response. The project\nthen leaves the active catalog and its project-scoped ingest keys no longer\nauthorize new ingestion. This is a soft archive; the CLI makes no hard-delete\nor restoration promise.\n\nFor AI sessions, the default mode should be checking only when requested because\nit uses fewer AI tokens. `logbrew watch --json` opens a live WebSocket stream for\nthe current session, and `logbrew watch --severity error,critical --json`\nfilters live logs/issues client-side to actionable severities. The watch stream\nreconnects after transient disconnects with a fresh feed ticket and backoff.\n\n## Development\n\n```bash\nbash scripts/pre-commit.sh\n```\n\nPublic-repo rule: keep this repository CLI-only. Do not add backend code,\nhostnames, IP addresses, secrets, deployment files, database configuration, or\noperational details here.\n","readmeFilename":"README.md"}
![\"LogBrew\"](\"https://raw.githubusercontent.com/LogBrewCo/sdk/895b55798587a9eca5cabf8ebc2bbe8b4d55bd12/assets/brand/logbrew-logo-transparent-512.png\"){kind=logo}
\n