---
title: "CLI Reference"
---

# 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.

## Table of Contents

1. [Overview](#overview)
2. [Global Options](#global-options)
3. [Commands](#commands)
   - [start](#start-command)
   - [stop](#stop-command)
   - [status](#status-command)
   - [init](#init-command)
   - [repl](#repl-command)
   - [dump](#dump-command)
   - [restore](#restore-command)
4. [Common Use Cases](#common-use-cases)
5. [Exit Codes](#exit-codes)
6. [Environment Variables](#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:**

```bash
# 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](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest)
page. See [Installation](https://www.heliosdb.com/docs/nano/getting-started/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`):

```bash
# 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

```bash
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)**

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

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

**2. Persistent Server (Production)**

```bash
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**

```bash
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**

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

**5. High Availability**

```bash
# 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](https://www.heliosdb.com/docs/nano/features/high-availability/) for details.

**6. MySQL Protocol**

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

**7. With a Configuration File**

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

Command-line flags take precedence over the configuration file. See the
[Configuration Reference](https://www.heliosdb.com/docs/nano/reference/configuration_reference/).

---

### `stop` Command

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

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

---

### `status` Command

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

```bash
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.

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

---

### `repl` Command

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

#### Synopsis

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
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

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

---

## Common Use Cases

### Development Workflow

```bash
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

```bash
# 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

```bash
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 |

```bash
#!/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.

---

## See Also

- [Configuration Reference](https://www.heliosdb.com/docs/nano/reference/configuration_reference/) - Configuration file options
- [In-Memory Mode Guide](https://www.heliosdb.com/docs/nano/guides/user/inmemory_mode/) - In-memory operations
- [Dump/Restore Guide](https://www.heliosdb.com/docs/nano/guides/user/dump_restore/) - Backup procedures
- [Migration Guide](https://www.heliosdb.com/docs/nano/guides/migration/) - Migration planning and operational checks