OpenParable
Skip to content
← Back to skills

Sq

Apps & Automation
sq

Sq is an Agent Skill for apps & automation published in the neilotoole/sq repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guides use of the sq CLI to query SQL databases and tabular files with SLQ (sq's jq-like query language) or native SQL, manage sources, choose output formats, and run inspect, diff, and table commands. Use when the user mentions sq, SLQ, wrangling CSV/Excel/JSON/DB data, cross-source joins, or command-line data pipelines after installing sq from https://sq.io.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/neilotoole/sq/blob/HEAD/skills/sq/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sq, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

sq (CLI)

sq is a command-line tool for structured data: SQL databases and formats like CSV, TSV, JSON, and Excel. It combines SQL- and jq-style querying. Official documentation lives at sq.io.

This skill targets use of an already-installed sq binary rather than guidance on building from source. Prefer sq help, sq <command> --help, and sq.io over guessing flags.

Verify the install

sq --version
sq help
sq driver ls

sq driver ls lists drivers available in this build (e.g. postgres, duckdb, oracle, sqlite3, csv).

Sources and handles

  1. Add a data source with sq add. You get a handle (e.g. @my_pg).
  2. List sources: sq ls.
  3. Active source: sq src shows or sets which source SLQ queries use when you omit an explicit handle.

Use @handle to target a source in queries (e.g. @my_pg.actor). Concepts: handle, sources.

Query modes

ModeWhen to use
SLQ (default)sq’s jq-like query language on sources and tables. See Query language.
Native SQLDatabase-specific SQL via sq sql.

Cross-source joins (e.g. CSV to Postgres): Cross-source joins.

Ping and inspect

  • sq ping @handle — connectivity check (ping).
  • sq inspect … — schema, columns, sizes (inspect). Can emit a schema entity-relationship diagram as Markdown/HTML (--markdown/--html), Mermaid source (-f mermaid-erd), or an image file (-f svg-erd/-f png-erd).

Output formats

Results can be printed as text, JSON, CSV, HTML, Markdown, XML, XLSX, etc. See Output formats and insert for writing query results into a database.

Common flags: -j/--json, -t/--text, -o FILE; details in sq --help and the docs above.

Diff and table operations

  • sq diff — compare metadata or row data between sources or tables (diff).
  • sq tbl — copy, truncate, drop tables (tbl copy, truncate, drop).

Driver-specific help (load on demand)

When the task involves a specific driver (connection strings, options, caveats), open the matching file under references/:

Overview of all drivers: Drivers.

Online resources