CLI Reference (v3.5)

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

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

Overview

The heliosdb-nano 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-nano-linux-amd64.tar.gz
tar xzf heliosdb-nano-linux-amd64.tar.gz
sudo mv heliosdb-nano /usr/local/bin/

# Verify installation
heliosdb-nano 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-nano --config /etc/heliosdb/config.toml start --memory

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

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

Commands

`start` Command

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

Synopsis

heliosdb-nano 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-nano start --memory

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

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

2. Persistent Server (Production)

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

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

3. Daemon Mode

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

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

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

4. In-Memory with Dump on Shutdown

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

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

5. High Availability Mode

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

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

# Start as observer (for split-brain protection)
heliosdb-nano 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-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 \
    --http-port 8080

# Standby with custom node ID
heliosdb-nano 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-nano --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-nano 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-nano repl --memory

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

2. Persistent REPL

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

3. Execute Single Query

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

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

4. Disable History

heliosdb-nano repl --memory --no-history

5. With Default Data Directory

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

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

6. Dump on Shutdown (In-Memory Mode)

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

# Dump to custom file
heliosdb-nano 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-nano 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-nano dump --output backup.heliodump

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

2. Incremental Dump

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

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

3. Selective Dump

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

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

4. Remote Database Dump

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

5. Compression Options

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

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

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

6. Verbose Output

heliosdb-nano 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-nano 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-nano 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-nano restore --input backup.heliodump

2. Append Mode

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

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

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

3. Selective Restore

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

4. Remote Restore

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

5. Dry Run (Verification)

# Verify dump without restoring
heliosdb-nano 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-nano 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-nano 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-nano status

# Output:
# HeliosDB Nano 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-nano 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-nano status --host db.example.com --port 5432 --user admin

`version` Command

Show version information.

Synopsis

heliosdb-nano 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-nano version

# Output:
# HeliosDB Nano 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-nano version --short

# Output:
# 3.5.8

3. JSON Output

heliosdb-nano 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-nano 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-nano dump --output testdata.heliodump

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

Production Deployment

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

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

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

# 4. Graceful restart
kill -SIGTERM $(cat /var/run/heliosdb.pid)
# ... optionally dump before restart ...
heliosdb-nano 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-nano start --memory --port 5432 &

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

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

Data Migration

# 1. Dump from source
heliosdb-nano 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-nano 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-nano 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-nano start --memory
# (starts on port 5433 with debug logging)

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

Priority Order:

Command-line flags (highest)
Environment variables
Configuration file
Built-in defaults (lowest)

CLI Reference (v3.5)

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