Enterprise

# CLI reference

> Commands and flags of the Synnax Core CLI.

The `synnax` command starts and manages a Synnax Core. This page lists its commands, flags, environment variables, and configuration file keys.

## Start

The `start` command starts the Synnax Core.

### Example

Use the `-i` and `-m` flags to start a Core in insecure mode with an in-memory data store:

```cmd
synnax start -l localhost:9090 -im
```

### Flags

You can also set each flag with its environment variable. A flag on the command line takes precedence over its environment variable. In an environment variable, separate list values with spaces, not commas.

* [`--listen`, `-l`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listen)`<address> = "localhost:9090"`

  The address that clients and other Cores use to reach this Core. The host must be a name or address they can reach, and the TLS certificate must cover it. The Core binds the port on every network interface. To bind more than one address, each with its own certificate, give a list of listeners in a [configuration file](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#configuration-files). See [Serve multiple listeners](https://docs.synnaxlabs.com/reference/enterprise/listeners).

  Env `SYNNAX_LISTEN`

* [`--data`, `-d`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#data)`<path> = "synnax-data"`

  The folder where the Core keeps its data.

  Env `SYNNAX_DATA`

* [`--verbose`, `-v`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#verbose)

  Sets the log level to debug.

  Env `SYNNAX_VERBOSE`

* [`--insecure`, `-i`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#insecure)

  Turns off TLS. Users still log in. Do not use it in production.

  Env `SYNNAX_INSECURE`

* [`--fips`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#fips)

  Restricts password hashing to PBKDF2. The Core refuses passwords stored with another algorithm until an administrator sets them again.

  Env `SYNNAX_FIPS`

* [`--mem`, `-m`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#mem)

  Keeps all data in memory. The Core writes nothing to disk, and loses all data when it stops. Use it for tests and development, not for production.

  Env `SYNNAX_MEM`

* [`--help`, `-h`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#help)

  Prints the help message for the `start` command.

* [`--config`, `-c`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#config)`<path> = "/usr/local/synnax/config.yaml"`

  A JSON, YAML, or TOML file that sets the Core’s configuration in place of flags or environment variables. See [Configuration files](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#configuration-files). The Core ignores a file that is missing or cannot be read, with no message.

* [`--auto-cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#auto-cert)

  Creates a CA and a certificate for the `--listen` host in `--certs-dir`, and replaces the certificate when the host changes. See [Set up TLS](https://docs.synnaxlabs.com/reference/enterprise/tls#use-a-self-signed-certificate).

  Env `SYNNAX_AUTO_CERT`

* [`--certs-dir`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#certs-dir)`<path> = "/usr/local/synnax/certs"`

  The folder that holds the TLS certificates of the Core.

  Env `SYNNAX_CERTS_DIR`

* [`--ca-cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#ca-cert)`<path> = "ca.crt"`

  The CA certificate file, relative to `--certs-dir`. Optional: the Core starts without it.

  Env `SYNNAX_CA_CERT`

* [`--ca-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#ca-key)`<path> = "ca.key"`

  The CA key file, relative to `--certs-dir`. `--auto-cert` uses it to sign the certificate of the Core.

  Env `SYNNAX_CA_KEY`

* [`--node-cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#node-cert)`<path> = "node.crt"`

  The certificate file of the Core, relative to `--certs-dir`.

  Env `SYNNAX_NODE_CERT`

* [`--node-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#node-key)`<path> = "node.key"`

  The key file of the Core, relative to `--certs-dir`.

  Env `SYNNAX_NODE_KEY`

* [`--username`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#username)`<string> = "synnax"`

  The username of the root user. The Core applies it at every start. See [the root user](https://docs.synnaxlabs.com/reference/enterprise/users#the-root-user).

  Env `SYNNAX_USERNAME`

* [`--password`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#password)`<string> = "seldon"`

  The password of the root user. At every start, the Core sets the root password to this value. See [the root user](https://docs.synnaxlabs.com/reference/enterprise/users#the-root-user).

  Env `SYNNAX_PASSWORD`

* [`--license-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#license-key)`<string>`

  The license key to activate at start. It shows in the process list, so prefer `--license-file` or the environment variable. See [Activate a license](https://docs.synnaxlabs.com/reference/enterprise/license).

  Env `SYNNAX_LICENSE_KEY`

* [`--license-file`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#license-file)`<path>`

  A file that holds the license key to activate at start, such as the `.lic` file from the portal. When `--license-key` is also set, the key wins. See [activate at start](https://docs.synnaxlabs.com/reference/enterprise/license#activate-at-start).

  Env `SYNNAX_LICENSE_FILE`

* [`--debug`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#debug)

  Serves a metrics page and profiling routes to every network with no login, and turns on development logging. Do not use it in production. For debug logs, use `--verbose`.

  Env `SYNNAX_DEBUG`

* [`--session-idle-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#session-idle-timeout)`<duration> = "168h"`

  Ends a login session after this long with no request from its client.

  Env `SYNNAX_SESSION_IDLE_TIMEOUT`

* [`--slow-consumer-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#slow-consumer-timeout)`<duration> = "2.5s"`

  The time after which the Core closes a telemetry streamer that stops receiving messages. You rarely need to change it.

  Env `SYNNAX_SLOW_CONSUMER_TIMEOUT`

* [`--no-driver`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#no-driver)

  Disables the Driver embedded in the Core. Use it to run Synnax without device integrations.

  Env `SYNNAX_NO_DRIVER`

* [`--stop-on-stdin-close`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#stop-on-stdin-close)

  Stops the Core when its standard input closes. A line `stop` on standard input always stops the Core. Use it when a parent process starts the Core and holds its standard input, so that the Core stops if the parent exits. Do not set it for a Core that runs as a service, because a service has no standard input.

  Env `SYNNAX_STOP_ON_STDIN_CLOSE`

* [`--disable-integrations`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#disable-integrations)`<list>`

  The device integrations to disable. All integrations are enabled by default. The options are `arc`, `ethercat`, `http`, `labjack`, `modbus`, `ni`, and `opc`.

  Env `SYNNAX_DISABLE_INTEGRATIONS`

* [`--enable-integrations`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#enable-integrations)`<list>`

  The device integrations to enable, when you want only some of them. All integrations are enabled by default. The options are `arc`, `ethercat`, `http`, `labjack`, `modbus`, `ni`, and `opc`.

  Env `SYNNAX_ENABLE_INTEGRATIONS`

* [`--task-op-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-op-timeout)`<duration> = "60s"`

  The time after which the embedded Driver reports a task operation as stuck. Use it to debug tasks that block.

  Env `SYNNAX_TASK_OP_TIMEOUT`

* [`--task-poll-interval`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-poll-interval)`<duration> = "1s"`

  The time between task timeout checks in the embedded Driver.

  Env `SYNNAX_TASK_POLL_INTERVAL`

* [`--task-shutdown-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-shutdown-timeout)`<duration> = "30s"`

  The longest time the embedded Driver waits for task workers when it shuts down. After this time, it detaches workers that are stuck.

  Env `SYNNAX_TASK_SHUTDOWN_TIMEOUT`

* [`--task-worker-count`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-worker-count)`<int> = 4`

  The number of worker threads for task operations in the embedded Driver, from 1 to 64.

  Env `SYNNAX_TASK_WORKER_COUNT`

* [`--log-file-path`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-path)`<path> = "./synnax-logs/synnax.log"`

  The file where the Core writes its logs.

  Env `SYNNAX_LOG_FILE_PATH`

* [`--log-file-max-size`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-size)`<int> = 50`

  The largest size of a log file, in MB, before the Core starts a new one.

  Env `SYNNAX_LOG_FILE_MAX_SIZE`

* [`--log-file-max-backups`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-backups)`<int> = 5`

  The number of old log files to keep before the Core deletes them.

  Env `SYNNAX_LOG_FILE_MAX_BACKUPS`

* [`--log-file-max-age`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-age)`<int> = 30`

  The number of days to keep old log files before the Core deletes them.

  Env `SYNNAX_LOG_FILE_MAX_AGE`

* [`--log-file-compress`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-compress)

  Compresses old log files on disk.

  Env `SYNNAX_LOG_FILE_COMPRESS`

* [`--disable-channel-name-validation`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#disable-channel-name-validation)

  Lets channels have any name, including special characters and spaces. By default, a channel name can contain only letters, digits, and underscores, and cannot start with a digit.

  Env `SYNNAX_DISABLE_CHANNEL_NAME_VALIDATION`

### Configuration files

The Core also reads a configuration file in JSON, YAML, or TOML. Each key has the name of its flag. Environment variables and flags take precedence over the file.

By default, the Core reads `/usr/local/synnax/config.yaml`. To use a different file, set `--config`. The `SYNNAX_CONFIG` environment variable has no effect.

Example files:

**JSON**

```json
{
  "listen": "localhost:9090",
  "data": "/usr/local/synnax/data",
  "verbose": true,
  "insecure": false,
  "mem": false,
  "certs-dir": "/usr/local/synnax/certs",
  "ca-cert": "ca.crt",
  "node-cert": "node.crt",
  "node-key": "node.key",
  "username": "synnax",
  "password": "seldon",
  "license-file": "/usr/local/synnax/synnax.lic",
  "debug": false,
  "session-idle-timeout": "168h",
  "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
}
```

**YAML**

```yaml
listen: localhost:9090
data: /usr/local/synnax/data
verbose: true
insecure: false
mem: false
certs-dir: /usr/local/synnax/certs
ca-cert: ca.crt
node-cert: node.crt
node-key: node.key
username: synnax
password: seldon
license-file: /usr/local/synnax/synnax.lic
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
```

**TOML**

```toml
listen = "localhost:9090"
data = "/usr/local/synnax/data"
verbose = true
insecure = false
mem = false
certs-dir = "/usr/local/synnax/certs"
ca-cert = "ca.crt"
node-cert = "node.crt"
node-key = "node.key"
username = "synnax"
password = "seldon"
license-file = "/usr/local/synnax/synnax.lic"
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 a single address, as above, or a list of listeners, each with its own address and certificate. The list works only in a configuration file, and cannot be combined with `--auto-cert`, `--node-cert`, or `--node-key`. See [Serve multiple listeners](https://docs.synnaxlabs.com/reference/enterprise/listeners).

```yaml
listen:
  - address: core01.example.com:9090
    cert:
      source: auto
    advertise: true
  - address: node01.example-tailnet.ts.net:9091
    cert:
      source: tailscale
    name: console
```

Fields of a listener:

* [`address`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-address)\* Required

  The `host:port` the listener binds to. Unique across listeners.

* [`cert.source`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-cert-source)

  The certificate source: `file`, `auto`, or `tailscale`. Required unless the Core starts with `--insecure`. See [Certificate sources](https://docs.synnaxlabs.com/reference/enterprise/listeners#certificate-sources).

* [`cert.cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-cert-cert)

  For a `file` source, the path to the PEM certificate. If `cert` and `key` are both empty, the listener uses the node certificate.

* [`cert.key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-cert-key)

  For a `file` source, the path to the PEM private key.

* [`advertise`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-advertise)

  Marks this listener’s address as the one the embedded Driver connects to. At most one listener may set it; the first listener is advertised if none do.

* [`name`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-name)

  An optional label. The Core does not use it.

* [`loopback`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-loopback)

  Binds the listener to the loopback interface only, so no other machine can reach it. The address host must be `localhost` or `127.0.0.1`. By default, a listener binds its port on every network interface.

## Cert

The `cert` commands create the files that `--auto-cert` creates, without starting the Core. They take `--certs-dir`, `--ca-cert`, `--ca-key`, `--node-cert`, and `--node-key` with the same defaults as `start`, and also:

* `--key-size` -> the key size in bits. Default 2048.
* `--allow-key-reuse` -> lets the CA key sign more than one certificate. Default false.

### cert ca

Creates `ca.crt` and `ca.key`.

```bash
synnax cert ca
```

### cert node

Creates `node.crt` and `node.key` for one or more hosts, signed by the CA. It needs the CA files and does not replace node files that exist.

```bash
synnax cert node synnax.example.com
```

## Version

The `version` command, or `synnax --version`, prints the version of the Core:

```bash
synnax version
```

```text
Synnax v0.60.0
```

## Service (Windows only)

The `service` commands run the Core as a Windows service named `SynnaxCore`. Run them in a terminal as an administrator. For the steps, see [Run the Core as a service](https://docs.synnaxlabs.com/reference/enterprise/service).

The service starts when Windows starts, unless installed with `--auto-start=false`. When the Core crashes, Windows restarts it after 5 seconds, then 30 seconds, then 60 seconds. The count resets each day. The service writes its log to the log file, not to the Windows Event Log.

### service install

Installs the service. It takes every `start` flag and writes them to `C:\ProgramData\Synnax\config.yaml`. The service reads only that file, and ignores `SYNNAX_*` environment variables. When the file exists, `install` does not change it.

```bash
synnax service install --listen=synnax.example.com:9090 --auto-cert
```

On Windows, these flags have different defaults:

* `--data` -> `C:\ProgramData\Synnax\data`
* `--certs-dir` -> `C:\ProgramData\Synnax\certs`
* `--log-file-path` -> `C:\ProgramData\Synnax\logs\synnax.log`

Two flags are only for `install`:

* `--auto-start` -> start the service when Windows starts. Default true.
* `--delayed-start` -> start the service after Windows finishes starting. Default false. With `--delayed-start`, the service starts automatically even with `--auto-start=false`.

### service uninstall

Removes the service. It does not stop a running service, and it does not delete `config.yaml`. Run `synnax service stop` first.

```bash
synnax service uninstall
```

### service start

Starts the service.

```bash
synnax service start
```

### service stop

Stops the service.

```bash
synnax service stop
```

### service status

Shows whether the service is installed and running, its version, its data folder, log file, certificate folder, listen address, and whether it runs with `--insecure`. When the service is stopped, it also shows the last 10 warnings and errors.

```bash
synnax service status
```