CLI Reference (v3.5)¶

Version: 3.5.8 Status: Production-Ready Last Updated: 2026-01-21

Table of Contents¶

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

Overview¶

The heliosdb-lite command-line interface provides commands for: - Starting database servers (in-memory or persistent) - Interactive SQL shell (REPL) - Dumping and restoring databases - Monitoring database status

Installation:

# Download latest release
wget https://releases.heliosdb.com/v3.5.8/heliosdb-lite-linux-amd64.tar.gz
tar xzf heliosdb-lite-linux-amd64.tar.gz
sudo mv heliosdb-lite /usr/local/bin/

# Verify installation
heliosdb-lite version

Global Options¶

Available for all commands:

Option	Description	Default
`--config <PATH>`	Path to configuration file	`./config.toml`
`--log-level <LEVEL>`	Logging level (error, warn, info, debug, trace)	`info`
`--log-format <FORMAT>`	Log format (json, text)	`text`
`--help`	Show help message	-
`--version`	Show version information	-

Examples:

# Use custom config file
heliosdb-lite --config /etc/heliosdb/config.toml start --memory

# Enable debug logging
heliosdb-lite --log-level debug repl --memory

# JSON logging for production
heliosdb-lite --log-format json start --data-dir /var/lib/heliosdb

Commands¶

`start` Command¶

Start HeliosDB server (in-memory or persistent mode).

Synopsis¶

heliosdb-lite start [OPTIONS]

Options¶

Option	Description	Required	Default
`--memory`	Run in pure in-memory mode	No*	-
`--data-dir <PATH>`	Path to persistent data directory	No*	-
`--port <PORT>`	Port to listen on	No	`5432`
`--listen <ADDR>`	Bind address	No	`127.0.0.1`
`--max-connections <N>`	Maximum concurrent connections	No	`100`
`--daemon`	Run as background daemon	No	`false`
`--pid-file <PATH>`	PID file path (daemon mode)	No	`/var/run/heliosdb.pid`
`--dump-on-shutdown`	Dump database before shutdown (in-memory mode)	No	`false`
`--dump-schedule <CRON>`	Cron schedule for automatic dumps	No	-
`--tls-cert <PATH>`	TLS certificate file (PEM format)	No	-
`--tls-key <PATH>`	TLS private key file (PEM format)	No	-
`--auth <METHOD>`	Authentication method	No	`trust`
`--password <PASS>`	Password for auth methods	No	-

* Note: Either --memory or --data-dir is required.

HA Replication Options¶

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

Examples¶

1. In-Memory Server (Development)

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

# Start on custom port
heliosdb-lite start --memory --port 5433

# Listen on all interfaces
heliosdb-lite start --memory --listen 0.0.0.0 --port 5432

2. Persistent Server (Production)

# Start with persistent storage
heliosdb-lite start --data-dir /var/lib/heliosdb

# With custom settings
heliosdb-lite start \
    --data-dir /var/lib/heliosdb \
    --port 5432 \
    --listen 0.0.0.0 \
    --max-connections 200

3. Daemon Mode

# Start as background daemon
heliosdb-lite start --memory --daemon --pid-file /var/run/heliosdb.pid

# Check status
cat /var/run/heliosdb.pid
ps aux | grep heliosdb-lite

# Stop daemon
kill $(cat /var/run/heliosdb.pid)

4. In-Memory with Dump on Shutdown

# Automatically dump database when server stops
heliosdb-lite start --memory --dump-on-shutdown

# With scheduled periodic dumps (cron syntax)
heliosdb-lite start --memory --dump-schedule "0 */6 * * *"

5. High Availability Mode

# Start as primary (leader)
heliosdb-lite start --data-dir /var/lib/heliosdb \
    --replication-role primary \
    --replication-port 5433 \
    --sync-mode sync

# Start as standby (follower)
heliosdb-lite start --data-dir /var/lib/heliosdb \
    --replication-role standby \
    --primary-host primary.example.com:5433

# Start as observer (for split-brain protection)
heliosdb-lite start --data-dir /var/lib/heliosdb \
    --replication-role observer \
    --primary-host primary.example.com:5433

6. HA Cluster with Multiple Standbys

# Primary with multiple standbys
heliosdb-lite 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 \
    --http-port 8080

# Standby with custom node ID
heliosdb-lite start --data-dir /var/lib/heliosdb \
    --replication-role standby \
    --primary-host primary.example.com:5433 \
    --node-id "550e8400-e29b-41d4-a716-446655440001"

7. With Configuration File

# config.toml
cat > config.toml <<EOF
[server]
port = 5432
listen = "0.0.0.0"
max_connections = 150

[session]
timeout_secs = 3600
default_isolation_level = "READ_COMMITTED"
EOF

# Start with config
heliosdb-lite --config config.toml start --memory

Exit Behavior¶

In-Memory Mode: - On clean shutdown (SIGTERM/SIGINT), warns if dirty state exists - Prompts for dump if uncommitted changes present - Example:

WARNING: Database has 12,345 uncommitted changes.
Dump now? (y/N): y
Dumping to /tmp/shutdown-20251208-103045.heliodump...
Dump complete. Safe to exit.

Persistent Mode: - Flushes WAL and commits pending transactions - Closes RocksDB cleanly - No data loss on normal shutdown

`repl` Command¶

Start interactive SQL shell (REPL mode).

Synopsis¶

heliosdb-lite repl [OPTIONS]

Options¶

Option	Description	Required	Default
`--memory`	Use in-memory database	No	-
`--data-dir <PATH>`	Path to persistent data directory	No	`./heliosdb-data`
`--history <PATH>`	Command history file	No	`~/.heliosdb_history`
`--no-history`	Disable command history	No	`false`
`--execute <SQL>`	Execute SQL and exit	No	-
`--dump-on-shutdown`	Dump database when exiting (in-memory mode)	No	`false`
`--dump-file <PATH>`	Dump output file path	No	`dump.sql`

Note: --data-dir defaults to ./heliosdb-data when not specified. Use --memory for in-memory mode.

Examples¶

1. Interactive In-Memory REPL

# Start REPL
heliosdb-lite repl --memory

# Output:
# HeliosDB Lite v3.5.8 - Interactive SQL Shell
# Type \h for help, \q to quit
#
# heliosdb=>

2. Persistent REPL

heliosdb-lite repl --data-dir ./mydb

3. Execute Single Query

# Execute and exit
heliosdb-lite repl --memory --execute "SELECT * FROM users LIMIT 10"

# Use in scripts
RESULT=$(heliosdb-lite repl --memory --execute "SELECT COUNT(*) FROM orders")
echo "Order count: $RESULT"

4. Disable History

heliosdb-lite repl --memory --no-history

5. With Default Data Directory

# Uses ./heliosdb-data by default
heliosdb-lite repl

# Override default data directory
heliosdb-lite repl --data-dir /var/lib/myapp/db

6. Dump on Shutdown (In-Memory Mode)

# Dump to default file (dump.sql) when exiting
heliosdb-lite repl --memory --dump-on-shutdown

# Dump to custom file
heliosdb-lite repl --memory --dump-on-shutdown --dump-file backup.sql

REPL Commands¶

Once in the REPL, use these meta-commands:

Command	Description	Example
`\h`	Show help	`\h`
`\q`	Quit REPL	`\q`
`\d`	List tables	`\d`
`\d <TABLE>`	Describe table	`\d users`
`\dt`	List tables	`\dt`
`\di`	List indexes	`\di`
`\timing`	Toggle query timing	`\timing`
`\x`	Toggle expanded output	`\x`
`\dump [FILE]`	Dump database to SQL file	`\dump backup.sql`

`dump` Command¶

Export database to dump file.

Synopsis¶

heliosdb-lite dump [OPTIONS]

Options¶

Option	Description	Required	Default
`--output <PATH>`	Output dump file path	Yes	-
`--host <HOST>`	Database host	No	`localhost`
`--port <PORT>`	Database port	No	`5432`
`--user <USER>`	Database user	No	`postgres`
`--password <PASS>`	Database password	No	-
`--append`	Incremental dump (append mode)	No	`false`
`--tables <TABLES>`	Comma-separated table list	No	All tables
`--compress <TYPE>`	Compression (none, lz4, zstd)	No	`zstd`
`--compression-level <N>`	Compression level (1-22 for zstd)	No	`3`
`--verbose`	Verbose output	No	`false`
`--dry-run`	Estimate size without dumping	No	`false`

Examples¶

1. Basic Dump

# Dump entire database
heliosdb-lite dump --output backup.heliodump

# With compression
heliosdb-lite dump --output backup.heliodump --compress zstd

2. Incremental Dump

# First dump (full)
heliosdb-lite dump --output base.heliodump

# Subsequent dumps (incremental)
heliosdb-lite dump --output base.heliodump --append

3. Selective Dump

# Dump specific tables
heliosdb-lite dump --output users.heliodump --tables users,sessions

# Exclude large tables (dump others)
heliosdb-lite dump --output critical.heliodump --tables users,orders,payments

4. Remote Database Dump

# Dump remote database
heliosdb-lite dump \
    --output remote-backup.heliodump \
    --host db.example.com \
    --port 5432 \
    --user admin \
    --password secret

5. Compression Options

# No compression (fastest)
heliosdb-lite dump --output fast.heliodump --compress none

# LZ4 compression (balanced)
heliosdb-lite dump --output balanced.heliodump --compress lz4

# Maximum compression (smallest)
heliosdb-lite dump --output archive.heliodump --compress zstd --compression-level 19

6. Verbose Output

heliosdb-lite dump --output backup.heliodump --verbose

# Output:
# [2025-12-08 10:00:00] Starting dump...
# [2025-12-08 10:00:01] Dumping table 'users' (1/5)
# [2025-12-08 10:00:02]   Exported 10,000 rows (1.2 MB)
# [2025-12-08 10:00:03] Dumping table 'orders' (2/5)
# ...
# [2025-12-08 10:00:30] Dump complete: 5 tables, 250,000 rows, 45.2 MB

7. Dry Run

# Estimate dump size without creating file
heliosdb-lite dump --output /dev/null --dry-run --compress zstd

# Output:
# Estimated dump size: 2.7 GB (compressed)
# Estimated time: 120 seconds

`restore` Command¶

Restore database from dump file.

Synopsis¶

heliosdb-lite restore [OPTIONS]

Options¶

Option	Description	Required	Default
`--input <PATH>`	Input dump file path	Yes	-
`--host <HOST>`	Database host	No	`localhost`
`--port <PORT>`	Database port	No	`5432`
`--user <USER>`	Database user	No	`postgres`
`--password <PASS>`	Database password	No	-
`--mode <MODE>`	Restore mode (clean, append)	No	`clean`
`--tables <TABLES>`	Comma-separated table list	No	All tables
`--on-conflict <ACTION>`	Conflict resolution (skip, update)	No	`error`
`--verbose`	Verbose output	No	`false`
`--dry-run`	Verify without restoring	No	`false`

Examples¶

1. Basic Restore

# Restore from dump (clean mode - drops existing data)
heliosdb-lite restore --input backup.heliodump

2. Append Mode

# Add data without dropping existing tables
heliosdb-lite restore --input backup.heliodump --mode append

# Handle conflicts by skipping
heliosdb-lite restore --input backup.heliodump --mode append --on-conflict skip

# Handle conflicts by updating (upsert)
heliosdb-lite restore --input backup.heliodump --mode append --on-conflict update

3. Selective Restore

# Restore specific tables only
heliosdb-lite restore --input backup.heliodump --tables users,sessions

4. Remote Restore

# Restore to remote database
heliosdb-lite restore \
    --input backup.heliodump \
    --host db.example.com \
    --port 5432 \
    --user admin \
    --password secret

5. Dry Run (Verification)

# Verify dump without restoring
heliosdb-lite restore --input backup.heliodump --dry-run

# Output:
# Dump file: backup.heliodump
# Version: 3.5.8 (compatible)
# Created: 2025-12-08 10:00:00
# Tables: users (10,000 rows), orders (50,000 rows), products (1,000 rows)
# Total size: 12.1 MB (compressed), 45.2 MB (uncompressed)
# Estimated restore time: ~30 seconds
# Validation: PASSED

6. Verbose Output

heliosdb-lite restore --input backup.heliodump --verbose

# Output:
# [2025-12-08 11:00:00] Starting restore...
# [2025-12-08 11:00:01] Restoring table 'users'
# [2025-12-08 11:00:03]   Restored 10,000 rows
# [2025-12-08 11:00:04] Restoring table 'orders'
# [2025-12-08 11:00:08]   Restored 50,000 rows
# ...
# [2025-12-08 11:00:30] Restore complete: 3 tables, 61,000 rows

`status` Command¶

Show database status and statistics.

Synopsis¶

heliosdb-lite status [OPTIONS]

Options¶

Option	Description	Required	Default
`--host <HOST>`	Database host	No	`localhost`
`--port <PORT>`	Database port	No	`5432`
`--user <USER>`	Database user	No	`postgres`
`--format <FORMAT>`	Output format (text, json)	No	`text`

Examples¶

1. Basic Status

heliosdb-lite status

# Output:
# HeliosDB Lite v3.5.8 Status
# ================================
# Mode: In-Memory
# Uptime: 2h 15m 30s
# Active Sessions: 15
# Total Connections: 142
# Dirty State: YES (12,345 uncommitted changes)
# Memory Usage: 245 MB / 1024 MB (24%)
# Last Dump: 2025-12-08 09:00:00 (2h ago)

2. JSON Output

heliosdb-lite status --format json

# Output:
# {
#   "version": "3.5.8",
#   "mode": "in-memory",
#   "uptime_seconds": 8130,
#   "active_sessions": 15,
#   "total_connections": 142,
#   "dirty_state": true,
#   "dirty_bytes": 12345,
#   "memory_usage_bytes": 256901120,
#   "memory_limit_bytes": 1073741824,
#   "last_dump_at": "2025-12-08T09:00:00Z"
# }

3. Remote Status

heliosdb-lite status --host db.example.com --port 5432 --user admin

`version` Command¶

Show version information.

Synopsis¶

heliosdb-lite version [OPTIONS]

Options¶

Option	Description	Required	Default
`--short`	Show version number only	No	`false`
`--json`	JSON output	No	`false`

Examples¶

1. Full Version Info

heliosdb-lite version

# Output:
# HeliosDB Lite v3.5.8
# Build: 2025-12-08 (commit: abc123)
# Platform: linux-amd64
# Features: in-memory, dump/restore, multi-user, ACID
# License: Apache-2.0

2. Short Version

heliosdb-lite version --short

# Output:
# 3.5.8

3. JSON Output

heliosdb-lite version --json

# Output:
# {
#   "version": "3.5.8",
#   "build_date": "2025-12-08",
#   "commit": "abc123",
#   "platform": "linux-amd64",
#   "features": ["in-memory", "dump/restore", "multi-user", "ACID"]
# }

Common Use Cases¶

Development Workflow¶

# 1. Start in-memory REPL for testing
heliosdb-lite repl --memory

# 2. Create schema and test data
heliosdb=> CREATE TABLE users (id INT PRIMARY KEY, name TEXT);
heliosdb=> INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');

# 3. Dump test data
heliosdb=> \q
heliosdb-lite dump --output testdata.heliodump

# 4. Restore for next test run
heliosdb-lite repl --memory
heliosdb=> -- Restore via external command or in script

Production Deployment¶

# 1. Start persistent server
heliosdb-lite start --data-dir /var/lib/heliosdb --daemon

# 2. Setup automated backups (cron)
0 2 * * * heliosdb-lite dump --output /backups/daily-$(date +\%Y\%m\%d).heliodump

# 3. Monitor status
heliosdb-lite status --format json > /var/log/heliosdb-status.json

# 4. Graceful restart
kill -SIGTERM $(cat /var/run/heliosdb.pid)
# ... optionally dump before restart ...
heliosdb-lite start --data-dir /var/lib/heliosdb --daemon

Disaster Recovery¶

# 1. Download latest backup
aws s3 cp s3://backups/latest.heliodump ./

# 2. Start new instance
heliosdb-lite start --memory --port 5432 &

# 3. Restore from backup
heliosdb-lite restore --input latest.heliodump

# 4. Verify restoration
heliosdb-lite status
psql -h localhost -c "SELECT COUNT(*) FROM users"

Data Migration¶

# 1. Dump from source
heliosdb-lite dump \
    --output migration.heliodump \
    --host old-server.example.com \
    --port 5432

# 2. Transfer dump file
scp migration.heliodump new-server.example.com:/tmp/

# 3. Restore to destination
ssh new-server.example.com
heliosdb-lite restore \
    --input /tmp/migration.heliodump \
    --host localhost \
    --port 5432

Exit Codes¶

Code	Meaning	Description
`0`	Success	Operation completed successfully
`1`	General Error	Unspecified error occurred
`2`	Invalid Arguments	Invalid command-line arguments
`10`	Connection Error	Cannot connect to database
`11`	Authentication Error	Authentication failed
`20`	Dump Error	Dump operation failed
`21`	Restore Error	Restore operation failed
`30`	Configuration Error	Invalid configuration file
`40`	I/O Error	File read/write error
`50`	Incompatible Version	Dump version incompatible

Example Usage:

#!/bin/bash
heliosdb-lite dump --output backup.heliodump

if [ $? -eq 0 ]; then
    echo "Backup successful"
else
    echo "Backup failed with code $?"
    exit 1
fi

Environment Variables¶

Variable	Description	Default
`HELIOSDB_CONFIG`	Path to config file	`./config.toml`
`HELIOSDB_DATA_DIR`	Default data directory	`./heliosdb-data`
`HELIOSDB_PORT`	Default server port	`5432`
`HELIOSDB_LOG_LEVEL`	Logging level	`info`
`HELIOSDB_USER`	Default database user	`postgres`
`HELIOSDB_PASSWORD`	Default database password	-
`PGHOST`	PostgreSQL host (fallback)	`localhost`
`PGPORT`	PostgreSQL port (fallback)	`5432`
`PGUSER`	PostgreSQL user (fallback)	`postgres`
`PGPASSWORD`	PostgreSQL password (fallback)	-

Example Usage:

# Set via environment
export HELIOSDB_PORT=5433
export HELIOSDB_LOG_LEVEL=debug

# Commands inherit settings
heliosdb-lite start --memory
# (starts on port 5433 with debug logging)

# Override with command-line flags
heliosdb-lite start --memory --port 5555
# (port 5555 takes precedence)

Priority Order: 1. Command-line flags (highest) 2. Environment variables 3. Configuration file 4. Built-in defaults (lowest)

CLI Reference (v3.5)¶

Table of Contents¶

Overview¶

Global Options¶

Commands¶

start Command¶

Synopsis¶

Options¶

HA Replication Options¶

Examples¶

Exit Behavior¶

repl Command¶

Synopsis¶

Options¶

Examples¶

REPL Commands¶

dump Command¶

Synopsis¶

Options¶

Examples¶

restore Command¶

Synopsis¶

Options¶

Examples¶

status Command¶

Synopsis¶

Options¶

Examples¶

version Command¶

Synopsis¶

Options¶

Examples¶

Common Use Cases¶

Development Workflow¶

Production Deployment¶

Disaster Recovery¶

Data Migration¶

Exit Codes¶

Environment Variables¶

See Also¶

`start` Command¶

`repl` Command¶

`dump` Command¶

`restore` Command¶

`status` Command¶

`version` Command¶