Logister Documentation CLI
Documentation / CLI

Use the Logister CLI to inspect project telemetry from a terminal.

The Logister CLI gives developers, operators, scripts, and AI coding tools read access to project telemetry without using project ingest keys. Use it after events are flowing so you can list projects, check server capabilities, inspect recent events and logs, and export grouped issue context.

Install the CLI Connect to Logister Run read commands

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 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 20 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 doctor to 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.

Use npm when Node is already part of your toolchain:

shell 
npm install -g logister-cli
logister version

Use Homebrew on macOS or Linuxbrew:

shell 
brew tap taimoorq/logister
brew install logister
logister version

Use Scoop on Windows:

powershell 
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:

shell 
yarn global add logister-cli
pnpm add -g logister-cli

Use npx for one-off checks without a global install:

shell 
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 code and opens the Logister approval URL. Sign in, choose which projects the token may read, approve the request, then return to the terminal.

shell 
logister auth login --host https://logister.example.com

If the CLI cannot open a browser, copy the displayed URL manually:

shell 
logister auth login --host https://logister.example.com --no-browser

For automation, avoid putting tokens directly into shell history:

shell 
printf '%s' "$LOGISTER_TOKEN" | logister auth login \
  --host https://logister.example.com \
  --token-stdin

Saved tokens use macOS Keychain when available and fall back to a local 0600 config file on other platforms.

Verify setup

Check the active profile and server capability map.

shell 
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. It does not print the token value. A healthy first run should show the Logister server version, recommended CLI version, and enabled features such as projects, events, logs, error groups, and AI context bundles.

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.

shell 
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 grouped issue commands when you already know the failing error group:

shell 
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> --for-ai --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.

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.

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. Current servers support the first read slice: projects, project summaries, events, logs, error groups, issue export, and AI context bundles. Other command groups are scaffolded in the CLI but stay disabled until the server exposes those read or write capabilities.

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 Feature-gated The CLI has command scaffolding, but current servers report these features as unavailable.
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.
  • Project ingest API keys are not accepted for CLI reads.
  • CLI output redacts sensitive-looking fields by default.
  • Use --no-redact only when you intentionally need raw payloads and have permission to view them.

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, local config files, or exploit details.

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.
Device login expired Start a fresh auth login. Device authorization requests are short-lived by design.
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.
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 redacts sensitive-looking fields by default. 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.

Create a project first The CLI can read projects your account can access, but ingestion starts with a Logister project and an API key. Send telemetry over HTTP Use project API keys for events, check-ins, and deployment records. Keep CLI tokens for reads. Understand grouped issue triage Read how Logister groups errors, stores context, and tracks owner/status changes before exporting issue context from the CLI.