Home / Documentation / CLI reference

CLI reference

All commands take a query file, or - to read the query from stdin. Exit code 0 means success, 1 a query/data error (or a failed fmt --check), and 2 a usage error.

Commands

Command	What it does
`unsequel run <file \| ->`	Execute the whole program and print the result.
`unsequel check <file>`	Parse the program; with a schema, validate column/type usage too.
`unsequel compile <file>`	Print the generated DuckDB SQL (one CTE per lowering unit).
`unsequel preview <file> --stage N`	Run the program truncated at grammar stage N and show sample rows with the stage label.
`unsequel fmt <file>`	Print the canonical form; `--write` rewrites, `--check` exits 1 if not canonical.
`unsequel repl`	Interactive session; a query runs on a blank line, a lone `;`, or `.run`.

A bare unsequel on a terminal also opens the REPL. unsequel --version and unsequel --help are always available.

File directives

# source orders: ../data/orders.csv
# source products: ../data/products.csv
# schema: ../data/schema.json
from orders
join products on orders.product_id = products.product_id
select order_id, product_name

Directives must be the first lines of the file (no blank line or ordinary comment before them) and paths are resolved relative to the query file. --data overrides a directive with the same name; --schema overrides # schema:. Without any schema, tables loaded from the sources are introspected automatically, so run, compile, and preview work without a schema file. The formatter preserves directives.

Flags

Flag	Used by	Meaning
`--data name=path`	run, compile, preview, repl	Load a CSV/JSON/Parquet file as a table; repeatable. Without `name=`, the table name is derived from the file name.
`--schema path`	run, check, compile, preview, repl	JSON schema for pre-execution validation; overrides `# schema:`.
`--lines A:B`	all query commands	Run only the 1-based line range (the file's directives still apply).
`--stage N`	compile, preview	Truncate at grammar stage N. Required for `preview`; counts stages, not CTEs.
`--limit K`	preview	Sample rows to show (default 10).
`--format table\|json\|csv`	run, preview, repl	Output format (default `table`).
`--delimiter C`	run, compile, preview, repl	One-character CSV delimiter (default comma). Applies to all loaded CSVs.
`--column-type table.column=type`	run, compile, preview, repl	Override CSV/JSON column inference; repeatable. Types: `text`, `integer`, `number`, `boolean`, `date`, `time`, `timestamp`, `decimal(p,s)`.

Examples

# run a self-contained file
unsequel run examples/real/r01_top_products.unsequel

# run just the selected lines of a multi-query file
unsequel run queries.unsequel --lines 12:20

# query from stdin (needs --data because stdin has no directives)
echo "from orders | take 1" | unsequel run - --data orders=examples/spec/orders.csv

# step through a pipeline: show the relation after stage 4
unsequel preview query.unsequel --stage 4 --limit 5

# inspect the generated SQL
unsequel compile query.unsequel --stage 4

# non-comma CSV with an explicit type override
unsequel run query.unsequel --delimiter ';' --column-type orders.postal_code=text

# JSON output
unsequel run query.unsequel --format json

REPL commands

Command	Meaning
`.run`	Execute the query being typed now.
`.load name=path`	Load a CSV/JSON/Parquet file as a table.
`.sources`	List loaded sources.
`.schema [path]`	Show or set an explicit schema file.
`.format table\|json\|csv`	Change the output format.
`.clear`	Discard the query being typed.
`.quit`	Exit (warns if lines are pending).