Get started.

01 / Install

One executable.

brew install yhay81/tap/sqrail
sqrail --version
sqrail --help
man sqrail

Prebuilt archives for Linux, macOS, and Windows are available on GitHub Releases →

02 / Agent Skill

Let the agent find it.

Install the optional public Agent Skill with GitHub CLI 2.90 or newer. It teaches an agent when to choose sqrail and tells it to read the executable's current help before acting.

gh skill preview yhay81/sqrail sqrail
gh skill install yhay81/sqrail sqrail \
  --agent codex --scope user

Replace codex with the current host, such as claude-code, cursor, or github-copilot. AGY/Antigravity CLI uses agy plugin install https://github.com/yhay81/sqrail. An end-to-end flow is available in the Agent setup guide → Agents can fetch the same instructions as plain Markdown →

03 / First query

SQL already is the interface.

Bind each input to an explicit table name with -t. Send SQL on stdin when it is long enough to make shell quoting awkward.

sqrail run \
  -t sales=sales.csv \
  -t drugs=drugs.parquet \
  -o result.parquet \
  - <<'SQL'
SELECT d.name, sum(s.amount) AS total
FROM sales AS s
JOIN drugs AS d USING (drug_id)
GROUP BY d.name
ORDER BY total DESC
SQL

04 / Three verbs

Inspect only when needed.

schema — discover names and types

sqrail schema trials.parquet

check — validate without executing

sqrail check -t trials=trials.parquet - < query.sql

run — execute once

sqrail run -t trials=trials.parquet - < query.sql

If names and types are already stated, skip discovery. Run once and stop after success. This explicit decision rule is part of --help.

05 / Boundaries

Make resource use explicit.

sqrail run \
  -t events=events.parquet \
  --memory 512MB \
  --threads 2 \
  --timeout 30s \
  --max-rows 100000 \
  --max-output-bytes 64MB \
  --max-input-files 32 \
  --stats \
  - < query.sql

Limits fail closed. Successful rows stay on stdout; versioned success statistics and single-object JSON errors stay on stderr. Existing outputs are never overwritten, and failed queries leave no partial destination.

06 / File formats

Local files, named precisely.

Multi-file inputs union evolving columns by name. --strict-schema instead requires identical names, order, and types.

07 / Reference

Follow the contract.
Audit the evidence.