CLI Reference

Command-line reference for the heliosdb-nano binary (current release). Run heliosdb-nano --help or heliosdb-nano <command> --help for the authoritative list of flags for the binary you have installed.

Overview
Global Options
Commands
- start
- stop
- status
- init
- repl
- dump
- restore
Common Use Cases
Exit Codes
Environment Variables

Overview

The heliosdb-nano command-line interface provides commands for:

Starting and stopping the database server (in-memory or persistent)
An interactive SQL shell (REPL) on an embedded database
Dumping and restoring a data directory

Installation:

# Resolve the latest release tag; pin a specific tag (VER=vX.Y.Z) in production
VER=$(curl -sSfL -o /dev/null -w '%{url_effective}' https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest | sed 's#.*/tag/##')
curl -sSfL -O "https://github.com/HeliosDatabase/HeliosDB-Nano/releases/download/$VER/heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
tar xzf "heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
sudo mv heliosdb-nano /usr/local/bin/

# Verify installation
heliosdb-nano --version

Archives for Linux (x86_64 / aarch64), macOS (arm64) and Windows (x86_64), plus SHA256SUMS, are on the GitHub Releases page. See Installation for other channels.

Global Options

Only these options apply before any command:

Option	Description
`-h`, `--help`	Show help (also works after a command: `heliosdb-nano start --help`)
`-V`, `--version`	Show the version

There are no global --config, --log-level or --log-format options. The configuration file is passed to start with --config, and logging is controlled with the RUST_LOG environment variable (default warn):

# Debug logging
RUST_LOG=debug heliosdb-nano start --data-dir ./mydb

# Per-module filters use the standard tracing EnvFilter syntax
RUST_LOG=info,heliosdb_nano=debug heliosdb-nano start --data-dir ./mydb

Commands

`start` Command

Start the database server (in-memory or persistent mode).

Synopsis

heliosdb-nano start [OPTIONS]

Options

Option	Description	Default
`-d`, `--data-dir <PATH>`	Persistent data directory (required unless `--memory`)	-
`-m`, `--memory`	Run in pure in-memory mode	`false`
`-p`, `--port <PORT>`	PostgreSQL port to listen on	`5432`
`--listen <ADDR>`	Listen address	`127.0.0.1`
`-c`, `--config <PATH>`	Configuration file (TOML)	-
`--daemon`	Run in the background	`false`
`--pid-file <PATH>`	PID file (with `--daemon`)	`./heliosdb.pid`
`--dump-on-shutdown`	Dump on shutdown (in-memory mode)	`false`
`--dump-schedule <CRON>`	Cron schedule for automatic dumps, e.g. `"0 /6 * *"`	-
`--tls-cert <PATH>`	TLS certificate (PEM)	-
`--tls-key <PATH>`	TLS private key (PEM)	-
`--tls-post-quantum <BOOL>`	Offer the X25519MLKEM768 hybrid key exchange on the PostgreSQL TLS listener	`true`
`--auth <METHOD>`	`trust`, `password`, `md5` or `scram-sha-256`	`trust`
`--password <PASS>`	Password (required for `password`/`md5`/`scram-sha-256`)	-
`--max-connections <N>`	Max concurrent connections per listener	`100`
`--max-connections-warn-percent <PERCENT>`	Log a warning when a listener reaches this share of `--max-connections` (`0` disables)	`80`
`--join-memory-limit-mb <MB>`	Memory a single join may materialize before the query is refused	`1024`
`--pg-socket-dir <DIR>`	Also listen on a PostgreSQL Unix socket in `<DIR>`	-
`--http-port <PORT>`	HTTP API port for health checks (`0` disables)	`8080`
`--http-listen <ADDR>`	HTTP API listen address	value of `--listen`
`--mcp-token <TOKEN>`	Bearer token for MCP-over-HTTP routes (`mcp-endpoint` builds)	-
`--allow-remote-mcp`	Mount MCP routes on a non-loopback listener without auth (unsafe)	`false`

Non-loopback listeners need an authentication method other than trust (for example --auth scram-sha-256 --password <secret>).

MySQL Protocol Options

Option	Description	Default
`--mysql`	Enable the MySQL protocol listener	`false`
`--mysql-listen <ADDR:PORT>`	MySQL listen address	`127.0.0.1:3306`
`--mysql-socket <PATH>`	MySQL Unix socket path	-
`--mysql-tls-cert <PATH>` / `--mysql-tls-key <PATH>`	TLS for the MySQL TCP listener (both required)	-
`--mysql-tls-post-quantum <BOOL>`	Hybrid post-quantum key exchange on the MySQL TLS listener	`true`

Connection Lifetime Options

PostgreSQL duration syntax (30s, 5min, …) is accepted.

Option	Description	Default
`--authentication-timeout <DURATION>`	Bound on the whole client handshake; bare integer = seconds	`60s`
`--idle-session-timeout <DURATION>`	Close sessions idle outside a transaction; bare integer = ms	`0` (disabled)
`--idle-in-transaction-session-timeout <DURATION>`	Close sessions idle inside a transaction; bare integer = ms	`0` (disabled)
`--tcp-keepalives-idle <DURATION>`	Seconds before the first keepalive probe	`0` (OS default)
`--tcp-keepalives-interval <DURATION>`	Seconds between keepalive probes	`0` (OS default)
`--tcp-keepalives-count <N>`	Probes before a connection is declared dead	`0` (OS default)

HA Replication Options

Option	Description	Default
`--replication-role <ROLE>`	`standalone`, `primary`, `standby`, `observer`	`standalone`
`--replication-port <PORT>`	Port for WAL streaming	`5433`
`--primary-host <HOST:PORT>`	Primary for standbys to connect to	-
`--standby-hosts <HOSTS>`	Comma-separated standby hosts (primary)	-
`--observer-hosts <HOSTS>`	Comma-separated observer hosts for split-brain protection	-
`--sync-mode <MODE>`	`async`, `semi-sync`, `sync`	`async`
`--node-id <UUID>`	Node identifier	auto-generated

Examples

1. In-Memory Server (Development)

# Start on the default port (5432)
heliosdb-nano start --memory

# Custom port
heliosdb-nano start --memory --port 5433

2. Persistent Server (Production)

heliosdb-nano start --data-dir /var/lib/heliosdb

# Listen on all interfaces (requires a non-trust auth method)
heliosdb-nano start \
    --data-dir /var/lib/heliosdb \
    --listen 0.0.0.0 --port 5432 \
    --auth scram-sha-256 --password "$HELIOS_PASSWORD" \
    --max-connections 200

3. Daemon Mode

heliosdb-nano start --data-dir /var/lib/heliosdb --daemon --pid-file /run/heliosdb.pid
heliosdb-nano status --pid-file /run/heliosdb.pid
heliosdb-nano stop --pid-file /run/heliosdb.pid

4. In-Memory with Dumps

heliosdb-nano start --memory --dump-on-shutdown
heliosdb-nano start --memory --dump-schedule "0 */6 * * *"

5. High Availability

# Primary with two standbys
heliosdb-nano start --data-dir /var/lib/heliosdb \
    --replication-role primary \
    --replication-port 5433 \
    --standby-hosts standby1.example.com:5433,standby2.example.com:5433 \
    --sync-mode semi-sync

# Standby
heliosdb-nano start --data-dir /var/lib/heliosdb \
    --replication-role standby \
    --primary-host primary.example.com:5433

See High Availability for details.

6. MySQL Protocol

heliosdb-nano start --data-dir ./mydb --mysql --mysql-listen 127.0.0.1:3306

7. With a Configuration File

heliosdb-nano start --config heliosdb.toml --data-dir /var/lib/heliosdb

Command-line flags take precedence over the configuration file. See the Configuration Reference.

`stop` Command

Stop a server started with --daemon, using its PID file.

heliosdb-nano stop [--pid-file <PATH>]   # default ./heliosdb.pid

`status` Command

Report whether the daemon recorded in the PID file is running.

heliosdb-nano status [--pid-file <PATH>]   # default ./heliosdb.pid

# Output when running:
# Status: RUNNING
#   PID: 12345
#   PID file: ./heliosdb.pid

For database-level statistics, connect with psql and query the system views (for example SELECT * FROM pg_stat_activity).

`init` Command

Create and initialize a new data directory.

heliosdb-nano init [DATA_DIR]   # default ./heliosdb-data

`repl` Command

Interactive SQL shell on an embedded database (no server required).

Synopsis

heliosdb-nano repl [OPTIONS]

Options

Option	Description	Default
`-d`, `--data-dir <PATH>`	Data directory	`./heliosdb-data`
`-m`, `--memory`	Use an in-memory database	`false`
`--dump-on-shutdown`	Dump when exiting (in-memory mode)	`false`
`--dump-file <PATH>`	Dump output file	`heliosdb_dump.heliodump`

The REPL has no --execute option. To run SQL non-interactively, start a server and use psql -c "..." (or any PostgreSQL client).

Examples

heliosdb-nano repl --memory
heliosdb-nano repl --data-dir ./mydb
heliosdb-nano repl --memory --dump-on-shutdown --dump-file backup.heliodump

REPL Meta-Commands

Command	Description
`\h`, `\help`, `\?`	Show help
`\q`, `\quit`, `\exit`	Quit
`\d`	List tables
`\d <table>`	Describe a table
`\dt`	List tables with details
`\dS [view]`	List / describe system views
`\timing`	Toggle query timing
`\branches`	List database branches
`\snapshots`	List time-travel snapshots
`\dmv [view]`	List / describe materialized views
`\compression [table]`	Compression statistics
`\set [var value]`	Show or set variables
`\indexes <table>`	List indexes on a table
`\stats`	Database statistics

Type \h in the REPL for the full list (server, user, AI, tenant and vector commands).

`dump` Command

Export a data directory to a dump file.

Synopsis

heliosdb-nano dump [OPTIONS]

Options

Option	Description	Default
`-o`, `--output <PATH>`	Output dump file	`backup.heliodump`
`-d`, `--data-dir <PATH>`	Data directory to dump	- (required)
`-a`, `--append`	Append incremental changes to an existing dump	`false`
`--compression <TYPE>`	`zstd`, `gzip`, `brotli` or `none`	`zstd`
`--connection <STRING>`	Server-mode dump — not yet implemented, the command exits with an error	-
`-v`, `--verbose`	Verbose output	`false`

There are no --host/--port/--user, --tables, --compression-level or --dry-run options. Dump an embedded data directory (stop the server, or use a copy), or use start --dump-schedule for scheduled dumps of a running server.

Examples

# Full dump
heliosdb-nano dump --data-dir ./mydb --output backup.heliodump

# Incremental dump appended to an existing file
heliosdb-nano dump --data-dir ./mydb --output backup.heliodump --append

# Uncompressed
heliosdb-nano dump --data-dir ./mydb --output backup.heliodump --compression none

`restore` Command

Restore a dump file into a data directory.

Synopsis

heliosdb-nano restore [OPTIONS] --input <PATH>

Options

Option	Description	Default
`-i`, `--input <PATH>`	Dump file to restore	- (required)
`-t`, `--target <PATH>`	Target data directory (created if missing)	`./heliosdb-data-restored`
`--verify`	Verify dump integrity before restoring	`false`
`--no-validate`	Restore even if rows violate the dump’s constraints, reporting each as a warning	`false`
`--connection <STRING>`	Server-mode restore — not yet implemented	-
`-v`, `--verbose`	Verbose output	`false`

There are no --mode, --on-conflict, --tables, --dry-run or --host/--port/--user options.

Examples

heliosdb-nano restore --input backup.heliodump --target ./restored-db --verify
heliosdb-nano start --data-dir ./restored-db

Common Use Cases

Development Workflow

heliosdb-nano repl --data-dir ./devdb
# heliosdb> CREATE TABLE users (id INT PRIMARY KEY, name TEXT);
# heliosdb> \q
heliosdb-nano dump --data-dir ./devdb --output testdata.heliodump
heliosdb-nano restore --input testdata.heliodump --target ./testdb

Production Deployment

# 1. Start the server, with a nightly scheduled dump
heliosdb-nano start --data-dir /var/lib/heliosdb --daemon --pid-file /run/heliosdb.pid \
    --listen 0.0.0.0 --auth scram-sha-256 --password "$HELIOS_PASSWORD" \
    --dump-schedule "0 2 * * *"

# 2. Or take a cold dump while the server is stopped
heliosdb-nano dump --data-dir /var/lib/heliosdb --output /backups/heliosdb-$(date +%Y%m%d).heliodump

# 3. Check the daemon
heliosdb-nano status --pid-file /run/heliosdb.pid

# 4. Graceful restart
heliosdb-nano stop --pid-file /run/heliosdb.pid
heliosdb-nano start --data-dir /var/lib/heliosdb --daemon --pid-file /run/heliosdb.pid

Disaster Recovery

heliosdb-nano restore --input latest.heliodump --target /var/lib/heliosdb --verify
heliosdb-nano start --data-dir /var/lib/heliosdb
psql -h localhost -c "SELECT COUNT(*) FROM users"

Exit Codes

Code	Meaning
`0`	Success
`1`	The command failed (the error is printed to stderr)
`2`	Invalid command-line arguments

#!/bin/bash
if heliosdb-nano dump --data-dir /var/lib/heliosdb --output backup.heliodump; then
    echo "Backup successful"
else
    echo "Backup failed" >&2
    exit 1
fi

Environment Variables

Variable	Description	Default
`RUST_LOG`	Log filter (`error`, `warn`, `info`, `debug`, `trace`, or per-module)	`warn`
`HELIOSDB_HASH_JOIN_MEM_MB`	Overrides `--join-memory-limit-mb` and the config file	-

Ports, data directory and credentials are set with command-line flags or the configuration file, not with HELIOSDB_* environment variables.

CLI Reference

Table of Contents

Overview

Global Options

Commands

`start` Command

Synopsis

Options

MySQL Protocol Options

Connection Lifetime Options

HA Replication Options

Examples

`stop` Command

`status` Command

`init` Command

`repl` Command

Synopsis

Options

Examples

REPL Meta-Commands

`dump` Command

Synopsis

Options

Examples

`restore` Command

Synopsis

Options

Examples

Common Use Cases

Development Workflow

Production Deployment

Disaster Recovery

Exit Codes

Environment Variables

See Also

CLI Reference

Table of Contents

Overview

Global Options

Commands

start Command

Synopsis

Options

MySQL Protocol Options

Connection Lifetime Options

HA Replication Options

Examples

stop Command

status Command

init Command

repl Command

Synopsis

Options

Examples

REPL Meta-Commands

dump Command

Synopsis

Options

Examples

restore Command

Synopsis

Options

Examples

Common Use Cases

Development Workflow

Production Deployment

Disaster Recovery

Exit Codes

Environment Variables

See Also

`start` Command

`stop` Command

`status` Command

`init` Command

`repl` Command

`dump` Command

`restore` Command