These are the docs for 13.8, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

The SpatialOS CLI


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).

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)

Cheat sheet

For a quick reference to the commands, see the SpatialOS CLI cheat sheet (preview below). spatial cheat sheet

For full reference documentation, see the spatial documentation.

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:

    Example CLI color output

  • 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:

    Example CLI non-interactive output

  • 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:

    Example CLI JSON output

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.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums