The SpatialOS CLI is a set of commands for managing and developing SpatialOS projects. You need to install it before you can use the Worker SDK and the GDKs for Unreal and Unity.


If you've followed the tools installation guide (Windows/Mac/Linux) you'll already have the CLI.

Otherwise, you can set up the CLI manually (Windows/Mac) or using a package manager (Windows/Mac).

Using the CLI in China

To use the CLI in China, you must either:

  • add --environment=cn-production to all commands, or
  • run spatial config set default-environment cn-production once, from any directory. This sets the environment for your computer, so you don’t need to specify it with every command. You can override this for a particular command only by specifying the production environment, which is the default environment outside of China. To do this, specify --environment=production for that command.

In-China instructions

Only follow the in-China instructions if you are located in China and deploying your game to server nodes hosted in China. You can only deploy to server nodes hosted in China if you're located in China. For more information, contact your account manager or get in touch.

Project-specific commands

These commands are specific to a particular project. You must run them from within a SpatialOS project directory.

Examples of project-specific commands:

  • building workers (spatial worker build)
  • cleaning worker directories and the project root folder (spatial worker clean)
  • generating code to let workers interact with components (spatial worker codegen)

Commands not specific to a project

These commands are not specific to a particular project. You don't need to run them from within a SpatialOS project directory.

Examples of commands that are not project-specific:

  • updating the CLI (spatial update)
  • launching and interacting with deployments in the cloud (spatial cloud)
  • commands for managing a project's deployments, snapshots, and assemblies (spatial project)

Logging with the SpatialOS CLI

The SpatialOS CLI outputs information to two places: to the console and to logs/spatial_<date_time>.log.

The console output

By default, your terminal output shows information messages, warnings and errors. You can increase or decrease the amount of information shown in the console by adding the --log_level option.

For example, use --log_level=warn to show only warnings and errors in the console.

The log files

The log files (for example logs/spatial_<date_time>.log) show information messages, warnings, errors, and additional debugging information.

They'll always contain all this information, regardless of the --log_level value you use in the console. Each file contains all the logs for a given SpatialOS CLI invocation. We keep the 20 most recent log files.

If you ask on the forums about a problem, make sure you send your log file along with your question.

Changing log file location

You can change the location of the log files using the --log_directory command line option. Set the value to be the path to the directory you want to use. For example:

spatial worker build --log_directory=./temp

Selecting the logs output format

You can enable one of the following output modes to change the format that the logs are displayed in:

  • Default output mode: This is a human-readable mode including colors and animated elements such as progress bars. This mode is active by default when you run commands manually in a supported terminal. For example:
  • Non-interactive mode: This mode formats the output as a list of simple key=value pairs, which can be easily digested by a raw logs database, such as Logstash.
    In this mode, there are no colors or animated elements. This mode is activated automatically when the SpatialOS CLI is run programmatically by another program. You can force this mode by passing the --no_animation flag. For example:
  • JSON output mode: This mode forces the output in a JSON format, one JSON object per line. In this mode, there are no colors or animated elements. You can activate this mode by passing the --json_output flag. For example:

Interpreting logs

The logs have entries of levels Info, Warning, and Error. Roughly, these mean:

  • Error
    These always indicate something going wrong. A single log entry of this type should be grounds for concern and should be investigated and resolved.

  • Warning
    These indicate that, possibly temporarily, the application was in an unexpected state. However, the application is intended to recover from these states autonomously. As such, warnings are only cause for concern if they are sustained over time, or if they occur together with errors.

  • Info
    These don’t indicate that anything is going wrong and shouldn't be cause for concern. By default, these aren't shown when running locally. You can turn the log level up or down by passing -DFABRIC_LOG_LEVEL=<level> as a JVM argument when running locally, where <level> is one of DEBUG, INFO, WARN, or ERROR.

SpatialOS CLI and network activity

During local builds and deployments, the SpatialOS CLI communicates with the Improbable servers. This communication consists of three things:

  • Authorisation: Checking that users are using the platform from authorised accounts. This is the step that opens a web page. Once checked, authorisation lasts for a few hours.
  • Updates: Checking for updates to the underlying infrastructure, which is responsible for starting and running local deployments. These updates are separate from the SDK version (specified in spatialos.json). Currently, the build will fail if this can't complete.
  • Logging: Logging to help us understand how people are using the platform. This is done in the background while the task is running, and won't stop the task completing.

For more information, see Network settings.

Using the SpatialOS CLI offline for local projects

You can use spatial worker build and spatial local launch offline. This means you can iterate on local projects without needing an internet connection.

To set this up:

  1. Make sure you have the latest version of the SpatialOS CLI by running spatial update from the command line. Once you’ve done this, you’ll be able to work offline regardless of your SpatialOS SDK version.
  2. Run spatial worker build and spatial local launch (while online) for each project that you want to work on offline. This makes sure you have all the required dependencies before going offline. You’ll need to repeat this if you change your SpatialOS SDK version, or if you update your launch configuration file.

You should now be able to run spatial worker build and spatial local launch offline.

Unsupported usage patterns

The following usage patterns are unsupported and may result in undefined behavior.

  • Uploading multiple assemblies to the same assembly name in parallel using spatial cloud upload.
  • Launching a cloud deployment (spatial cloud launch) and uploading (spatial cloud upload) to the same assembly name in parallel.

Updated about a year ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.