Reference: hsql CLI
This page is generated from hsql --spec with no adapters loaded, in Harlequin’s repository, and published
with the release it describes.
It does not cover any adapter’s connection options. Four commands answer that, and none of them connects to a database:
$ hsql --help
hsql --help -a postgres
hsql --spec
hsql --info--help is this list for a person, --help -a NAME adds one adapter’s options
to it, and --spec is the whole surface as JSON. --info describes the
installation: versions, config files, the active profile, and what each adapter
supports.
What the options are for is on the other pages under The hsql CLI.
Generated from hsql 2.15.0, and served verbatim at harlequin.sh/artifacts/hsql-reference.md.
hsql
Execute SQL and exit.
CONN_STR: one or more connection strings, or paths to local db files.
Generated from the bare hsql command, with no adapters loaded. An adapter
contributes its own options on top of these: hsql --help -a NAME shows one
adapter’s, and hsql --spec reports every installed adapter’s as JSON.
Usage
hsql [OPTIONS] [CONN_STR]...Arguments
| Argument | Type | Accepts |
|---|---|---|
CONN_STR | text | zero or more |
Options
Alphabetical by name. Flags are off by default.
| Option | Type | Values | Default | Env var | Description |
|---|---|---|---|---|---|
-a, --adapter | choice | NAME | duckdb | The installed adapter plug-in to connect with. | |
--catalog | boolean | List the catalog objects one level below --path, and exit without running SQL. | |||
--catalog-search | text | TERM | Search the whole catalog, at every level, for objects whose name contains TERM, and exit without running SQL. Not every adapter can; see --info. | ||
--color | choice | auto, always, never | never | Color text output. auto follows the terminal and NO_COLOR. | |
-c, --command | text | Execute SQL. Repeatable. | |||
--config | choice | show, list-profiles, validate, schema, init | Report on the config files hsql found, or write a profile into one, and exit without running SQL. One of: show, list-profiles, validate, schema, init. | ||
--config-path | path | PATH | HARLEQUIN_CONFIG_PATH | Use this config file instead of the ones hsql discovers. | |
--csv | boolean | Shorthand for --format csv. | |||
--display-rows | integer | N | Rows printed per result set by the text layouts. -1 for all rows. [default: 40 for table, markdown, md; 10 for vertical] | ||
-f, --file | text | PATH | Execute SQL from a file, or from stdin for -. Repeatable. | ||
--format | choice | table, markdown, md, vertical, csv, tsv, json, jsonl, ndjson, parquet, orc, feather, arrow, none | table | Output format. See below for the list. | |
--help | boolean | Show this message and exit. | |||
--history | boolean | List the queries harlequin and hsql have run, newest first, and exit without running SQL. --limit says how many; -P, -a or a CONN_STR narrows it to one database. | |||
--history-search | text | TERM | List the logged queries whose SQL contains TERM, newest first, and exit without running SQL. Scoped like --history. | ||
--idle-timeout | number | SECONDS | 1800.0 | With --serve: stop the session once it has gone SECONDS with no request. 0 for a session that waits as long as it takes. | |
--info | boolean | Versions, config files, the active profile, and what each installed adapter declares it supports, as JSON. Connects to nothing. -a narrows it to one adapter. | |||
--json | boolean | Shorthand for --format json. | |||
--jsonl | boolean | Shorthand for --format jsonl. | |||
--limit | integer | N | 500 | Maximum rows fetched per result set. -1 for no limit. | |
--markdown | boolean | Shorthand for --format markdown. | |||
--max-lifetime | number | SECONDS | 28800.0 | With --serve: stop the session SECONDS after it connected, whatever it is doing; a request already running finishes first. 0 for a session that runs until something stops it. | |
-A, --no-align | boolean | Unaligned output. As in psql. | |||
--no-footer | boolean | Omit the row-count footer, keeping other chrome. | |||
--no-header | boolean | Omit the header row, keeping other chrome. | |||
--no-write-history | boolean | Do not record this run’s queries in the query history that Harlequin and hsql share. | |||
--null-string | text | TEXT | Render NULL as TEXT. Defaults to NULL for text formats, empty for csv. | ||
--on-error | choice | stop, continue | stop | What to do when a statement fails. | |
-o, --output | text | PATH | Write results to PATH instead of stdout. Accepts a file or directory. | ||
--path | text | TEXT | Where in the catalog --catalog looks, and what --catalog-search searches under. Dotted segments, named by the adapter; the top of the catalog by default. A trailing * filters a --catalog listing. | ||
-P, --profile | text | Load a profile from an available config file. Options passed here take precedence over the profile’s. Use the profile named None for Harlequin’s defaults instead of the config file’s default profile. | |||
--queue-timeout | number | SECONDS | With --serve: a request waits at most SECONDS for the one before it, then exits 4 without reaching the database. [default: no limit] | ||
-r, --read-only | boolean | Connect read-only, and refuse to run at all if the adapter cannot. To check an adapter’s capabilities, use --info. | |||
--result | text | all\|last\|N | all | Which result set(s) to emit. | |
--serve | text | NAME | Connect, then hold the connection open as the session named NAME and answer --session NAME invocations from it until stopped. Takes connection and session-lifetime options; no per-request ones. Not on native Windows. | ||
--session | text | NAME | Send this invocation to the running session named NAME, started with --serve. HSQL_SESSION=NAME does the same for every invocation, and runs without the session, with a warning, when none is up. | ||
--session-reset | boolean | Ask the session to close its connection and open a fresh one, and exit without running SQL. Temp tables, settings and an open transaction are gone. Needs --session. | |||
--session-status | boolean | Poll the server for its status as JSON, and exit. Reports while a query is running. Needs --session. | |||
--skill | boolean | Write the Agent Skill for driving hsql, as markdown. -o installs it: ‘hsql --skill -o ~/.claude/skills/hsql/‘. | |||
--spec | boolean | Every option here, plus every installed adapter’s, as JSON. -a narrows it to one adapter. | |||
--ssh-allow-reuse | boolean | When the local port is already bound, warn and connect through the listener that has it instead of failing. | |||
--ssh-batch-mode | boolean | Fail rather than prompt for a passphrase, a password or a host key. ssh’s own BatchMode; set it in scripts, CI and cron. | |||
--ssh-forward | text | TEXT | A local forward, spelled as ssh -L takes one: LOCAL:HOST:REMOTE. Repeatable. Omit it when your ssh config has the LocalForward. | ||
--ssh-host | text | TEXT | Open an SSH tunnel to this destination first, and connect through it. A Host alias, host, user@host or ssh://user@host:port, passed to ssh verbatim. | ||
--ssh-timeout | number | SECONDS | Seconds to wait for the tunnel’s forwards. [default: 60] | ||
--stats | boolean | Write a one-line JSON summary to stderr. | |||
--timeout | number | SECONDS | Cancel the run after SECONDS and exit 4. Refused if the adapter cannot cancel a query; to check, use --info. | ||
-t, --tuples-only | boolean | Rows only: no header, no footer. As in psql. | |||
--version | boolean | Show the version and exit. | |||
-x, --vertical | boolean | Shorthand for --format vertical. As in psql. |
-a/--adapter names an installed adapter plug-in. hsql --info reports
adapters installed in your environment.
Formats
--format takes one of these names, which affect the layout of data in stdout.
Modify output further with options above (e.g., -t, -A, --display-rows). none runs the SQL but generates no output. The suffix is what -o DIRECTORY names a file with.
| Format | Kind | Suffix | Holds several result sets |
|---|---|---|---|
table | text layout | .txt | yes |
markdown | text layout | .md | yes |
md | text layout | .md | yes |
vertical | text layout | .txt | yes |
csv | file | .csv | no |
tsv | file | .tsv | no |
json | file | .json | no |
jsonl | file | .jsonl | yes |
ndjson | file | .ndjson | yes |
parquet | file | .parquet | no |
orc | file | .orc | no |
feather | file | .feather | no |
arrow | file | .arrow | no |
none | writes nothing | yes |
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | The database rejected the SQL. |
2 | A bad flag, a bad profile, or a config file hsql could not read. |
3 | hsql could not connect. |
4 | --timeout ran out, and hsql stopped the run. |
70 | hsql hit a bug in itself and wrote a crash report. |
130 | Interrupted. |