logfire-cli

An unofficial Logfire CLI built for coding agents. It turns Logfire's read API into a small set of investigation commands, prints token-efficient TOON by default, and keeps arbitrary SQL available for everything else.

Why this exists

Pydantic ships an official logfire command for authentication, projects, tokens, and Python instrumentation. It does not provide a terminal-first telemetry explorer. logfire-cli fills that gap without shadowing the official binary.

The common path is short:

logfire-cli auth
logfire-cli services --since 1h
logfire-cli exceptions --service api --since 30m
logfire-cli trace 0123456789abcdef0123456789abcdef

Every result is bounded, deterministic, non-interactive, and useful when pasted into an agent context.

Install

With Bun 1.3 or newer:

bun add --global github:Laurens-Nys/logfire-cli

Or compile one native binary from source:

git clone https://github.com/Laurens-Nys/logfire-cli
cd logfire-cli
bun install --frozen-lockfile
bun run build
cp dist/logfire-cli ~/.local/bin/logfire-cli

Tagged releases publish native archives for macOS and Linux on Intel and ARM.

Authentication

Create a project read token in Logfire's UI or with its official CLI:

logfire read-tokens --project <organization>/<project> create
export LOGFIRE_READ_TOKEN=pylf_v1_...
logfire-cli auth

The token is read only from LOGFIRE_READ_TOKEN. It is never printed, logged, or stored. Its prefix selects the US or EU API automatically. Set LOGFIRE_BASE_URL only for a self-hosted or explicitly overridden endpoint.

Commands

Command	Purpose
auth	Show the token's organization, project, and selected endpoint
services [search]	Summarize service activity and error counts
metrics [search]	Inventory recent metric streams
exceptions [search]	Find exceptions by service, type, file, or message
logs [search]	Find logs by service, severity, or message
traces [search]	Find root traces by service, severity, or duration
trace <id-or-url>	List every span and log in one trace, with parent relationships
link <id-or-url>	Print the matching Logfire UI URL
schema [pattern]	Inspect the live records and metrics schema
query [sql]	Run arbitrary SQL; omit SQL to read stdin
api <path>	GET a relative Logfire endpoint as raw JSON
skill [--install DIR]	Print or install the generated agent skill
completions <shell>	Generate Bash, Zsh, or Fish completions

Run logfire-cli --help or logfire-cli <command> --help for exact flags and examples.

Shared query controls

All telemetry commands use the same controls:

--since 30m
--until 2026-08-07T12:00Z
-n, --limit 100
--environment production
--timezone Europe/Brussels

--since defaults to one hour and accepts durations or ISO timestamps. Limits range from 1 to 10,000 and default to 50. trace defaults to 1,000 rows because one trace can contain many child spans. Logfire's request-level limit remains the hard cap even when SQL contains its own LIMIT clause.

Output contract

Lists are TOON tables:

exceptions[2]{time,service,type,message,trace,span}:
  2026-08-07T11:55:00Z,worker,TimeoutError,job timed out,5bb...,91a...
  2026-08-07T11:52:10Z,api,ValueError,invalid state,08c...,32f...

Nested values become compact JSON strings inside cells, preserving the tabular shape. Empty results are explicit: exceptions[0]:. api is the sole raw-JSON escape hatch and link prints one bare URL.

Errors go to stderr and name the correction. Exit codes are stable: 0 success, 1 API/network/unexpected, 2 correctable input or SQL, 3 authentication, 4 not found.

Arbitrary SQL

The main backend is Logfire's current POST /v2/query API. Query records for logs and spans or metrics for metric points:

logfire-cli query "SELECT service_name, count(*) AS count FROM records GROUP BY service_name"

logfire-cli schema duration

logfire-cli query --since 24h <<'SQL'
SELECT span_name, count(*) AS count
FROM records
WHERE level >= 'error'
GROUP BY span_name
ORDER BY count DESC
SQL

The CLI sends explicit time and row bounds outside the SQL. Logfire's engine is Apache DataFusion with PostgreSQL-like syntax and Logfire extensions; inspect the live schema before relying on an uncertain column.

Agent setup

Install the bundled skill into any SKILL.md-aware project:

logfire-cli skill --install .agents/skills/logfire

The checked-in skills/logfire/SKILL.md and generated help/completions all derive from the same command registry. Tests fail if the bundled skill drifts.

API status

This project is built against Logfire's public read interfaces observed on 2026-08-07: POST /v2/query, GET /v1/read-token-info, and GET /v1/schemas. Logfire can evolve those endpoints. schema stays live, while the read-only api escape hatch keeps new GET endpoints reachable before a first-class command lands.

Official references: query API, SQL schema, and official SDK CLI.

Development

bun install --frozen-lockfile
bun run check

Tests cross the same public CLI seam callers use: arguments in, exact HTTP request and stdout/stderr/exit status out. Network responses are synthetic and contain no real project data or credentials.

License

MIT. This project is not affiliated with or endorsed by Pydantic.