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

Flag	Default	Description
`--listen/-l`	`"localhost:9090"`	A reachable address and port to listen on for incoming client connections and RPCs from other nodes.
`--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 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 database root user.
`--password`	`"seldon"`	Password for the database root user.
`--license-key`	`""`	License key to use Synnax outside of demo mode.
`--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.
`--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: labjack, modbus, ni, opc, sequence
`--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: labjack, modbus, ni, opc, sequence
`--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`
`--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:

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 version 0.49.8

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

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 (labjack, modbus, ni, opc, sequence).
`--disable-integrations`	`[]`	Device integrations to disable (labjack, modbus, ni, opc, sequence).
`--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.

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

Requirements

Systemd Service