CLI Reference

HeliosDB Lite is one binary, heliosdb-lite. Run heliosdb-lite --help or heliosdb-lite <command> --help to print the flags your build accepts.

Command	Purpose
start	Start the server (PostgreSQL wire protocol plus the REST API)
stop	Stop a server started with --daemon
status	Report whether a daemonised server is running
init	Create an empty database directory
repl	Open the interactive SQL shell on an embedded database
dump	Write a database to a dump file
restore	Load a dump file into a database
skills	Install the bundled agent skills catalog

start

HELIOSDB_JWT_SECRET=<secret> heliosdb-lite start (--data-dir <PATH> | --memory) [OPTIONS]

start needs either --data-dir or --memory. It serves the PostgreSQL wire protocol on the main port and the REST API on the HTTP port.

The REST API signs and verifies tokens with HELIOSDB_JWT_SECRET. The server refuses to start when that variable is unset or empty, so export it first:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./mydb

Flag	Description	Default
-d, --data-dir <PATH>	Data directory (required unless --memory is used)	none
-m, --memory	Run with an in-memory store	off
-p, --port <PORT>	PostgreSQL wire port (overrides [server].port)	5432
--listen <ADDR>	Listen address (overrides [server].listen_addr)	127.0.0.1
-c, --config <PATH>	Configuration file	none
--daemon	Run the server in the background	off
--pid-file <PATH>	PID file, used with --daemon	./heliosdb.pid
--dump-on-shutdown	Write a dump when an in-memory server shuts down	off
--dump-schedule <CRON>	Periodic dump schedule. Planned: the flag is accepted but not yet acted on	none
--tls-cert <PATH>	TLS certificate (PEM); requires --tls-key	none
--tls-key <PATH>	TLS private key (PEM); requires --tls-cert	none
--auth <METHOD>	trust, password, md5 or scram-sha-256	trust
--password <PASS>	Password, required by every method except trust	none
-v, --verbose	Debug logging (unless RUST_LOG is set)	off

--auth trust accepts every connection without a password and is meant for local development. For anything reachable from another host, use --auth scram-sha-256 --password ... and keep --listen on 127.0.0.1 unless clients must connect from elsewhere.

Replication flags

Replication needs a binary built with cargo build --release --features ha-tier1; other builds refuse to start with any role except standalone.

Flag	Description	Default
--replication-role <ROLE>	standalone, primary, standby or observer (the observer role starts no service yet; observer-based split-brain protection is planned)	standalone
--replication-port <PORT>	WAL streaming port	5433
--primary-host <HOST:PORT>	Primary that a standby connects to	none
--standby-hosts <LIST>	Accepted and printed at startup; standbys connect to the primary without it	none
--observer-hosts <LIST>	Accepted; observer-based split-brain protection is planned	none
--sync-mode <MODE>	async, semi-sync or sync	async
--http-port <PORT>	HTTP port for the REST API and health checks	8080
--node-id <UUID>	Node identifier, generated when omitted	generated
--replication-tls <BOOL>	Encrypt WAL replication traffic	on when --tls-cert is set

Examples

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Persistent server on the default ports (5432 and 8080), loopback only
heliosdb-lite start --data-dir /var/lib/heliosdb

# Password authentication and TLS, reachable from other hosts
heliosdb-lite start --data-dir /var/lib/heliosdb \
  --listen 0.0.0.0 \
  --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD" \
  --tls-cert server.crt --tls-key server.key

# In-memory server that writes a dump on shutdown
heliosdb-lite start --memory --dump-on-shutdown

# Background server
heliosdb-lite start --data-dir /var/lib/heliosdb --daemon --pid-file /var/run/heliosdb.pid

Primary and standby:

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"

# Primary
heliosdb-lite start --data-dir /var/lib/heliosdb \
  --replication-role primary --replication-port 5433 \
  --standby-hosts standby1.example.com:5433 --sync-mode semi-sync

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

See High Availability for the replication model.

stop

heliosdb-lite stop [--pid-file <PATH>]

Stops the server whose PID is in the PID file (default ./heliosdb.pid). The command asks the process to shut down and, if it is still running after the grace period, kills it.

status

heliosdb-lite status [--pid-file <PATH>]

Prints Status: RUNNING with the PID, or Status: NOT RUNNING when the PID file is missing or the process is gone.

init

heliosdb-lite init [DATA_DIR]

Creates an empty database in DATA_DIR (default ./heliosdb-data).

repl

heliosdb-lite repl [--data-dir <PATH> | --memory] [OPTIONS]

Flag	Description	Default
-d, --data-dir <PATH>	Data directory	./heliosdb-data
-m, --memory	Use an in-memory database	off
--dump-on-shutdown	Write a dump when an in-memory session exits	off
--dump-file <PATH>	Dump file used with --dump-on-shutdown	none

Inside the shell, \h lists the meta-commands; see REPL Commands.

dump

heliosdb-lite dump (--data-dir <PATH> | --connection <CONN>) [OPTIONS]

Flag	Description	Default
-o, --output <PATH>	Dump file	backup.heliodump
-d, --data-dir <PATH>	Dump an embedded database directory	none
--connection <CONN>	Dump a running server through its PostgreSQL port (PostgreSQL connection string)	none
-a, --append	Append incremental changes to an existing dump	off
--compression <TYPE>	zstd, gzip, brotli or none	zstd
--tables <LIST>	Comma-separated tables to include (embedded mode only)	all
--tls	Encrypt the server connection; requires --tls-ca	off
--tls-ca <PATH>	CA certificate (PEM) that signed the server certificate	none
-v, --verbose	Progress output	off

# Embedded database directory
heliosdb-lite dump --data-dir ./mydb --output backup.heliodump

# Selected tables
heliosdb-lite dump --data-dir ./mydb --output users.heliodump --tables users,sessions

# Running server, over TLS
heliosdb-lite dump --connection "host=db.example.com port=5432 user=postgres" \
  --tls --tls-ca ca.crt --output remote.heliodump

restore

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

Flag	Description	Default
-i, --input <PATH>	Dump file to load	required
-t, --target <PATH>	Target data directory	./heliosdb-data-restored
--verify	Check the dump’s integrity before loading it	off
--connection <CONN>	Restore into a running server through its PostgreSQL port	none
--tables <LIST>	Comma-separated tables to restore	all
--tls	Encrypt the server connection; requires --tls-ca	off
--tls-ca <PATH>	CA certificate (PEM) that signed the server certificate	none
-v, --verbose	Progress output	off

heliosdb-lite restore --input backup.heliodump --target ./mydb --verify

See Dump and Restore for workflows.

skills

heliosdb-lite skills install <TARGET> [--symlink] [--catalog claude|codex] [--force]
heliosdb-lite skills list

install copies the bundled agent skills into TARGET (for example ~/.claude/skills). --symlink links instead of copying, --catalog picks the claude (default) or codex catalog, and --force overwrites existing files. list prints the skills bundled with the binary.

Environment variables

Variable	Used by	Purpose
HELIOSDB_JWT_SECRET	start	Signing secret for REST API tokens. Required: the server will not start without it
HELIOSDB_CORS_ALLOWED_ORIGINS	start	Comma-separated origins allowed to call the REST API from a browser; when unset, cross-origin requests are denied
HELIOSDB_METRICS_KEY	start	Read-only key that unlocks /metrics and the detailed /health body
RUST_LOG	all	Log filter, for example RUST_LOG=info or RUST_LOG=debug

Checking the version

The CLI has no version subcommand. Use the \version meta-command in the REPL, or GET /version on the HTTP port of a running server:

curl http://127.0.0.1:8080/version