Every Flight server demo today starts with "first, write a Python script." sparrowCLI is one binary: connect to any Arrow Flight SQL server, browse the catalog, run SQL, and pipe columnar data onward — to a file, a chart, or the next process.

That's the whole catalog — vendor, tables, every schema — as markdown, in one round trip. A human reads it; an AI agent reads it natively. It's why Claude Code can orient itself on any Flight server with a single command.

Anything a server advertises in GetTables, the CLI can reach — this endpoint advertises search_meta, a server-side BM25 full-text index over 2.8 million series descriptions: search_meta('<query>' [, lim := N] [, dedup := true]). Ranked matches (default cap 50), dedup := true collapses per-frequency duplicates, and total_matches carries the full hit count so the cap is never silent. A macro, not a subcommand — ls discovers it, plain SQL composes with it (WHERE, JOIN, anything).

The session above is real — the endpoint is this site's public Flight server, the same 136-million-row lake behind the browser demo, and demo:demo is yours to use. The client is validated against GizmoSQL, ROAPI/DataFusion, Dremio, InfluxDB 3, and Sparrow — both auth families (basic and bearer + headers), one binary, pure Go, no runtime. The source is public — Apache-2.0, on GitHub — and release binaries ship for Linux, macOS and Windows (amd64 + arm64).

Every connection failure looks the same from a client — one opaque error. sparrow doctor walks the stack one layer at a time, and on a TLS failure it shows the certificate the wire actually presented. The capture above is real: a fixture that "wouldn't verify" turned out to be antivirus re-signing the connection. -o json hands agents the same diagnosis as structured data; any hard failure exits 2.

Ten probes of the Flight SQL surface — catalog RPCs, prepared statements, declared schemas, actions — and a GetSqlInfo decode that lints the capability block against the spec. The capture above is real and the server it flags is this site's own demo: an external tester proposed the linter, and its first catch was our mistyped SqlInfo codes — fixed the same day (the card now reads ✓ 9 entries · SQL ✓ · Substrait ✓ · read-only ✓). gizmosql decodes clean: 85 entries · SQL ✓ · Substrait ✗ · txns ✓ · cancel ✓. Same card, five vendors — the quirk matrix is in docs/conform.md.

pull — a Direct Pull — sends a client-constructed ticket straight to the server (the Flight DoGet RPC) — no GetFlightInfo, no SQL text — so a known read is one round trip, not two. Sparrow serving nodes take JSON in two dialects: {"series":[…]} by key, or {"sql":"…"} for an arbitrary read-only query. The wire comes back lz4-compressed because the client advertised it (negotiated, never forced). doget still works as an alias. Opaque-handle vendors don't accept client tickets — doctor --server probes which kind a server is.

Flight SQL can carry a query as SQL text or as a serialized Substrait plan — sparrow implements both sides of the spec: sql --substrait plan.pb sends CommandStatementSubstraitPlan (with a capability pre-check, so a server that doesn't accept plans yields a clear message, not a raw gRPC error), and this site's own serving node consumes plans — the 277-byte plan above ran against the 136M-row public table with no SQL string anywhere on the wire. Substrait's audience is software talking to software: query builders and dataframe libraries serializing plans under a typed API — no SQL generation, no dialect differences. Producer recipe and the optimizer footgun we hit: docs/substrait.md.

sparrow check screens a dataset without downloading it — every check is one conservative SQL aggregate, pushed to the server: duplicate keys, NULL census, staleness against --max-age, frozen series (a stuck feed's signature), σ-outliers. Findings exit 1, so sparrow check t --key id && deploy is a data gate in CI.

sparrow diff compares one table on two servers — schema, row count, time bounds, a numeric fingerprint — as conservative aggregates on both sides; nothing is downloaded. The capture proved this site's two public engines (a Python server and C++ GizmoSQL) serve an identical 136-million-row snapshot. Identical exits 0, drift exits 1 — one cron line becomes a replication monitor.

ping runs a bare TCP connect next to a lightweight RPC on the warm channel — the gap between the two medians is the server, not the network. --stats breaks a query into plan / first byte / stream, with the bytes counted at the gRPC layer as they crossed the wire. Both captures above are real, against this site's public endpoint. Every benchmark number on this site is reproducible with a flag.

The gap sparrow fills isn't "a CLI exists" — it's Arrow-native ergonomics: catalog discovery over the Flight RPCs, profiles, orient, output that follows the consumer, and conventions agents can script against.

Output (-o): table · csv · json · jsonl · md · arrow — or a file path (.parquet .csv .json .jsonl .arrow .md). Defaults: a TTY gets a table (numeric columns add a whole-stream sparkline), a pipe streams raw Arrow IPC; -o md to stdout caps at 1,000 rows (file sinks always get everything). Exit codes: 0 ok · 1 query error or a gate hit (check findings, diff drift, audit exposure — the command ran fine, it found something; that's what makes them CI gates) · 2 connection/auth · 3 usage — scripts and agents branch on them. Profiles live in ~/.sparrow/config.json.