@spfunctions/bi

@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.