agentlogs (CLI)

Query structured local logs your coding agent can read. Reads the JSONL file the SDKs write (~/.agentlogs/app.log) and answers distinct questions — nothing overlaps. See the repo root and the contract.

npm install -g @almanac-ai/agentlogs-cli   # installs the `agentlogs` command

Commands

agentlogs events                 # flat, time-ordered records — "what happened?"
agentlogs trace <id>             # one cross-surface flow, in order
agentlogs time [name]            # duration of successful timed regions
agentlogs doctor                 # is logging working? do surfaces correlate?
agentlogs init                   # detect the stack, print setup
agentlogs init --write           # also create AGENTS.md when missing

There is no recent, errors, slow, tail, or latest command — those are filters and modes on the five above:

agentlogs events --since 10m                  # recent
agentlogs events --level error --since 10m    # errors
agentlogs events --tail                        # follow live
agentlogs trace --latest                       # the flow you just triggered
agentlogs trace tr_18cd --timings              # + nested timing tree
agentlogs time publish --since 1h              # one operation's stats

Filters (events, time)

--since 10m · --until <iso> · --service backend · --logger pages · --event 'publish.*' · --level error · --limit 50 · --tail · --json

Output contract

Human tables by default; --json on every command (--tail --json streams NDJSON). JSON → stdout, diagnostics → stderr. Exit 0 matches / healthy, 1 no matches / failed doctor check, 2 usage error. The CLI reports facts — it never calls something "slow" or "the bug."

Develop

npm install                 # from the repo root
npm run test:cli            # unit tests (tsx)
npm run dev -- trace --latest
npm run build               # → dist/