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.16.1, 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 name of an installed database adapter plug-in to use to connect to the database at CONN_STR. | |
--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 | By default, Harlequin finds files named .harlequin.toml in the current directory and the home directory (~) and merges them. Use this option to specify the full path to a config file at a different location. | |
--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 | path | 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 | Select a profile from an available config file to load its values. Other options passed here will take precedence over those loaded from the profile. Use the special profile named None to use Harlequin’s defaults, instead of the default profile specified in the config file. | |||
--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. | |||
--ssh-forward | text | TEXT | A local forward, spelled as ssh -L takes one: LOCAL:HOST:REMOTE. Repeat this option for more than one. Omit it when your ssh config already 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 is 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. |