storm-server

The server: run it, install it as a service, pair the first device, back it up. Generated from storm-server --help.

Storm sync server

Usage: storm-server [OPTIONS] <COMMAND>

Commands:
  serve            Run the sync server (what systemd starts)
  up               Install and start the server as a service. Linux: write the env file and enable the systemd unit (as root). macOS: install a LaunchAgent that runs as you, with the notes in ~/Storm (decision 84d; not root)
  down             Stop the service (and keep it from starting again)
  status           Show the service's state and a local health probe
  uninstall        macOS: stop the LaunchAgent and remove what `up` installed, keeping the notes. Linux: the package owns the install (`apt remove`)
  dry-run          Report what an import would change, then exit without writing
  passwd           Set the account's password — the recovery path when it is forgotten (A11). On a Storm not set up yet, this creates the account
  single-user      Choose which account a pre-v6 server keeps when it becomes single-user (decision 82). Only needed when it has no active owner to keep
  pair             Print a bootstrap pairing QR code for a fresh server (no account yet)
  has-account      Exit 0 if this Storm has its account, 1 if not (decision 84). For the installer, which waits on a first device's pairing
  host-enrollment  Mint a one-time Runtime Host enrollment string for a host on this machine, and print it for `storm-runtime enroll` to read (decision 84e). Run by whoever owns the state directory, like `passwd`. It is a secret, so it is printed only into a pipe, never to a terminal
  qr               Draw TEXT as a scannable QR block, for the installer's download and web links
  backup-db        Snapshot every vault index into DIR, then exit
  storage-root     Print the storage root this server uses, from its registry
  backup           Back up the vaults, the indexes and the account into `DEST/<YYYY-MM-DD>/`, check the snapshots open, and prune old ones: `deploy/storm-backup.sh` without bash, for Windows' nightly task (decision 99, W-S3)
  help             Print this message or the help of the given subcommand(s)

Options:
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help
  -V, --version          Print version

serve

Run the sync server (what systemd starts)

Usage: storm-server serve [OPTIONS]

Options:
      --vault-root <VAULT_ROOT>
          Storage root — a directory holding one directory per vault
          
          [env: STORM_VAULT_ROOT=]

      --vault <VAULT>
          Deprecated: a single vault directory.
          
          Accepted for one release so an existing single-vault deployment starts without edits. The storage root becomes this directory's *parent* and this one directory is registered as a vault.

      --state <STATE>
          State directory for the registry and the per-vault SQLite indexes. Kept out of the vaults so they stay pure markdown
          
          [default: ./state]

      --host <HOST>
          [default: 127.0.0.1]

      --port <PORT>
          [default: 8484]

      --web <WEB>
          Directory holding the built Flutter web client, served at `/`

      --mcp
          Serve the Model Context Protocol endpoint at `/mcp`.
          
          Read-only tools over the same vaults and the same bearer token. Off by default: it is a new surface on the notes, and turning one on should be a decision rather than a side effect of upgrading.

      --no-discovery
          Do not advertise on the local network, and refuse pairing with the password, whatever the app's setting says (decision 118). Also `STORM_DISCOVERY=0`

      --log-file <FILE>
          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)

  -h, --help
          Print help (see a summary with '-h')

up

Install and start the server as a service. Linux: write the env file and enable the systemd unit (as root). macOS: install a LaunchAgent that runs as you, with the notes in ~/Storm (decision 84d; not root)

Usage: storm-server up [OPTIONS]

Options:
      --data-root <DATA_ROOT>
          Directory for vaults/, state/, and backups/ (default /srv/storm on Linux, ~/Storm on macOS).
          
          Ignored for a path that `--vault-root` / `--state` override individually — needed when vaults and state already live in different places.

      --vault-root <VAULT_ROOT>
          Override the storage root (default: `<data-root>/vaults`)

      --state <STATE>
          Override the state directory (default: `<data-root>/state`)

      --host <HOST>
          [default: 0.0.0.0]

      --port <PORT>
          [default: 8484]

      --web <WEB>
          Built Flutter web client directory (Linux: the package's /usr/share/storm/web; macOS: the `web/` beside this binary)

      --log-file <FILE>
          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)

  -h, --help
          Print help (see a summary with '-h')

down

Stop the service (and keep it from starting again)

Usage: storm-server down [OPTIONS]

Options:
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

status

Show the service's state and a local health probe

Usage: storm-server status [OPTIONS]

Options:
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

uninstall

macOS: stop the LaunchAgent and remove what `up` installed, keeping the notes. Linux: the package owns the install (`apt remove`)

Usage: storm-server uninstall [OPTIONS]

Options:
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

dry-run

Report what an import would change, then exit without writing

Usage: storm-server dry-run [OPTIONS]

Options:
      --vault-root <VAULT_ROOT>
          Storage root — a directory holding one directory per vault
          
          [env: STORM_VAULT_ROOT=]

      --vault <VAULT>
          Deprecated: a single vault directory.
          
          Accepted for one release so an existing single-vault deployment starts without edits. The storage root becomes this directory's *parent* and this one directory is registered as a vault.

      --state <STATE>
          State directory for the registry and the per-vault SQLite indexes. Kept out of the vaults so they stay pure markdown
          
          [default: ./state]

      --log-file <FILE>
          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)

  -h, --help
          Print help (see a summary with '-h')

passwd

Set the account's password — the recovery path when it is forgotten (A11). On a Storm not set up yet, this creates the account

Usage: storm-server passwd [OPTIONS]

Options:
      --state <STATE>    State directory holding auth.db [default: ./state]
      --password-stdin   Read the password from stdin instead of prompting
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

single-user

Choose which account a pre-v6 server keeps when it becomes single-user (decision 82). Only needed when it has no active owner to keep

Usage: storm-server single-user [OPTIONS] --keep <KEEP>

Options:
      --state <STATE>    State directory holding auth.db [default: ./state]
      --keep <KEEP>      Every other account is deleted; `auth.db.pre-v6` is written first
      --yes              Skip the confirmation prompt
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

pair

Print a bootstrap pairing QR code for a fresh server (no account yet)

Usage: storm-server pair [OPTIONS]

Options:
      --state <STATE>
          State directory holding auth.db and the server identity
          
          [default: ./state]

      --addr <ADDR>
          Address the QR code tells the client to connect to

      --qr
          Also draw the URI as a scannable QR block.
          
          Opt-in rather than the default: the block is ~45 columns wide and is noise when the output is being read by a script, which is how the deploy scripts and `auth_e2e.py` consume this command.

      --log-file <FILE>
          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)

  -h, --help
          Print help (see a summary with '-h')

has-account

Exit 0 if this Storm has its account, 1 if not (decision 84). For the installer, which waits on a first device's pairing

Usage: storm-server has-account [OPTIONS]

Options:
      --state <STATE>    State directory holding auth.db [default: ./state]
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

host-enrollment

Mint a one-time Runtime Host enrollment string for a host on this machine, and print it for `storm-runtime enroll` to read (decision 84e). Run by whoever owns the state directory, like `passwd`. It is a secret, so it is printed only into a pipe, never to a terminal

Usage: storm-server host-enrollment [OPTIONS]

Options:
      --state <STATE>    State directory holding auth.db and the server identity [default: ./state]
      --url <URL>        The address the host will reach this server at. Defaults to the loopback address on `STORM_PORT` (8484)
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

qr

Draw TEXT as a scannable QR block, for the installer's download and web links

Usage: storm-server qr [OPTIONS] <TEXT>

Arguments:
  <TEXT>  

Options:
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

backup-db

Snapshot every vault index into DIR, then exit

Usage: storm-server backup-db [OPTIONS] <DIR>

Arguments:
  <DIR>  Destination directory for the snapshots

Options:
      --state <STATE>    State directory holding the registry and indexes [default: ./state]
      --log-file <FILE>  Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help             Print help

storage-root

Print the storage root this server uses, from its registry.

For the nightly backup (decision 79). The stored root wins over `STORM_VAULT_ROOT`, which only seeds a first run, so a script that read the env file copied the wrong directory once the root was changed in the app. Exits 3, printing nothing, when there is no registry yet.

Usage: storm-server storage-root [OPTIONS]

Options:
      --state <STATE>
          State directory holding vaults.json
          
          [default: ./state]

      --log-file <FILE>
          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)

  -h, --help
          Print help (see a summary with '-h')

backup

Back up the vaults, the indexes and the account into `DEST/<YYYY-MM-DD>/`, check the snapshots open, and prune old ones: `deploy/storm-backup.sh` without bash, for Windows' nightly task (decision 99, W-S3)

Usage: storm-server backup [OPTIONS] --vault-root <VAULT_ROOT> --dest <DEST>

Options:
      --vault-root <VAULT_ROOT>  The storage root to fall back on when the registry names none
      --state <STATE>            State directory holding vaults.json and the databases [default: ./state]
      --dest <DEST>              Where the dated backups go
      --keep-days <KEEP_DAYS>    Dated backups older than this many days are removed [default: 30]
      --log-file <FILE>          Append the log to this file instead of the terminal. Windows' windowless `storm-serverw` has no terminal (decision 99, W-S1)
  -h, --help                     Print help