The spatial command line tool
Introduction
The spatial
command line tool includes a set of tools for managing and developing SpatialOS projects.
There are two categories of commands available via the spatial
command line tool: those which are specific to a
particular project, and those which are not project-specific.
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 spatial
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
) - running a local worker (
spatial local worker launch
) - checking you have the correct versions of the software you need (
spatial diagnose
)
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 spatial
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 spatial
cheat sheet (preview below).
For full reference documentation, see the spatial documentation.
Logging with spatial
spatial
outputs information to two places: to the console and to logs/spatial_<date_time>.log
.
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 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 spatial
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
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 ofDEBUG
,INFO
,WARN
, orERROR
.
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.
Using the spatial
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
spatial
CLI by runningspatial update
from the command line.Once you’ve done this, you’ll be able to work offline regardless of your SpatialOS SDK version.
Run
spatial worker build
andspatial 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.