localql 1.0.1

LocalQL packages csvql, a DuckDB-powered CLI for querying local CSV files like SQL tables.

LocalQL

LocalQL is a lightweight DuckDB-powered tool for querying local CSV files with SQL. It installs the csvql command and provides named tables, saved SQL, readable output, exports, and an optional terminal menu.

Contents

• Quickstart
• Core workflows
• Terminal menu
• Safety
• Documentation

Quickstart

Install LocalQL:

pip install localql

The query below uses the example data in this repository. From another directory, replace the path with one of your own CSV files.

Query the example CSV:

csvql query examples/saas_revenue/data/revenue_movements.csv \
  "SELECT movement_type, SUM(mrr_delta) AS net_mrr_change
   FROM revenue_movements
   GROUP BY movement_type
   ORDER BY movement_type"

For a complete copy-and-paste walkthrough, see Getting started.

Core workflows

When you want to…	Start here
Query a CSV or join named tables	CLI reference
Reuse a project catalog and saved SQL	Project catalogs
Inspect, sample, or profile a source	Inspect, sample, and profile
Export a result or reuse it as a CSV source	Save and reuse results
Check configured data-quality rules	Data-quality checks

CSVQL does not implement a SQL engine. DuckDB executes SQL; CSVQL manages the local workflow around table aliases, project configuration, output, and exports.

Terminal menu

The optional csvql menu workbench provides sources, a SQL editor, results, history, and explicit export actions in the terminal:

pip install "localql[tui]"
csvql menu
csvql menu /path/to/orders.csv

The terminal menu is optional; all core commands also work without it. See the Terminal menu guide for keys, source actions, history, and result handling.

Safety

LocalQL treats user-authored SQL as trusted local DuckDB SQL. It does not sandbox DuckDB or restrict filesystem access. Run only SQL you trust.

Documentation

Use LocalQL

• Getting started
• CLI reference
• Terminal menu guide
• Troubleshooting
• FAQ
• SaaS revenue example

Reference

• JSON output reference
• Architecture
• v1 release notes
• Changelog

Project and support

• Roadmap
• Contributing
• Security
• Support
• Code of Conduct