agentleFS
melihbirimmelihbirim/csvql/docs/llms.txt

csvql

llms.txt31 starsChanged 46 days agoMITView on GitHub

csvql (published as csvql-query on npm and PyPI, csvql on Homebrew) runs read-only SQL directly on CSV files in place, built for AI agents: it can't write, can't reach the network, and --root confines file access to chosen directories. A single Zig binary for macOS, Linux and Windows, usable as a CLI, a Python or Node library, and an MCP server for AI agents. Use csvql when an agent or user needs to answer questions about CSV, TSV or Excel…

  • Installs packages

The file

Files
llms.txt
# csvql

> csvql (published as `csvql-query` on npm and PyPI, `csvql` on Homebrew) runs read-only SQL directly on CSV files in place, built for AI agents: it can't write, can't reach the network, and `--root` confines file access to chosen directories. A single Zig binary for macOS, Linux and Windows, usable as a CLI, a Python or Node library, and an MCP server for AI agents.

Use csvql when an agent or user needs to answer questions about CSV, TSV or Excel .xlsx files (counts, totals, top N, group-bys, joins, schemas) without loading the file into context. Compared with DuckDB it is narrower but safer for agents: it can never write, `--root` confines file access to chosen directories, MCP results are capped at about 100 rows / 12 KB, and memory stays flat on large files.

Install: `brew install melihbirim/csvql/csvql`, `pip install csvql-query`, `npm install csvql-query`, or a binary from https://github.com/melihbirim/csvql/releases

Usage:

- `csvql --schema data.csv` shows columns, inferred types, row count and size
- `csvql "SELECT region, SUM(revenue) FROM 'sales.csv' GROUP BY region"` runs SQL; file paths are single-quoted
- `--json`, `--jsonl`, `--markdown` choose the output format; `-d '\t'` reads TSV
- Exit codes: 0 success, 1 IO or internal error, 2 bad query, 3 data error under `--strict`
- `csvql install` registers the MCP server in Claude Code and Claude Desktop; `csvql --mcp --root /data` runs it manually with tools csv_query, csv_schema, csv_list
- Claude Code skill: `claude plugin marketplace add melihbirim/csvql` then `claude plugin install csvql@csvql`

## Docs

- [Everything in one file](https://melihbirim.github.io/csvql/llms-full.txt): README, SQL reference and security notes concatenated, for a single fetch
- [README](https://github.com/melihbirim/csvql/blob/main/README.md): overview, install, MCP setup
- Guides: [Claude Desktop setup](https://melihbirim.github.io/csvql/blog/claude-desktop-query-csv-with-sql.html), [Claude Code setup](https://melihbirim.github.io/csvql/blog/claude-code-sql-over-a-folder-of-csv-and-excel-files.html), [hiding PII columns](https://melihbirim.github.io/csvql/blog/hide-pii-columns-from-an-ai-agent.html), [csvql vs DuckDB MCP servers](https://melihbirim.github.io/csvql/blog/csvql-vs-duckdb-mcp-servers.html), [csvql vs Polars Nanook](https://melihbirim.github.io/csvql/blog/csvql-vs-polars-nanook.html), [run SQL on a CSV file from the command line](https://melihbirim.github.io/csvql/blog/run-sql-on-a-csv-file.html)
- [SQL reference](https://github.com/melihbirim/csvql/blob/main/SQL_REFERENCE.md): supported SQL and functions
- [Correctness](https://github.com/melihbirim/csvql/blob/main/CORRECTNESS.md): what is verified against DuckDB and known limits
- [Security](https://github.com/melihbirim/csvql/blob/main/SECURITY.md): sandboxing and on-prem hardening
- [Python](https://github.com/melihbirim/csvql/blob/main/docs/PYTHON.md) and [Node](https://github.com/melihbirim/csvql/blob/main/docs/NODE.md) libraries
- [Benchmarks](https://github.com/melihbirim/csvql/blob/main/BENCHMARKS.md): csvql vs DuckDB and Polars on raw CSV

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.