The SpatialOS CLI
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 (
- launching and interacting with deployments in the cloud (
- commands for managing a project’s deployments, snapshots, and assemblies (
For a quick reference to the commands, see the SpatialOS CLI cheat sheet (preview below).
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
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
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=valuepairs, 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_animationflag. 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:
The logs have entries of levels Info, Warning, and Error. Roughly, these mean:
These always indicate something going wrong. A single log entry of this type should be grounds for concern and should be investigated and resolved.
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.
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
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:
Make sure you have the latest version of the SpatialOS CLI by running
spatial updatefrom the command line.
Once you’ve done this, you’ll be able to work offline regardless of your SpatialOS SDK version.
spatial worker buildand
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.