Skip to main content

Command Line Interface

deepstream comes with a comprehensive command line interface (CLI) that lets you start or stop the server or override configuration options.

Many of these options can also be set via the configuration file, read config file documentation. for a detailed list.

Usage​

If you've installed deepstream on linux via a package manager, the deepstream command is already on your path. On Mac and Windows, you can access it through the executable, e.g. ./deepstream or deepstream.exe

For the brave souls who've got deepstream via Github or NPM instead, you can find the executable in bin/deepstream

Let's start simple:

deepstream --help

will print out all available commands:

  Usage: deepstream [command]


  Commands:

    start [options]            start a deepstream server
    info [options]             print meta information about build and runtime
    hash [options] [password]  Generate a hash from a plain text password using file auth configuration settings
    service [options] [add|remove|start|stop]  Add, remove, start or stop deepstream as a service to your operating system
    daemon [options]           start a deepstream daemon that will auto-restart on failures
    cluster [options]           start a vertical cluster of deepstream servers on each processor core

  Options:

    -h, --help     output usage information
    -V, --version  output the version number

You can pass the --help option to individual commands as well.

deepstream start​

deepstream start --help

will print all the options you can specify for the deepstream server:

  Usage: start [options]

  start a deepstream server

  Options:

    -h, --help                         output usage information
    -c, --config [file]                configuration file, parent directory will be used as prefix for other config files
    -l, --lib-dir [directory]          path where to lookup for plugins like connectors and logger
    --server-name <name>               Each server within a cluster needs a unique name
    --host <host>                      host for the HTTP/websocket server
    --port <port>                      port for the HTTP/websocket server
    --disable-auth                     Force deepstream to use "none" auth type
    --disable-permissions              Force deepstream to use "none" permissions
    --log-level <level>                Log messages with this level and above
    --colors [true|false]              Enable or disable logging with colors

You can either use the shorthand syntax with one hyphen or the long syntax with two hyphens.

All the options starting from --server-name and below will overwrite the values within your config file if. If you want to specify more options, or see the default values provided please look at the config file documentation.

--config​

If you installed it via a linux package manager it will default to /etc/deepstream. Otherwise the paths are relative to your current working directory.

--lib-dir​

If you installed it via a linux package manager it will default to /var/lib/deepstream. Otherwise the paths are relative to your current working directory.

deepstream daemon​

deepstream damemon --help

This command starts the deepstream server and monitors it for crashes, allowing it to be automatically restarted on unexpected exits.

It allows all the same commands as deepstream start

deepstream cluster​

deepstream cluster --help

This command starts a vertical cluster of deepstream servers, i.e. multiple process on the same machine that share state and act as a cluster. Defaults to one process per available core

It allows all the same commands as deepstream start

deepstream service​

deepstream service --help

  Usage: service [options] [add|remove|start|stop|status]

  Add, remove, start, stop or see the status of deepstream as a service to your operating system

  Options:

    -h, --help             output usage information
    -c, --config [file]    configuration file, parent directory will be used as prefix for other config files
    --service-name <name>  the name to register the service
    --std-out <directory>  the directory for output logs
    --std-err <directory>  the directory for error logs
    --dry-run              outputs the service file to screen

--config​

If you installed it via a linux package manager it will default to /etc/deepstream. Pass the config file you would like the service to use

--service-name​

Defaults to deepstream Allows you to create multiple services on the same machine. You would need to ensure that different ports are used to avoid clashing.

--std-out​

Specify where you would like your logs to be stored. Default to /var/log/deepstream

--std-err​

Specify where you would like your error logs to be stored. Default to /var/log/deepstream

--dry-run​

See what the config file will emit without writing it to disk. This is useful if you want to avoid running with sudo.

deepstream info​

Displays information, about deepstream's version and system architecture. If you'd like to raise an issue on Github we'd appreciate if you could paste attach it.

Output example

{
  "deepstreamVersion": "6.1.2",
  "gitRef": "b65e5230b1cedeb102d325d0ad4f568f6e3fd7d8",
  "buildTime": "Sat Apr 23 2022 02:57:49 GMT+0000 (Coordinated Universal Time)",
  "platform": "linux",
  "arch": "x64",
  "nodeVersion": "v14.18.1",
  "libs": [
    "uWebSockets.js:20.5.0"
  ]
}

deepstream hash​

This command allows you generate a hash for a plaintext password. Show the usage by appending --help to that command:

  Usage: hash [options] [password]

  Generate a hash from a plaintext password using file auth configuration settings

  Options:

    -h, --help           output usage information
    -c, --config [file]  configuration file containing file auth and hash settings