CLI reference

The CLI guide shows these in use. Both listings below are generated from the client built from Hardcharger™’s main branch (hardcharger --help, and .help in a session), and CI fails when they drift.

Options

hardcharger --help

Usage: hardcharger [OPTIONS] [URI]

Examples:
  hardcharger --username admin             localhost:31337, over TLS (the default)
  hardcharger --no-tls --username admin    a server without TLS (plain HTTP)
  hardcharger hardcharger://db.example.com:31337 --username admin -c "SELECT 1"

Hardcharger Client Options

Connection:
  -h, --host HOST               Server host (default: localhost; env: HARDCHARGER_HOST)
  -p, --port PORT               Server port (default: 31337; env: HARDCHARGER_PORT)
  -u, --username USER           Username (env: HARDCHARGER_USER, falls back to HARDCHARGER_ADMIN_USERNAME for parity with the server)
  -W, --password                Force a password prompt (else env: HARDCHARGER_PASSWORD, or a prompt)
      --uri URI                 Connection URI: hardcharger://HOST[:PORT][/PREFIX][?tls=false], HTTPS unless it says ?tls=false, port 31337 by default; also warp://, https:// and http:// (also the one positional argument; not with --host, --port or --tls)

TLS:
      --tls[=BOOL]              TLS (HTTPS), on by default; --no-tls (or --tls=false, --tls false) for plain HTTP to a server without TLS (env: HARDCHARGER_TLS=false; in a URI, ?tls=false)
      --tls-roots FILE          Trusted root certificates (PEM; default: the system's) (env: HARDCHARGER_TLS_ROOTS)
      --tls-skip-verify         Skip TLS server certificate verification (development only)
      --mtls-cert FILE          mTLS client certificate (PEM)
      --mtls-key FILE           mTLS client private key (PEM)

Sign-in:
      --auth-type TYPE          'password' (default), 'external' (the server's browser sign-in, OAuth/SSO) or 'mtls' (the --mtls-cert client certificate is the credential; no password)

Input and output:
  -c, --command SQL             Execute SQL (and dot commands) and exit
  -f, --file FILE               Execute SQL from FILE and exit
  -o, --output FILE             Write output to FILE
      --init FILE               Init file to execute on startup (default: ~/.hardchargerrc)
      --no-init                 Do not execute the init file

Tags:
      --session-tag JSON        Session tag sent after connecting (env: HARDCHARGER_SESSION_TAG)
      --query-tag JSON          Query tag sent after connecting (env: HARDCHARGER_QUERY_TAG)
      --result-partitions N     Read large results in up to N partitions at once, over N connections (env: HARDCHARGER_RESULT_PARTITIONS; default 8; 1: one stream)

Output modes:
      --csv                     Set output mode to CSV
      --json                    Set output mode to JSON
      --table                   Set output mode to table (ASCII borders)
      --box                     Set output mode to box (Unicode borders, default)
      --markdown                Set output mode to markdown
      --no-header               Disable column headers

Display:
  -q, --quiet                   Suppress the welcome banner and informational messages
  -e, --echo                    Echo executed SQL statements
      --bail                    Stop on first error
      --null TEXT               String to display for NULL values (default: NULL)

Other:
  -?, --help                    Show this help message
  -v, --version                 Show version
      --licenses                Show the third-party software in this program and their licences

Dot commands

.help

.about                         Show version, copyright, and project info
.bail on|off                   Stop on error. Default: off
.catalogs                      List all catalogs
.cd DIR                        Change working directory
.connect URI | HOST PORT USER  Connect to a Hardcharger server (HOST PORT USER
                               --no-tls: without TLS)
.describe TABLE                Show table column names and types
.echo on|off                   Echo input commands. Default: off
.exit                          Exit this program (same as .quit)
.export_last [FILE]            Export last result to Arrow IPC file
.headers on|off                Toggle column headers. Default: on
.help [PATTERN]                Show this help or commands matching PATTERN
.highlight on|off              Toggle syntax highlighting. Default: on
.last                          Re-display last query result
.maxrows [N]                   Show or set max rows displayed (0=unlimited)
.maxwidth [N]                  Show or set max width (0=auto from terminal)
.mode MODE                     Set output mode (box table csv json markdown ...)
.nullvalue STRING              Set string for NULL values. Default: "NULL"
.once FILE                     Redirect next query output to FILE
.output [FILE]                 Redirect output to FILE or stdout
.pager on|off|N                Toggle pager or set row threshold. Default: on/50
.prompt MAIN [CONT]            Set prompt strings
.quit                          Exit this program
.read FILE                     Execute SQL from FILE
.refresh                       Refresh tab-completion schema cache
.schema [PATTERN]              Show database schemas
.separator COL [ROW]           Set separators for list/csv mode
.shell CMD...                  Execute CMD in system shell
.show                          Show current settings
.tables [PATTERN] [--flat]     List tables (tree view, or --flat)
.timer on|off                  Show query execution time. Default: off

Environment

Variable	Meaning
HARDCHARGER_HOST, HARDCHARGER_PORT	Server address
HARDCHARGER_USER	User name (falls back to HARDCHARGER_ADMIN_USERNAME)
HARDCHARGER_PASSWORD	The user’s password (never the server’s HARDCHARGER_ADMIN_PASSWORD)
HARDCHARGER_TLS, HARDCHARGER_TLS_ROOTS	TLS on; trusted roots
HARDCHARGER_SESSION_TAG, HARDCHARGER_QUERY_TAG	Tags
HARDCHARGER_RESULT_PARTITIONS	Partitioned reads
HARDCHARGER_BROWSER	The command that opens the browser for --auth-type external (browser sign-in)

Files

File
~/.hardchargerrc	Run at startup (--init, --no-init)
~/.hardcharger_history	Shell history
~/.hardcharger_last_result.arrow	.export_last’s default

Exit status

0 when everything ran, 1 when a statement or dot command failed, 130 when Ctrl-C stopped a script between statements.