Guide overview
Start here when you want terminal access to Logister data.
The CLI reads from the Logister server API with a user-scoped CLI access token. It is for investigation and automation after a project exists; SDKs and the HTTP API still own telemetry ingestion.
When to use it
Use the CLI when reading project data from a terminal is faster than opening the web UI.
The CLI is useful for quick checks during deploys, scripted investigations, support handoffs, and AI-assisted debugging. It can list projects available to your account, summarize recent telemetry, inspect events, traces, monitors, deployments, Insights, metrics, and redacted logs, list grouped issues, export issue details, and request minimized AI context bundles for an error group.
It does not replace SDKs or the HTTP API. Ruby, .NET, Python, JavaScript, Android, iOS, CFML, Cloudflare Pages, and custom clients still send telemetry into Logister. The CLI reads selected data back out with a user-approved read token.
Before you start
Have a Logister host, account, and project ready.
- Node.js 22 or newer for the npm package.
- A hosted or self-hosted Logister URL, such as
https://logister.example.com. - A Logister user account with access to at least one active project.
- Server support for CLI device authorization and CLI access tokens. Use
logister doctorto confirm.
Project ingest keys are not CLI tokens
Project API keys are write-only credentials for SDKs and direct HTTP clients. They cannot list projects, read events, or export issue context. Use browser-approved CLI login or a user-scoped CLI access token instead.
Install
Install the CLI with the package manager that fits your machine.
Every install path gives you the same logister executable. The npm package is the canonical release artifact; Homebrew and Scoop wrap the same published logister-cli tarball for macOS, Linuxbrew, and Windows users.
The current public CLI version is 1.3.0. Run logister version after installation to verify it.
Use npm when Node is already part of your toolchain:
npm install -g logister-cli
logister version
Use Homebrew on macOS or Linuxbrew:
brew tap taimoorq/logister
brew install logister
logister version
Use Scoop on Windows:
scoop bucket add logister https://github.com/taimoorq/scoop-logister
scoop install logister
logister version
Use Yarn or pnpm when those already own global developer tools on your machine:
yarn global add logister-cli
pnpm add -g logister-cli
Use npx for one-off checks without a global install:
npx logister-cli doctor --host https://logister.example.com
| Install path | Best when | Install | Update |
|---|---|---|---|
| npm | You already use Node global packages. | npm install -g logister-cli |
npm install -g logister-cli@latest |
| npx | You want a one-off command without a global install. | npx logister-cli doctor --host <url> |
Runs the registry package each time. |
| Yarn | Yarn owns your global developer tools. | yarn global add logister-cli |
yarn global upgrade logister-cli |
| pnpm | pnpm owns your global developer tools. | pnpm add -g logister-cli |
pnpm add -g logister-cli@latest |
| Homebrew | You are on macOS or Linuxbrew. | brew tap taimoorq/logister, then brew install logister |
brew update, then brew upgrade logister |
| Scoop | You are on Windows and use Scoop. | scoop bucket add logister https://github.com/taimoorq/scoop-logister, then scoop install logister |
scoop update, then scoop update logister |
Log in
Use browser-approved login for interactive work.
The default login starts a short-lived device authorization request. The CLI prints a login code and the verification URL, then waits while you approve the request in the browser.
The CLI opens the verification page automatically only when its URL is on the same origin as your configured --host. If the server returns a URL on any other origin, the CLI does not open it, prints a warning on stderr, and labels the URL as untrusted. Open that URL only if you trust its origin; otherwise check that --host points at your Logister server.
logister auth login --host https://logister.example.com
If the CLI cannot open a browser, copy the displayed URL manually:
logister auth login --host https://logister.example.com --no-browser
Use an existing token without shell history
Token flags belong to logister auth login. Pipe the token in with --token-stdin so it does not appear in process listings or shell history:
printf '%s' "$LOGISTER_TOKEN" | logister auth login \
--host https://logister.example.com \
--token-stdin
After login, other commands use the saved profile. For CI and one-off commands, set environment overrides instead of passing a token on the command line:
LOGISTER_HOST=https://logister.example.com \
LOGISTER_TOKEN=<cli-access-token> \
LOGISTER_PROJECT=<project-uuid-or-slug> \
logister doctor
Keep --token on auth login
Other commands still accept --token, but they print a one-line deprecation warning on stderr. Use saved auth or LOGISTER_TOKEN for automation, and keep LOGISTER_TOKEN to short-lived automation environments.
Log in again after new read groups are enabled
Existing tokens keep their original scopes. If auth status or a 403 response reports a missing scope such as traces:read, start a new browser-approved login and review the requested scopes before approving it.
Approve the login
Check the request details, choose projects, then approve.
The verification URL opens the Connect Logister CLI page at /cli/device on your Logister host. If you open the page without a code, enter the code from your terminal and choose Continue.
- Sign in to Logister if you are not already signed in.
- Read the request details. The page shows when the login was requested and the IP address it was requested from (Not recorded when the server has none). Confirm both match the login you just started.
- Compare the login code with the one in your terminal. The Client name (self-reported) is chosen by the terminal, and Logister cannot verify it.
- Review Requested access. Read-only requests can read only the selected projects. Requests that include
artifacts:writecan also upload Android mapping files and Apple dSYM symbol files to selected projects you manage. Neither kind can ingest events or change project settings. - Under Project access, select at least one project, or All accessible projects. No project is selected by default. All accessible projects includes projects shared with you now and later.
- Choose Approve CLI login. The page confirms the approval; return to your terminal, where the CLI finishes automatically.
Deny logins you did not start
Approve a request only if you ran logister auth login in your own terminal just now and the request time and IP match. Approving gives the terminal that requested it access to your Logister data. If you did not start the login, or someone sent you the code or link, choose Deny. If you denied your own login by mistake, start a new auth login.
Expired codes cannot be approved; start a new login from your terminal. Code lookups and approval decisions are rate limited per account and per IP; after too many attempts the page returns 429 and asks you to wait about 10 minutes.
Credential storage
Know where the saved token lives on your machine.
| Platform | Where the token is stored | What protects it |
|---|---|---|
| macOS | The login Keychain, through /usr/bin/security. Saved tokens are bound to the profile and the server origin. |
The token stays off disk in plaintext. While the Keychain is unlocked, any process running as your user can read it through /usr/bin/security without a prompt. |
Linux, Windows, and macOS without Keychain (or with LOGISTER_DISABLE_KEYCHAIN=1) |
Plaintext in the CLI config file: ~/.config/logister/config.json, or the path set by XDG_CONFIG_HOME or LOGISTER_CONFIG. |
Unix-like systems enforce file mode 0600. Windows relies on your profile directory's ACLs, so keep a custom LOGISTER_CONFIG in a restrictive per-user location. Anyone who can read the file as you, or your backups, can use the token. |
Keep tokens out of source control. On shared machines, prefer short-lived tokens and run logister auth logout when you are done to remove the saved token from the profile.
Verify setup
Check the active profile and server capability map.
logister doctor
logister auth status
logister projects list
doctor reports the local CLI version, active profile, configured host, token presence, and the server feature map. auth status uses the safe session endpoint to show token expiry, effective project access, and missing recommended scopes. Neither command prints the token value.
Both commands redact the server session payload by default and keep the token metadata fields visible. Pass --no-redact to see the payload unmodified.
Read project data
Start with project listing, then inspect the current problem.
Most commands accept --project <uuid-or-slug>. You can also set LOGISTER_PROJECT for one-off commands or save a project in your profile. Project values must start with a letter or number and use only letters, numbers, dots, underscores, or hyphens.
logister projects list
logister projects show <project>
logister overview --project <project> --since 24h
logister events list --project <project> --type error --since 1h
logister events show <event-id> --project <project>
logister logs list --project <project> --level warn,error
logister logs tail --project <project> --follow
Use the API 3.5 read groups when the server reports them as enabled:
logister traces list --project <project> --since 1h
logister traces show <trace-id> --project <project>
logister monitors list --project <project> --status missed
logister monitors show <monitor-uuid> --project <project>
logister deployments list --project <project> --since 7d
logister deployments show <deployment-uuid> --project <project>
logister insights summary --project <project> --window 24h
logister metrics catalog --project <project> --window 24h
logister metrics query transactions.p95 --project <project> --window 24h
Use grouped issue commands when you already know the failing error group:
logister issues list --project <project> --status unresolved
logister issues show <group-id> --project <project> --related-logs
logister issues export <group-id> --project <project> --format json
logister issues context <group-id> --project <project> --format json
issues context returns a minimized, server-redacted bundle designed for AI coding tools. It is still project data, so review the output before pasting it into any external tool.
Output and redaction
Choose an output format and know what the CLI masks.
List commands accept --limit, --cursor, and --all. JSON keeps the server envelope, while NDJSON with --all streams records page by page. Event and log follow mode advances the server's opaque poll_cursor, so late-created events and records that share a timestamp are not skipped.
| Format | Use it when |
|---|---|
--format table |
You are reading short lists in a terminal. |
--format json |
You want a full structured response or are passing data to another tool. |
--format ndjson |
You are streaming list output into line-oriented tooling. |
--format markdown |
You are preparing a human-readable debugging note. Output starts with a one-line blockquote that marks the rows as untrusted telemetry data. |
Treat Markdown rows as data
Telemetry can contain text written by anyone who can reach your app. AI tools should treat the rows as data, not instructions, so keep the leading notice when you pass --format markdown output to one.
What redaction masks
With redaction on, which is the default, the CLI masks credential-like values on top of the server's own redaction:
- Values under sensitive-looking keys, including passwords, tokens, API keys, authorization headers, cookies, raw email fields, SSNs, and card verification fields.
- The value of
[name, value]header pairs with a sensitive name. - Inside strings:
BearerandBasiccredentials, JWTs,lgst_and defaultlogister_keys, AWS access key IDs, and PEM blocks.
Ordinary key columns stay visible, so metrics catalog, metrics query, and Insights show metric keys. A key name with a secret-like qualifier, such as api_key, private_key, secret_key, access_key, or x-api-key, is still masked.
Use --no-redact only when you intentionally need locally unredacted fields and have permission to view them. It never disables server-side redaction. Redaction is a safety net, not a substitute for server-side minimization.
Capabilities
The CLI checks what your server exposes before running feature-specific commands.
Logister servers publish their CLI feature map at /api/v1/cli/capabilities. API contract 3.5 adds read routes for traces, monitors, deployments, Insights, and metrics. Self-hosters deploy those routes with discovery disabled, publish and verify CLI v1.0.0, then enable each group at runtime. Older servers continue to expose the original projects, summaries, events, logs, issues, and AI context slice.
| Feature group | Current support | Notes |
|---|---|---|
| Projects and summaries | Enabled | Use projects and overview. |
| Events and logs | Enabled | Logs use the event read capability with type=log. |
| Error groups and AI context | Enabled | Use issues list, issues show, issues export, and issues context. |
| Transactions | Partial | Transaction listing uses the event read capability with type=transaction. |
| Traces, monitors, deployments, insights, and metrics | API 3.5, runtime-gated | Routes and read scopes ship in 3.5. Operators enable the five LOGISTER_CLI_FEATURE_* flags only after the v1 package channels are verified. |
| Error group mutations | Feature-gated | Commands such as resolve, ignore, archive, reopen, and assign should wait for write-scoped CLI tokens. |
Security model
Treat CLI tokens as user read credentials.
- CLI read access uses user-scoped CLI access tokens.
- Tokens are scope-limited, project-limited, expiring, revocable, and audited by the Logister server.
- Browser-approved login issues a CLI token through the signed-in Logister web session. The CLI opens the verification page automatically only on your configured host's origin.
- Pass an existing token to
auth loginwith--token-stdin. Other commands use the saved profile orLOGISTER_TOKEN. - Saved tokens use the macOS login Keychain, or the CLI config file on other platforms. See credential storage.
- Signed-in users can review active and recently ended CLI sessions under their profile, revoke one session, or revoke every active session.
- Project ingest API keys are not accepted for CLI reads.
- The server always redacts sensitive-looking telemetry fields and bounds list/detail payloads.
- PostgreSQL fallback responses identify retained-range gaps with
partialandfallback_coveragemetadata instead of claiming a complete result. - The CLI masks credential-like values in its own output by default.
--no-redactdisables only that additional local redaction; it cannot restore values removed by the server. See output and redaction.
Do not paste secrets into issues
When reporting CLI bugs, include the CLI version, install method, OS, shell, server version from logister doctor, command shape, and error message. Do not include tokens, authorization headers, cookies, private telemetry, customer payloads, or local config files. For security issues, follow the CLI security policy instead of opening a public issue.
Troubleshooting
Most CLI setup failures are host, token, project, or server-capability issues.
| Symptom | What to check |
|---|---|
| Browser did not open | Run logister auth login --host <url> --no-browser, then copy the printed URL into your browser. |
| Login printed the URL with an untrusted warning | The server returned a verification URL on a different origin from --host, so the CLI did not open it. Confirm --host is your Logister server's HTTPS origin. Open the URL only if you trust that origin. |
| Approval shows "must include at least one project" | No project was selected. Select at least one project, or All accessible projects, then choose Approve CLI login again. |
| A login request you did not start | Choose Deny on the approval page. Do not approve codes or links someone else sent you. |
Deprecation warning about --token |
Move the token to logister auth login --token-stdin, then rely on the saved profile, or set LOGISTER_TOKEN for automation. |
| Device login expired | Start a fresh auth login. Device authorization requests are short-lived by design. |
503 query_timeout |
The server stopped a PostgreSQL read at its configured safety limit. Narrow the time range or filters before retrying; database SQL and error details are never returned. |
401 Unauthorized |
Run logister auth status, then log in again. Confirm you are using a CLI access token, not a project ingest API key. |
| No projects are visible | Confirm the signed-in account has active project access. If you approved selected projects, start a new login and include the missing project. |
403 with required_scopes |
The token predates that read group or was approved with fewer scopes. Run logister auth login again and review the requested read scopes. |
| Missing project error | Pass --project <uuid-or-slug> or set LOGISTER_PROJECT. |
| Feature is not supported | Run logister doctor and read the server feature map. The server may not expose that command group yet. |
| Output hides values you expected | The CLI masks credential-like values by default; ordinary key columns stay visible. Prefer server-minimized output; use --no-redact only for approved local debugging. |
For package-specific bugs and feature requests, use the Logister CLI issue tracker.
Next steps
Use the CLI alongside the product guides.
Read related requests from the terminal
CLI 1.2.0+ can follow an occurrence across explicitly connected projects on Logister 3.7+. The instance and both projects must enable correlations. Your token needs events:read, errors:read, traces:read and deployments:read, and access to both projects.
logister events correlations EVENT_UUID --project PROJECT_UUID --format jsonWith CLI 1.2.1 and Logister 3.8, optional fields include HTTP status, recorded duration and measurement scope, app build/device details, issue ownership and the selected occurrence as anchor. JSON and NDJSON preserve coverage; tables show separate HTTP/span outcomes. Older servers can omit enriched fields. Check package availability before upgrading.
Results are bounded and may be partial. Matching identifiers do not prove cause, and client/server times should not be subtracted. Use the web interface for connected impact reports and deployment comparisons. Read verification and token requirements or connected impact.