Get SpatialOS



The spatial command line tool

Note: This page covers the new version of the CLI. If you haven’t upgraded, see the guide to the new spatial commands.

The spatial command line tool incldues a set of tools for managing and developing SpatialOS projects. It notably includes commands for:


  • building workers (spatial worker build)
  • cleaning worker directories (spatial worker clean)
  • generating code to let workers interact with components (spatial worker codegen)
  • checking you have the correct versions of the software you need (spatial diagnose)
  • updating the CLI (spatial update)

Working with deployments:

  • launching local deployments (spatial local launch)
  • running a local worker (spatial local worker launch)
  • launching and interacting with deployments in the cloud (spatial cloud)
  • commands for managing a project’s deployments, snapshots, and assemblies (spatial project)

For full reference documentation, see the spatial documentation.

Logging with spatial

spatial outputs information to two places: to the console and to spatial.log (in the current working directory).

The console

By default, the console 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 file

The log file, spatial.log, shows information messages, warnings, errors, and additional debugging information. It’ll always contain all this information, regardless of the --log_level value you use in the console.

The file contains a rotation of previous logs, so some history is preserved. Each run is prefixed by ==========> and the time and date spatial was started. You can always find the latest run of the tool at the end of the file. If the file gets too big (around 16MB), it will be emptied and restarted.

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

Adding more information

You can add call stacks to lines printed to the log file with the --log_callstack_level option. This will help Support diagnose more complex issues.

For example, --log_callstack_level=warn will output additional information for each message at the warning level or above.

Changing log file location

You can change the location and name of the log file using the --log_file command line option. Set the value to the name of the file you want to use. For example:

spatial worker build --log_file=./temp/other_log_file.log

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.

spatial and network activity

During local builds and deployments, spatial 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.

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums