<!-- Generated by scripts/write_cli_reference.py. Do not edit by hand. -->

# 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. |
| `--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. |
| `-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. |
| `--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. |
| `-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. |
| `--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. |
| `130` | Interrupted. |