---
title: "CLI Reference"
description: "Subcommands and flags of the heliosdb-lite binary: start, stop, status, init, repl, dump, restore and skills."
---

# 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) | Start the server (PostgreSQL wire protocol plus the REST API) |
| [`stop`](#stop) | Stop a server started with `--daemon` |
| [`status`](#status) | Report whether a daemonised server is running |
| [`init`](#init) | Create an empty database directory |
| [`repl`](#repl) | Open the interactive SQL shell on an embedded database |
| [`dump`](#dump) | Write a database to a dump file |
| [`restore`](#restore) | Load a dump file into a database |
| [`skills`](#skills) | Install the bundled agent skills catalog |

## start

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

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

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

```bash
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](/docs/lite/features/high-availability/) for the replication model.

## stop

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

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

```bash
heliosdb-lite init [DATA_DIR]
```

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

## repl

```bash
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](/docs/lite/user-guide/repl-commands/).

## dump

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

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

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

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

See [Dump and Restore](/docs/lite/guides/user/dump_restore/) for workflows.

## skills

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

```bash
curl http://127.0.0.1:8080/version
```