# 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: ```cmd synnax start -l localhost:9090 -im ``` ### Flags | Flag | Default | Description | | ----------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--listen/-l` | `"localhost:9090"` | A reachable address and port to listen on for incoming client connections and RPCs from other nodes. To bind multiple addresses, each with its own certificate, provide a list of listener objects in a configuration file. See [Serving multiple listeners](https://docs.synnaxlabs.com/reference/core/production#serving-multiple-listeners). | | `--peers/-p` | `[]` | A list of comma-separated peer Cores in an existing cluster. If this list is not empty, the Core will attempt to join the cluster by connecting to each peer in the list. If the list is empty and no existing cluster data is found, the Core will bootstrap a new cluster. | | `--data/-d` | `"synnax-data"` | The file path to the folder where Synnax will keep its data. | | `--verbose/-v` | `false` | Enables human-readable logging. | | `--insecure/-i` | `false` | Starts the node without TLS encryption. This is not recommended for production use. | | `--mem/-m` | `false` | Starts the node with an in-memory data store. In this mode, all data will kept in memory, will not be stored on disk, and will be lost when the node is restarted. This can be useful for testing and development, but is not recommended for production use. | | `--help/-h` | `false` | Prints the help message for the start command. | | `--config/c` | `"/usr/local/synnax/config.yaml"` | Path to a JSON, YAML, or TOML configuration file that can be used to set the node's configuration instead of using flags or environment variables. See [Configuration files](https://docs.synnaxlabs.com/reference/core/cli-reference#configuration-files) for more information. | | `--auto-cert` | `false` | Automatically generate self-signed certificates for the node. | | `--certs-dir` | `"/usr/local/synnax/certs"` | Path to the directory containing the TLS certificates for the node. | | `--ca-cert` | `"ca.crt"` | Path to the CA certificate file relative to \`--certs-dir\`. | | `--node-cert` | `"node.crt"` | Path to the node certificate file relative to \`--certs-dir\`. | | `--node-key` | `"node.key"` | Path to the node key file relative to \`--certs-dir\`. | | `--username` | `"synnax"` | Username for the cluster root user. Reconciled on every start — see [Root user reconciliation](https://docs.synnaxlabs.com/reference/core/cli-reference#root-user-reconciliation) for the behavior when this changes between restarts. | | `--password` | `"seldon"` | Password for the cluster root user. The configured value is the source of truth: if the stored password diverges, it is rotated to match on the next start. See [Root user reconciliation](https://docs.synnaxlabs.com/reference/core/cli-reference#root-user-reconciliation). | | `--license-key` | `""` | License key that activates the Core. | | `--debug` | `false` | Enables debug logging output. We recommend against using this in production, as it generates a very large amount of output. | | `--slow-consumer-timeout` | `2500000000` | The duration, in ns, after which a telemetry streamer will be closed by the Core if it stops receiving messages. It's rarely necessary to change this value. The default is 2.5s. | | `--no-driver` | `false` | Disables the embedded Synnax Driver for the Synnax Core. This is useful when you want to run Synnax without any device integration. | | `--stop-on-stdin-close` | `false` | Stops the Core when its standard input closes. 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. | | `--disable-integrations` | `[]` | List of device integrations to disable. This is useful when you don't want particular integrations. All integrations are enabled by default. Options are: arc, ethercat, labjack, modbus, ni, opc | | `--enable-integrations` | `[]` | List of device integrations to enable. This is useful when you only want particular integrations. All integrations are enabled by default. Options are: arc, ethercat, labjack, modbus, ni, opc | | `--task-op-timeout` | `"60s"` | Duration before reporting stuck task operations in the embedded driver. This is useful for debugging tasks that may be blocking. | | `--task-poll-interval` | `"1s"` | Interval between task timeout checks in the embedded driver. | | `--task-shutdown-timeout` | `"30s"` | Maximum time to wait for task workers during embedded driver shutdown. After this timeout, stuck workers will be detached. | | `--task-worker-count` | `4` | Number of worker threads for task operations in the embedded driver. Valid range is 1-64. | | `--log-file-path` | `"./synnax-logs/synnax.log"` | The path to the file in which the Synnax Core should store its logs | | `--log-file-max-size` | `50` | The maximum size (in MB) before a log file gets rotated. | | `--log-file-max-backups` | `5` | The maximum number of log files that should be kept before they are deleted | | `--log-file-max-age` | `30` | The maximum age (in days) that log files should be kept before they are removed | | `--log-file-compress` | `false` | Whether to compress log files on disk. | | `--disable-channel-name-validation` | `false` | Disables channel name validation. When enabled, channels can be created with any name including special characters and spaces. By default, channel names must contain only letters, digits, and underscores, and cannot start with a digit. | ### 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. | Flag | Environment variable | | ----------------------------------- | ---------------------------------------- | | `--listen/-l` | `SYNNAX_LISTEN` | | `--peers/-p` | `SYNNAX_PEERS` | | `--data/-d` | `SYNNAX_DATA` | | `--verbose/-v` | `SYNNAX_VERBOSE` | | `--insecure/-i` | `SYNNAX_INSECURE` | | `--mem/-m` | `SYNNAX_MEM` | | `--config/c` | `SYNNAX_CONFIG` | | `--certs-dir` | `SYNNAX_CERTS_DIR` | | `--ca-cert` | `SYNNAX_CA_CERT` | | `--node-cert` | `SYNNAX_NODE_CERT` | | `--node-key` | `SYNNAX_NODE_KEY` | | `--username` | `SYNNAX_USERNAME` | | `--password` | `SYNNAX_PASSWORD` | | `--license-key` | `SYNNAX_LICENSE_KEY` | | `--debug` | `SYNNAX_DEBUG` | | `--slow-consumer-timeout` | `SYNNAX_SLOW_CONSUMER_TIMEOUT` | | `--no-driver` | `SYNNAX_NO_DRIVER` | | `--stop-on-stdin-close` | `SYNNAX_STOP_ON_STDIN_CLOSE` | | `--disable-integrations` | `SYNNAX_DISABLE_INTEGRATIONS` | | `--enable-integrations` | `SYNNAX_ENABLE_INTEGRATIONS` | | `--task-op-timeout` | `SYNNAX_TASK_OP_TIMEOUT` | | `--task-poll-interval` | `SYNNAX_TASK_POLL_INTERVAL` | | `--task-shutdown-timeout` | `SYNNAX_TASK_SHUTDOWN_TIMEOUT` | | `--task-worker-count` | `SYNNAX_TASK_WORKER_COUNT` | | `--log-file-path` | `SYNNAX_LOG_FILE_PATH` | | `--log-file-max-size` | `SYNNAX_LOG_FILE_MAX_SIZE` | | `--log-file-max-backups` | `SYNNAX_LOG_FILE_MAX_BACKUPS` | | `--log-file-max-age` | `SYNNAX_LOG_FILE_MAX_AGE` | | `--log-file-compress` | `SYNNAX_LOG_FILE_COMPRESS` | | `--disable-channel-name-validation` | `SYNNAX_DISABLE_CHANNEL_NAME_VALIDATION` | ### 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: **JSON** ```json { "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 } ``` **YAML** ```yaml 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 ``` **TOML** ```toml 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](https://docs.synnaxlabs.com/reference/core/production#serving-multiple-listeners) for the full deployment model. ```yaml 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: | Field | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | The `host:port` the listener binds to. Required and unique across listeners. | | `cert.source` | The certificate source: `file`, `auto`, or `tailscale`. See [Certificate sources](https://docs.synnaxlabs.com/reference/core/production#certificate-sources). | | `cert.cert` | For a `file` source, the path to the PEM certificate. | | `cert.key` | For a `file` source, the path to the PEM private key. | | `advertise` | Marks this listener's address as the one peers dial to join the cluster. At most one listener may set it; the first listener is advertised if none do. | | `name` | An optional label for the listener, shown in logs. | | `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. | ### 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: | Scenario | Behavior | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Fresh Core (no existing users) | A new user is created with the configured username and marked as the root user. Credentials are registered and the user is granted the `Owner` role. | | Restart with unchanged credentials | No-op — the existing root user is left alone. | | Restart with the same username but a different password | The stored password is rotated to match the configured one. The old password no longer authenticates. Other users' passwords are untouched. | | Restart with a different username | The previous root user is demoted (the `RootUser` flag is cleared) but retains their `Owner` role and credentials, so they can still log in with full permissions. A new user is created with the configured username, marked root, and granted `Owner`. | | Configured username matches an existing *non-root* user | The existing user is promoted in place: their `RootUser` flag is set to true, their stored password is rotated to match the configured one, and any previous root user is demoted. The user keeps the same key, name, and role assignments. This lets you point `--username` at an already-provisioned account to make it the root, instead of creating a new one. | | Restart with no credentials configured (both flags omitted) | Auth state is left untouched. If multiple users somehow have `RootUser=true`, all but the first returned by the retrieve are demoted (keeping their `Owner` role) and a warning is logged. A cluster with zero or one root user is left as-is, so test setups and other callers that do not need a root user can open the Core without supplying credentials. | #### 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: ```cmd synnax version ``` You’ll see output similar to the following: ```text 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): ```cmd synnax service install --insecure ``` Install with custom data directory and listen address: ```cmd synnax service install --listen 0.0.0.0:9090 --data C:\ProgramData\Synnax\data --insecure ``` Install without auto-start: ```cmd synnax service install --auto-start=false --insecure ``` #### Flags | Flag | Default | Description | | ------------------------ | ------------------------------ | ------------------------------------------------------------------------- | | `--auto-start` | `true` | Start the service automatically when Windows starts. | | `--delayed-start` | `false` | Delay service start until after Windows startup completes. | | `--listen/-l` | `"localhost:9090"` | The address to listen for client connections. | | `--data/-d` | `"C:\ProgramData\Synnax\data"` | Directory where Synnax will store its data. | | `--insecure/-i` | `false` | Disable encryption, authentication, and authorization. | | `--username` | `"synnax"` | Username for the admin user. | | `--password` | `"seldon"` | Password for the admin user. | | `--auto-cert` | `false` | Automatically generate self-signed certificates. | | `--no-driver` | `false` | Disable the embedded Synnax driver. | | `--enable-integrations` | `[]` | Device integrations to enable (arc, ethercat, labjack, modbus, ni, opc). | | `--disable-integrations` | `[]` | Device integrations to disable (arc, ethercat, labjack, modbus, ni, opc). | | `--peers/-p` | `[]` | Addresses of additional peers in the cluster. | ### service uninstall Removes the Synnax Windows Service. This will stop the service if it is running and remove it from the system. ```cmd synnax service uninstall ``` ### service start Starts the installed Synnax Windows Service. ```cmd synnax service start ``` ### service stop Stops the running Synnax Windows Service. ```cmd synnax service stop ```