@spfunctions/bi

Agent-friendly BI CLI. Query, inspect, and convert tabular data with SQL — powered by DuckDB.

npm i -g @spfunctions/bi

After install, the binary is bi:

bi head sales.csv

Why

LLM agents need a fast, reliable way to work with CSV, JSON, and Parquet files without spinning up a notebook. bi gives them four primitives:

| Command | What it does | |---|---| | bi head <file> | Peek at the first N rows | | bi schema <file> | Show column names and types | | bi query <file> --sql "..." | Run any DuckDB SQL against the file | | bi convert <file> -o <out> | Convert between CSV / JSON / Parquet |

Files are streamed via DuckDB's native readers — no full load into memory. CSV column types are auto-detected. Output is plain text by default, JSON/Markdown/CSV on demand for clean piping.

Examples

# Peek
bi head sales.csv -n 5

# Schema
bi schema sales.csv

# Query — use {t} as the table alias
bi query sales.csv --sql "SELECT region, SUM(amount) total FROM {t} GROUP BY region ORDER BY total DESC"

# Output as JSON for an agent to parse
bi query sales.csv --sql "SELECT * FROM {t} WHERE amount > 1000" -o json

# Convert CSV to Parquet
bi convert sales.csv -o sales.parquet

Install (from source)

git clone https://github.com/spfunctions/bi
cd bi
npm install
npm run build
node dist/cli.js head sample.csv

Output formats

| Flag | Format | Use case | |---|---|---| | table (default) | Aligned columns, ANSI colors | Humans in a terminal | | json | JSON array of objects | Pipe to jq, agents | | csv | RFC-4180 CSV | Pipe to other tools | | markdown | GFM table | Paste into docs/issues |

Why DuckDB

• Streams Parquet, CSV, JSON without loading into memory
• ~10x faster than pandas for typical analytics
• Zero config — no server, no schema definitions
• Battle-tested SQL engine, open source

License

MIT — Sparkco. Built for agents at sparkco.ai.