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

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:

1. Make sure you have the latest version of the spatial 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