@loguro/cli

Command-line tool for querying Loguro logs.

Install

npm i -g @loguro/cli
# or run without install:
npx @loguro/cli logs --help

Quick start

loguro init   # interactive wizard: auth → project → key → link → first log

Walks you through PAT setup, project creation, ingestion key generation, and links the current directory. Ends with copy-paste SDK examples (curl, Node, Python, Go) using your real key — ready to ship logs the next second.

Already have an account? loguro init detects existing tokens and projects and skips the parts you don't need.

Auth

One token (PAT) covers all your projects.

loguro login                          # paste a pat_… from /app/settings/cli-tokens
loguro whoami
loguro logout

After login you only need slugs:

loguro config add prod --slug=my-prod-app
loguro config add staging --slug=my-stg-app
loguro link my-prod-app               # link a directory directly to a slug

Env vars (CI / one-shot)

export LOGURO_TOKEN=pat_xxx
export LOGURO_PROJECT=my-app
export LOGURO_BASE_URL=https://logu.ro   # optional override

LOGURO_TOKEN overrides the saved auth.json, useful for CI.

Project link

Link a directory so you don't have to specify the project every time:

cd ~/work/api-prod
loguro link my-prod-app          # writes ./.loguro: { "slug": "my-prod-app" }
loguro logs -l error             # uses your PAT + the linked slug

# Or, if you have an app configured under a friendlier name:
loguro config add prod --slug=my-prod-app
loguro link prod                 # writes { "app": "prod" }

Walk-up: from any subdirectory, the closest .loguro upwards is used. Commit it to git — no secrets stored, only the slug or app name.

Resolution order

1. --app <name> flag (explicit per-command)
2. .loguro in current dir or any ancestor (slug or app)
3. Default app from config store
4. LOGURO_PROJECT env / --project (with the active PAT)

The active PAT is LOGURO_TOKEN (env) or the saved auth.json (from loguro login).

Commands

Setup & diagnostics

loguro init           Interactive setup wizard (auth → project → key → link → first-log examples)
loguro doctor         Health check: auth, backend, env, configured apps, all linked dirs, version

Querying logs

loguro logs           Query logs with filters
loguro tail           Follow new logs (poll)
loguro count          Count logs (total or filtered)
loguro get            Fetch a single log by ID with full context
loguro distinct       List unique values for a field
loguro timeline       Logs around a specific log ID
loguro trace          All logs sharing a trace ID, in chronological order
loguro slow           Slow requests above duration threshold
loguro sample         Random sample of logs
loguro group          Group logs by field
loguro replay         Replay a window of logs as if streaming live, at adjustable speed
loguro investigate    AI investigation of a log (uses your plan AI quota)

Visualizations

loguro top            Top N values for a field with horizontal bars (level, message, context.X)
loguro chart          Volume over time as compact sparkline or chunky bars (--bars)
loguro analytics      Aggregated dashboard: levels, daily timeline, top errors, endpoints
loguro health         Project health badge: error rate now vs previous, optional 24h trend
loguro diff           Compare log patterns between two windows (new / spiked / dropped)

Local config

loguro config         Manage app configurations (slug aliases)
loguro link           Link current dir to a slug or app
loguro unlink         Remove .loguro link

Auth

loguro login          Save a PAT
loguro logout         Remove the saved PAT
loguro whoami         Show current user / token info

Account & projects

loguro projects       List / create / rename / delete projects
loguro keys           Manage project ingestion keys (used by your SDK)
loguro tokens         Manage CLI tokens (PATs)
loguro usage          Current month usage + plan caps
loguro billing        Subscription, current plan, available plans

Alerts & notifications

loguro channels       Manage notification channels (webhook | discord | slack | telegram)
loguro alerts         Manage project alerts
loguro integrations   Connect issue trackers (jira/linear/github) and message integrations (slack/discord/telegram)

Workflow helpers

loguro pin            Pin recurring logs to track (📌 marker auto-shown on lists)
loguro share          Create / list / revoke public markdown shares of logs (single or multi-log)

Interactive mode (legacy, logs -i)

loguro logs --interactive   # or -i

The original one-shot TUI navigator built on top of loguro logs:

• ↑↓ / jk navigate, enter to inspect a log, esc back
• / live fuzzy search (highlights matches; prefix = for exact substring)
• space multi-select rows; s shares selected as one markdown page, p bulk pins, c copies all IDs
• r refresh, ? keybindings overlay, q quit

In log detail:

• e AI explain (light) · i AI investigate (deep, code-aware)
• a create alert from this log (suspends interactive, runs full alert wizard, returns)
• p pin/unpin toggle (shows encounter count for recurring logs)
• t show all logs sharing the same trace ID
• s create public share, URL auto-copied to clipboard
• c copy log ID, o open in web console, j toggle JSON-colored context

Pipe-friendly: without -i everything stays plain text streamable.

TUI (multi-view app, loguro tui)

loguro tui                          # opens at Logs view
loguro tui --view=saved-views       # jump straight to a specific view
loguro tui --app=prod               # use a configured app shortcut

A persistent multi-view Ink app. Unlike logs -i (one shot, one feed), loguro tui is a small terminal app with view stack, navigation, command palette, and shared search state. Press ? inside for the full keybinding reference (multi-section, navigable with ← →).

Views

• Logs (1) — live tail with cursor + paging. Scroll position, applied filter and live/pause state survive when you go into a detail view and come back. space toggles live polling (green ● live, yellow ⏸ paused).
• Pins (2) — manage pinned logs (fingerprint-based). Resolve / mark-watching / delete inline.
• Saved Views (3) — backend-synced saved filters (same store the web console uses). enter to apply, d to delete. Create new ones from Logs with s.
• Docs (4) — browse logu.ro/docs/* inline. / fuzzy-search across all pages, enter opens, tab switches focus list/body, r refreshes cache. Markdown is rendered with headings/code/lists/quotes. Cached locally for 24h in ~/.config/loguro/docs-cache/.
• Alerts (5) — list / toggle / delete project alerts. c opens the create-alert wizard (name → channel → levels → message-substring → cooldown). You can also derive an alert from a log: open the log and press a to start the wizard with name/level/message pre-filled.
• Log detail — a create alert from this log (wizard pre-filled with name/level/message), p pin, t trace, c copy id, o open in web, j JSON view, y copy full JSON.
• Trace — every log sharing a trace id, in order.
• Command palette (:) — fuzzy-search every registered action and view by title/keyword.

Global keys

• 1 / 2 / 3 / 4 / 5 — switch to Logs / Pins / Saved Views / Docs / Alerts
• / — focus search bar (filter logs by the same query syntax as the web)
• : — command palette
• ? — multi-section help (this is the source of truth for every key)
• q — pop one view from the stack
• Q — quit the TUI
• esc — close overlay / unfocus search / pop view

Logs navigation

• ↑/↓ or j/k — move by 1
• ctrl+↑/↓ — jump 10 lines
• g / G — top / bottom
• n — next page (older logs)
• r — reload
• space — pause / resume live tail
• s — save current filter as a saved view
• v — open Saved Views list
• x — clear current filter

Filter syntax

Same as the web console: level:error @last-1h !context.env:staging "payment timeout". The search bar offers static completions today (filter keys + common operators); live values are next.

Layout

Top: a two-row header — first row shows loguro · <slug> on the left and a health badge on the right (✓ healthy 3% → / ⚠ warning 8% ↑ / ✗ critical 25% ↑ / · idle for empty projects). The badge polls every 60s, derived from the error-rate trend over the last 20 minutes. Second row: view tabs. Bottom: status bar (item count, live state, applied query), search bar, shortcuts row. The shortcuts row auto-truncates to terminal width and shows +N ? if anything was hidden — open ? for the full keymap.

All actions hit the same backend endpoints as the standalone commands. Anything you do in the TUI (pins, saved views, alerts, etc.) shows up on the web too.

Zero-UI workflow

Setup an entire project — including alerts and integrations — from the terminal:

loguro login                                                   # paste pat_…

# Create project + ingestion key
loguro projects create "My API"                                # → slug auto-generated (e.g. happy-otter)
loguro keys create happy-otter --name=server                   # server key, default; → shown ONCE; copy into your SDK
loguro link happy-otter                                        # link cwd to that slug

# Browser key for a frontend app (requires at least one --origin)
loguro keys create happy-otter --name=web --type=browser \
                               --origin=https://app.example.com \
                               --origin=https://staging.example.com

# Wire up notifications
loguro channels create --name=ops --type=slack \
                       --token=xoxb-… --channel=#alerts
loguro alerts create --name "prod errors" --channel=ops \
                     --levels=error,critical --cooldown=30

# Connect GitHub for AI-powered code-aware investigations
loguro integrations connect github --token=ghp_… \
                                   --owner=mycompany --repo=api \
                                   --allowAiCodeSearch

# Use it
loguro logs                                                    # see logs as soon as your SDK ships them
loguro investigate <logId>                                     # AI explains the error using your repo

Project secrets are shown only once at create time — copy them immediately.

Run loguro <command> --help for full options.

App shortcut

If you have an app named in config, use it as the first arg — equivalent to --app=<name>:

loguro prod logs -l error          # = loguro logs --app=prod -l error
loguro prod tail                   # = loguro tail --app=prod
loguro prod                        # = loguro logs --app=prod (last 20)
loguro staging slow                # = loguro slow --app=staging

Query syntax

The logs, tail, slow, and sample commands accept a query string with the same syntax as the Loguro UI, via -q or as a positional:

loguro logs -q 'level:error @last-1h'
loguro 'level:error @last-1h'                         # positional shortcut
loguro prod 'level:error context.duration:>=500'      # with app name
loguro tail 'level:critical|error'

Reference:

| Token | Meaning | |-------|---------| | level:error / level:error\|critical | filter by level (OR with \|) | | !level:debug | exclude levels | | message:"phrase with spaces" | message substring (quote spaces) | | message:single | unquoted single word | | !message:"foo" | exclude messages | | trace:"abc123" | trace ID | | context.user_id:42 | context field equals | | context.duration:>=500 | with operator (=, !=, >, <, >=, <=) | | !context.env:staging | exclude context | | search:"payment" | global search across message + context | | @today / @yesterday / @last-1h / @last-24h / @last-7d | time range | | @"2 hours ago" | natural language (chrono-node) | | from:@today to:"1 hour ago" | explicit range | | !@yesterday | exclude time range | | --errors | shortcut: level:error\|critical | | --warn / --debug / --critical / --info | level shortcuts | | --slow:1000 | duration > N ms | | --memory | query saved task-context parquets |

Unrecognized tokens emit a warning suggesting how to quote them.

Examples

Setup (interactive wizards)

# Full first-time setup — walks you to first log in under 2 min
loguro init

# Create a project interactively (offers to chain key + link)
loguro projects create

# Create a project non-interactively (CI / scripted)
loguro projects create "My API" --with-key=server --link
loguro projects create "Web App" --with-key=front --keyType=browser \
                                  --origin=https://example.com --origin=http://localhost:3000

# Create a notification channel interactively (type select + per-type prompts with hints)
loguro channels create

# Create an alert from an existing log id (derives name/level/message-substring)
loguro alerts create --from-log 01KQ0E1ZTAP7YWFBK1S2K6XM2W

Querying & investigation

# Last 20 errors
loguro logs -l error

# Last 24h, payment-related, slower than 200ms, exclude staging
loguro logs --from 24h -m payment --slow 200 -c '!env=staging'

# Errors only, follow live
loguro tail -l error

# All envs in use
loguro distinct env

# Logs around an error
loguro timeline 01KQ0E1ZTAP7YWFBK1S2K6XM2W --window 60

# Random 20 errors with full context
loguro sample -n 20 -l error

# Group by level for error+critical
loguro group level -v error -v critical

# JSON output for piping into jq
loguro logs -l error --json | jq '.items[].message'

# Count for CI alerts
ERRORS=$(loguro count -q 'level:error @last-1h' --json | jq '.count | tonumber')
[ "$ERRORS" -gt 100 ] && curl -X POST $SLACK_WEBHOOK -d "alert: $ERRORS errors"

# Single log with full context
loguro get 01KQ0E1ZTAP7YWFBK1S2K6XM2W

# AI investigate (uses plan AI quota; cached after first run)
loguro investigate 01KQ0E1ZTAP7YWFBK1S2K6XM2W
loguro investigate 01KQ0E1ZTAP7YWFBK1S2K6XM2W --no-cache
loguro investigate 01KQ0E1ZTAP7YWFBK1S2K6XM2W --raw      # streamed text for pipes
loguro get 01KQ0E1ZTAP7YWFBK1S2K6XM2W --investigate     # show log + AI in sequence

# All logs sharing a trace ID, in chronological order (debug a request end-to-end)
loguro trace 01KQ0E1ZTAP7YWFBK1S2K6XM2W
loguro trace 01KQ0E1ZTAP7YWFBK1S2K6XM2W --no-showContext
loguro prod trace 01KQ0...                              # app shortcut works

# Trim output to specific fields (works on logs/tail/slow/sample)
loguro logs --fields message,context.service,context.userId
loguro logs -l error --fields timestamp,message,context.path
loguro logs --fields message --json | jq '.items[]'

# Replay a window of logs as if streaming live (with density chart at top)
loguro replay                                       # last 5min @ 2x
loguro replay --from 1h --speed 10x                 # last hour at 10x speed
loguro replay --from "yesterday 14:00" --to "yesterday 15:00" --bars
loguro replay -l error --instant                    # just walk through with deltas
loguro replay --from 24h --speed 50x                # gap-compression auto-skips quiet stretches
loguro replay --from 24h --no-compress-gaps         # disable gap compression

Visualizations

# Top values for a field — horizontal bars with percent
loguro top level                              # last 24h by default
loguro top level --from 7d
loguro top message -l error -n 20             # top 20 error messages
loguro top context.service --from "3 days ago"
loguro top context.endpoint -l error          # problematic endpoints
loguro top message --json | jq '.values[].value'

# Volume over time — sparkline (default) or chunky bars (--bars)
loguro chart                                  # last 24h
loguro chart --bars                           # chunkier bar chart with axis
loguro chart -l error --from 7d --bars
loguro chart --notLevel heartbeat --bars      # exclude noise
loguro chart --json | jq '.buckets[].value'

# Aggregated dashboard — levels, daily timeline, top errors, endpoints
loguro analytics                              # last 7d
loguro analytics --from 30d -l error
loguro analytics --json | jq '.byLevel'

# Health badge — error rate last 20min vs previous 20min, status (operational/degraded/incident)
loguro health                                 # quick status check
loguro health --trend                         # adds 24h error-rate + volume sparklines
loguro health --json | jq '.status'           # 'operational' | 'degraded' | 'incident'

# Compare windows — new patterns, spikes, drops between baseline and comparison
loguro diff yesterday                         # baseline yesterday vs current view
loguro diff 2-days-ago yesterday              # explicit two-window
loguro diff "last monday" "today"             # natural language windows
loguro diff yesterday --spike 100 --drop 30   # tighter thresholds
loguro diff yesterday --json | jq '.patterns[] | select(.status=="new")'

Sharing logs

Public markdown links — anyone with the URL can view. Includes the log message, all context, trace timeline if any, and AI investigation if cached.

# Single log
loguro share create 01KQ0E1ZTAP7YWFBK1S2K6XM2W

# Multiple logs as ONE markdown page (great for bug reports / Linear tickets)
loguro share create-context 01KQ0... 01KR3... 01KS9...

# List + revoke
loguro share list
loguro share delete <hash>           # accepts 4+ char prefix
loguro share update <hash> <logId>   # regenerate with fresh data (incl. new AI cache)

In loguro logs --interactive, space to multi-select rows then s runs share create-context and copies the URL automatically.

Diagnostics

# Full health check: auth, backend, env vars, configured aliases, all linked dirs, projects, version
loguro doctor

# Discover all .loguro files on disk (walks ~/Desktop, ~/code, ~/work, ~/projects, …)
loguro doctor --scan

# Custom scan root
loguro doctor --scan-root ~/dev/work

# JSON for tooling
loguro doctor --json | jq '.indexedLinks'

Linked directories are recorded automatically when you run loguro link or loguro init. The index lives at ~/.config/loguro/links.json and prunes itself when files are deleted.

Alerts & notifications

# Channels — interactive (recommended; prompts include where to obtain credentials)
loguro channels create

# Channels — non-interactive (CI / scripted)
loguro channels create --name=ops --type=webhook --url=https://...
loguro channels create --name=ops-slack --type=slack --token=xoxb-... --channel=#alerts
loguro channels create --name=ops-tg --type=telegram --bot-token=... --chat-id=...
loguro channels list
loguro channels enable ops      # / disable
loguro channels delete ops --yes

# Alerts — derive from an existing log (recommended after seeing an error in `loguro logs`)
loguro alerts create --from-log 01KQ0E1ZTAP7YWFBK1S2K6XM2W
# → opens a wizard pre-filled with name, level, message substring from that log

# Alerts — non-interactive
loguro alerts create --name "prod errors" --channel=ops \
                     --levels=error,critical \
                     --messageContains=payment \
                     --cooldown=30
loguro alerts list
loguro alerts show "prod errors"
loguro alerts update "prod errors" --levels=critical
loguro alerts disable "prod errors"     # / enable
loguro alerts delete "prod errors" --yes

Integrations

Connect issue trackers (for AI-aware investigation context) and per-project message integrations:

# GitHub — enables AI code search in `loguro investigate`
loguro integrations connect github --token=ghp_… \
                                   --owner=mycompany --repo=api \
                                   --branch=main --allowAiCodeSearch

# Linear / Jira
loguro integrations connect linear --api-key=lin_… --teamId=...
loguro integrations connect jira --base-url=https://org.atlassian.net \
                                  [email protected] --api-token=... --project-key=BUG

# Per-project messaging (different from global channels)
loguro integrations connect slack --token=xoxb-… --channel=#alerts
loguro integrations connect discord --webhook-url=...
loguro integrations connect telegram --bot-token=… --chat-id=…

# Discover before connecting
loguro integrations github-repos --token=ghp_…
loguro integrations github-branches --owner=foo --repo=bar
loguro integrations linear-teams --api-key=lin_…

loguro integrations list
loguro integrations show github
loguro integrations disconnect github --yes

Pinned logs

loguro pin add <logId> --note "tracking until #1234 ships"
loguro pin list
loguro pin list --status watching        # / resolved
loguro pin show <pinId>
loguro pin update <pinId> --status=resolved
loguro pin remove <pinId> --yes

Account

loguro usage                       # current period quota + caps
loguro usage --history             # recent billing periods
loguro billing                     # plan + available upgrades
loguro tokens list                 # CLI tokens (PATs)
loguro tokens create --name=ci     # → pat_… shown ONCE
loguro tokens delete <id> --yes

Context filters

-c key=value filter on context.<key>. Repeatable. Supports operators and negation:

-c user_id=42                # context.user_id = 42
-c duration>=500             # context.duration >= 500
-c '!env=staging'            # NOT context.env = staging

Operators: =, !=, >, <, >=, <=. Prefix ! to negate.

Time ranges

--from / --to accept ISO dates, relative shorthand, or natural language (via chrono-node):

--from 30m              # 30 minutes ago
--from 24h              # 24 hours ago
--from 7d               # 7 days ago
--from 2w               # 2 weeks ago
--from 2026-05-01       # ISO date
--from 2026-05-01T10:00:00Z

--from "3 days ago"     # natural language
--from "yesterday"
--from "last monday"
--from "2 hours ago"
--to "yesterday at 18:00"

# Combinable
loguro logs --from "3 days ago" --to "yesterday" -l error

If a time string can't be parsed, the CLI prints a warning and passes it through to the API (which will return 400 with the offending value).

When to use the CLI vs MCP vs Web Console

Loguro ships in three surfaces. Pick the one that fits the workflow — they share auth and project data, so you can switch freely.

| Reach for Web Console when... | Reach for CLI when... | Reach for MCP when... | |---|---|---| | Visual exploration: charts, timeline, replay, log shares | Scripting, CI alerts, pipe to jq, batch operations | Talking to Claude/Cursor in your IDE about prod logs without leaving the editor | | First-time setup with interactive prompts (OAuth, integrations) | Reproducible setup as code: loguro projects create → keys create → alerts create in a script | "What errors hit payments in the last hour?" — natural language over your real logs | | Saved views, command palette browsing, embed widgets | Long-lived PAT in env, single token across all projects | Code-aware investigation: AI sees the log AND your repo (when GitHub integration is connected) | | Issue tracker creation with rich UI (Linear/Jira/GitHub) | .loguro link per directory, app shortcuts (loguro prod logs) | Quick context inline while debugging — no context switch |

Why MCP works zero-config

The MCP server reads the same ~/.config/loguro/auth.json that loguro login writes. Set up the CLI once and the MCP works in every IDE you connect it to — no second login, no rotated credentials per session.

Latency and footprint

• CLI: single HTTP call per command, streamed JSON, predictable. Best for fetching thousands of rows or piping to other tools.
• MCP: 6 focused tools (~1k tokens of system prompt) — minimal context overhead vs MCPs that ship 30+ tools. Built for Claude to call iteratively without burning the conversation.
• Web: real-time UI with live mode, charts, and AI investigation streaming. Heaviest but only when interactivity matters.

Combine them

A common workflow:

1. Web — set up the project, integrations, alerts once
2. CLI — wire loguro logs into CI, scripts, alerts you trigger from cron
3. MCP — debug interactively when an error comes in: ask Claude "what happened?", let it call query_logs + get_log_timeline to figure it out

All three see the same data. Pick by friction, not by capability.