@loguro/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Pavel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,554 @@
+# @loguro/cli
+
+Command-line tool for querying [Loguro](https://logu.ro) logs.
+
+## Install
+
+```bash
+npm i -g @loguro/cli
+# or run without install:
+npx @loguro/cli logs --help
+```
+
+## Quick start
+
+```bash
+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.
+
+```bash
+loguro login                          # paste a pat_… from /app/settings/cli-tokens
+loguro whoami
+loguro logout
+```
+
+After login you only need slugs:
+
+```bash
+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)
+
+```bash
+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:
+
+```bash
+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
+
+```
+loguro logs --interactive   # or -i
+```
+
+Opens a TUI navigator over your 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
+
+All actions wired to the same backend endpoints as the standalone commands. Pipe-friendly: without `-i` everything stays plain text streamable.
+
+### Zero-UI workflow
+
+Setup an entire project — including alerts and integrations — from the terminal:
+
+```bash
+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>`:
+
+```bash
+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:
+
+```bash
+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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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.
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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=you@x.com --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
+
+```bash
+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
+
+```bash
+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.