CLI reference

Find information about the Synnax Core CLI.

Start

The start command starts the Synnax Core.

Examples

Starting a Core

We can use the i and m flags to start a Core in insecure mode with an in-memory data store:

synnax start -l localhost:9090 -im

Flags

Environment variable equivalents

The following environment variables can be used in place of the corresponding flags. Command line flags will take precedence over environment variables.

Configuration files

Synnax will also read configuration files in JSON, TOML and YAML formats. The values set in these configuration files take the lowest precedence and will be overridden by any environment variables or command line flags.

By default, Synnax will look for a configuration file at ~/.synnax.yaml. You can specify a different configuration file using the --config flag or the SYNNAX_CONFIG environment variable.

Here are example configuration files in various formats:

{
  "listen": "localhost:9090",
  "peers": ["localhost:9091", "localhost:9092"],
  "data": "/usr/local/synnax/data",
  "verbose": true,
  "insecure": false,
  "mem": false,
  "config": "/usr/local/synnax/config.yaml",
  "certs-dir": "/usr/local/synnax/certs",
  "ca-cert": "ca.crt",
  "node-cert": "node.crt",
  "node-key": "node.key",
  "username": "synnax",
  "password": "seldon",
  "license-key": "000000-00000000-0000000000",
  "debug": false,
  "slow-consumer-timeout": "2.5s",
  "no-driver": false,
  "disable-integrations": [],
  "enable-integrations": [],
  "task-op-timeout": "60s",
  "task-poll-interval": "1s",
  "task-shutdown-timeout": "30s",
  "task-worker-count": 4,
  "log-file-path": "./synnax-logs/synnax.log",
  "log-file-max-size": 50,
  "log-file-max-backups": 5,
  "log-file-max-age": 30,
  "log-file-compress": true,
  "disable-channel-name-validation": false
}

listen: localhost:9090
peers:
  - localhost:9091
  - localhost:9092
data: /usr/local/synnax/data
verbose: true
insecure: false
mem: false
config: /usr/local/synnax/config.yaml
certs-dir: /usr/local/synnax/certs
ca-cert: ca.crt
node-cert: node.crt
node-key: node.key
username: synnax
password: seldon
license-key: 000000-00000000-0000000000
no-driver: false
disable-integrations: []
enable-integrations: []
task-op-timeout: 60s
task-poll-interval: 1s
task-shutdown-timeout: 30s
task-worker-count: 4
log-file-path: ./synnax-logs/synnax.log
log-file-max-size: 50
log-file-max-backups: 5
log-file-max-age: 30
log-file-compress: true
disable-channel-name-validation: false

listen = "localhost:9090"
peers = ["localhost:9091", "localhost:9092"]
data = "/usr/local/synnax/data"
verbose = true
insecure = false
mem = false
config = "/usr/local/synnax/config.yaml"
certs-dir = "/usr/local/synnax/certs"
ca-cert = "ca.crt"
node-cert = "node.crt"
node-key = "node.key"
username = "synnax"
password = "seldon"
license-key = "000000-00000000-0000000000"
no-driver = false
disable-integrations = []
enable-integrations = []
task-op-timeout = "60s"
task-poll-interval = "1s"
task-shutdown-timeout = "30s"
task-worker-count = 4
log-file-path = "./synnax-logs/synnax.log"
log-file-max-size = 50
log-file-max-backups = 5
log-file-max-age = 30
log-file-compress = true
disable-channel-name-validation = false

Multiple listeners

The listen key takes either form. A single address (as above) binds one listener over the node certificate paths. A list of objects binds one listener per entry, each with its own address and certificate. The list form works in configuration files only, not as a flag. See Serving multiple listeners for the full deployment model.

listen:
  - address: core01.example.com:9090
    cert:
      source: file
      cert: /usr/local/synnax/certs/driver.crt
      key: /usr/local/synnax/certs/driver.key
    advertise: true
  - address: node01.example-tailnet.ts.net:9091
    cert:
      source: tailscale
    name: console

Each listener object accepts the following fields:

Root user reconciliation

Every time a Core starts, it reconciles the configured --username / --password against the existing cluster state. The configured credentials are the source of truth: the Core makes the state match config, rather than asking the operator to log in and update things by hand.

The behavior depends on what already exists on disk:

Recovering a forgotten root password

Because the configured password is the source of truth, you can recover a forgotten root password by editing the Core’s configuration (config file, environment variable, or --password flag) and restarting the Core. The stored password will be rotated on startup. Non-root users rotate their passwords through the API as normal — only the root user’s password is governed by configuration.

Demoted users

When a username change demotes the previous root user, that user keeps their Owner role and their original credentials. They can still log in with full permissions; they just no longer hold the immutable root-user flag. To fully remove them, an Owner can delete the demoted user through the API.

Version

The version command prints the installed version of the Synnax database.

Examples

If you run this command:

synnax version

You’ll see output similar to the following:

Synnax v0.59.1

Flags

This command has no flags.

Service (Windows only)

The service command manages Synnax as a Windows Service. These commands are only available on Windows and require administrator privileges.

When running as a Windows Service, Synnax will:

• Start automatically when Windows boots (if configured)
• Receive proper shutdown signals for graceful termination
• Log events to the Windows Event Log
• Automatically restart on failure

service install

Installs Synnax as a Windows Service. Server configuration flags are stored in the service configuration and used when the service starts.

Examples

Install with default settings (auto-start enabled, insecure mode):

synnax service install --insecure

Install with custom data directory and listen address:

synnax service install --listen 0.0.0.0:9090 --data C:\ProgramData\Synnax\data --insecure

Install without auto-start:

synnax service install --auto-start=false --insecure

Flags

service uninstall

Removes the Synnax Windows Service. This will stop the service if it is running and remove it from the system.

synnax service uninstall

service start

Starts the installed Synnax Windows Service.

synnax service start

service stop

Stops the running Synnax Windows Service.

synnax service stop