Reference

Using the CLI in China

To use the CLI in China, you need to add --environment=cn-production to all commands, or run a one-off command to set the environment for your computer (see Using the CLI in China).

Only follow the in-China instructions if you are located in China and deploying your game to server nodes hosted in China. You can only deploy to server nodes hosted in China if you're located in China. For more information, contact your account manager or get in touch.

spatial diagnose

Print diagnostic version information about the spatial tool and dependencies.

spatial diagnose [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial setup install-dependencies

This command attempts to install the required software dependencies for developing with the SpatialOS SDK version of the current project.

If a specific dependency is already installed but in the wrong version, a warning is issued together with recommendations on how to install the new version manually.

This command is only supported on Windows. Please use administrator PowerShell.

spatial setup install-dependencies [flags]

Options

  • --dry-run Used to check what would be installed by this command. Only outputs log messages and does not install software dependencies.
  • --force Pass --force to (re)install regardless of what might already be installed.
  • --sdk-version string Override the SpatialOS SDK version that the setup commands operate for.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial update

Update the spatial command-line tool.

Update the 'spatial' command-line tool to a specified version or, if none is specified, to the latest version.

spatial update [version] [flags]

Options

  • --rollback Roll back the 'spatial' CLI tool to the previous version.

*Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial upload

Upload local assemblies. Multiple uploads to the same assembly name in parallel can result in undefined behavior.

spatial upload <assembly name> [flags]

Options

  • --enable_pre_upload_check Run sanity checks and fixes on the assembly before uploading it. (default true)
  • --force Force upload by overwriting an existing assembly.
  • -n, --tries int Number of upload attempts to be made. (default 1)
  • --upload_only Do not remove remote artifacts that are not present locally.
  • --upload_workers int Maximum number of file uploads to be performed in parallel. (default 3)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial version

Display the version of this tool and its plugins.

spatial version [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial alpha cloud launch

Launch a deployment.

Orchestrate a new deployment to run the given code with and tag the deployment. Launching while uploading to the same assembly name in parallel can result in undefined behavior.

spatial alpha cloud launch -d <deployment name> -a <assembly name> [flags]

Options

  • -a, --assembly_name string Name of the assembly to start the deployment with (required).
  • --cluster string The cluster to create the deployment in. For example, gce-us-central1-c. Leave blank to choose automatically. For a full list of clusters, contact your account manager.
  • --cluster_region string The region to create the deployment in. Choose one of en, us, ap, or cn. Leave blank to choose automatically.
  • --deployment_description string Description for the deployment.
  • -d, --deployment_name string Name of the deployment to be started (required). Deployment names may contain alphanumerical characters and underscores, and must be 2 to 32 characters long.
  • --hide_overview_page Set flag to not open the deployment overview page.
  • --launch_config string Path to launch configuration file to start the deployment with (optional). This flag overrides any launch configuration file specified in the main project configuration file.
  • --no_history Do not create a new history. You should normally never need to specify this.
  • --runtime_version string Specify a SpatialOS Runtime version to start a deployment with (required). (Deprecated aliases: fabric_version, experimental_runtime)
  • --snapshot string Path to the snapshot file to start the deployment with (optional). This flag overrides any snapshot file path specified in the launch configuration file.
  • --tags strings Comma-delimited list of tags to attach to the new deployment.
  • --upload_timeout duration Snapshot upload timeout ('2s', '1m', etc). (default 2m0s).

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial alpha cloud upload

Upload local assemblies for new project structure.

spatial alpha cloud upload -a <assembly name> [flags]

Options

  • -a, --assembly_name string Name of the assembly to be uploaded (required). Assembly names may contain alphanumerical characters, hyphens, dots and underscores, and must be 5 to 64 characters long.
  • --force Force upload by overwriting an existing assembly.
  • -n, --tries int Number of upload attempts to be made. (default 1)
  • --upload_only Do not remove remote artifacts that are not present locally.
  • --upload_workers int Maximum number of file uploads to be performed in parallel. (default 3)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial alpha config convert

Convert an FPL format launch configuration to its SPL format equivalent. You need a SPL format launch configuration in order to start a deployment using the Platform SDK. This command is only available for FPL and in alpha.

spatial alpha config convert [flags]

Options

  • --launch_config string Deployment launch configuration file. This flag overrides any launch configuration files specified in the main project configuration file. The path can be relative to the main project configuration file's location.
  • --output_path string Name of the SPL format launch configuration file. (default spl_launch.json)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial alpha local launch

Start a SpatialOS simulation locally for flexible project layout.

Start a cloud-like SpatialOS environment which runs and manages the specified deployment configuration locally.

spatial alpha local launch [flags]

Options

  • --enable_inspector_v2 Enable serving of inspector-v2 route. (default true)
  • --enable_jvm_debugging Specifies whether to start JVM with the debugging capability.
  • --enable_pre_run_check Ensure that changes to the schema have been applied before starting a local deployment. (default true)
  • --launch_config string Path to launch configuration file to start the deployment with (optional). This flag overrides any launch configuration file specified in the main project configuration file.
  • --local_service_grpc_port uint16 Port on which the local version of Improbable's public gRPC services are started. (default 22000)
  • --local_service_http_port uint16 Port on which the local version of Improbable's public HTTP services are started. (default 21000)
  • --network_check_timeout duration Timeout for internet connection check spatial does at startup. (default 10s)
  • --runtime_log_level string The minimum log level required to display a log message in the CLI. Permitted values: debug, info, warn, error. (default "info")
  • --runtime_version string Specify a SpatialOS Runtime version to start a deployment with (required). (Deprecated aliases: fabric_version, experimental_runtime)
  • --show_internal_runtime_logs If true, all runtime logs will be displayed (including internal system logs).
  • --snapshot string Path to the snapshot file to start the deployment with (optional). This flag overrides any snapshot file path specified in the launch configuration file.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial auth login

Initialize your local credentials.

This stores a local copy of your refresh token in the following location:

  • C:\Users\<username>\AppData\Local\.improbable\oauth2\oauth2_refresh_token\ (Windows)
  • ~/.improbable/oauth2/oauth2_refresh_token (Mac/Linux)
spatial auth login [flags]

Options

  • --force Force new credentials to be obtained

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial auth logout

Clear your local credentials.

spatial auth logout [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial cloud connect external

Set up a connection to a SpatialOS Deployment from your local machine. This enables running your engine locally and connecting to a remote deployment.

spatial cloud connect external <deployment name> [flags]

Options

  • --listening_address string Network interface to bind the receptionist proxy to. (default "127.0.0.1")
  • --local_receptionist_port int Port on which the receptionist proxy will be available. (default 7777)

Options inherited from parent commands

For further information, see Options inherited from parent commands.

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation* --project_name string

spatial cloud history list

List a project's histories.

spatial cloud history list [flags]

Options

  • --from string From this date (yyyy-mm-dd). (default "2000-01-01")
  • --to string Up to and including this date (yyyy-mm-dd). (default <TODAY>)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud history snapshot create

Take a snapshot of a deployment.

spatial cloud history snapshot create <deployment_name> [flags]

Options

  • --timeout duration Snapshot request timeout ('2s', '1m', etc). (default 3m20s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud history snapshot list

List snapshots for a project within a time range. Use --from and --until to specify date range. Default lists snapshots taken on current day.

spatial cloud history snapshot list <deployment_name> [flags]

Options

  • --from string From this date (yyyy-mm-dd). (default "2000-01-01")
  • -t, --tags strings Tags used to filter available snapshots.
  • --until string Up to and including this date (yyyy-mm-dd). (default <TODAY>)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud launch

Orchestrate a new deployment to run the given code with and tag the deployment. Launching while uploading to the same assembly name in parallel can result in undefined behavior.

spatial cloud launch <assembly name> <launch configuration> <deployment name> [flags]

Options

  • --cluster string The cluster to create the deployment in. For example, gce-us-central1-c. Leave blank to choose automatically. For a full list of clusters, contact your account manager.
  • --cluster_region string The region to create the deployment in. Choose one of en, us, ap, or cn. Leave blank to choose automatically.
  • --deployment_description string Description for the deployment.
  • --hide_overview_page Set flag to not open the deployment overview page.
  • --no_history Do not create a new history. You should normally never need to specify this.
  • --runtime_version string Specify a SpatialOS Runtime version to start a deployment with (required). (Deprecated aliases: fabric_version, experimental_runtime)
  • --snapshot string Path to the snapshot to start the deployment from. (default "no snapshot")
  • --tags strings Comma-delimited list of tags to attach to the new deployment.
  • --upload_timeout duration Snapshot upload timeout ('2s', '1m', etc). (default 2m0s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud queue_size

Display how many clients are queued up for a deployment.

This command is deprecated for the China deployment environment. For information about integrating your own authentication server with SpatialOS, see Set up an authentication server without the Platform SDK.

spatial cloud queue_size <deployment name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud remaining_capacity

Display how many more clients can connect to a deployment.

This command is deprecated for the China deployment environment. For information about integrating your own authentication server with SpatialOS, see Set up an authentication server without the Platform SDK.

spatial cloud remaining_capacity <deployment name> [flags]

Options

  • --grpc_timeout duration Timeout for any grpc calls executed by this command. (default 6s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud runtime flags get

Get the value of a flag.

spatial cloud runtime flags get <deployment_name> <flag_name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud runtime flags list

List all flags of a deployment.

spatial cloud runtime flags list <deployment_name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud runtime flags set

Set the value of a flag.

spatial cloud runtime flags set <deployment_name> <flag_name> <flag_value> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud shell

Opens basic interactive shell to the worker container.

You can use this to explore the file system and run debug commands.

Supported terminals on Windows are Command Prompt and mintty (with winpty). Unsupported terminals may produce unexpected results when using special keys such as arrow keys.

spatial cloud shell [flags]

Options

  • --deployment_name string Deployment name
  • --worker_id string Worker instance ID

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud stop

Stop and bring down the deployment that is identified by the given name.

spatial cloud stop <deployment name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial cloud upload

Upload local assemblies. Multiple uploads to the same assembly name in parallel can result in undefined behavior.

spatial cloud upload <assembly name> [flags]

Options

  • --enable_pre_upload_check Run sanity checks and fixes on the assembly before uploading it. (default true)
  • --force Force upload by overwriting an existing assembly.
  • -n, --tries int Number of upload attempts to be made. (default 1)
  • --upload_only Do not remove remote artifacts that are not present locally.
  • --upload_workers int Maximum number of file uploads to be performed in parallel. (default 3)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial config get

spatial config get <config-name> [flags]

Examples

spatial config get hide-overview-page

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial config set

spatial config set <config-name> <config-value> [flags]

Examples

spatial config set ignore-updates true

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local launch

Start a cloud-like SpatialOS environment which runs and manages the specified deployment configuration locally. Defaults to using default_launch.json in the root of your project. If default_launch.json doesn't exist, looks for default_launch.pb.json in the root of your project.

spatial local launch [launch_configuration] [flags]

Options

  • --enable_inspector_v2 Enable serving of inspector-v2 route. (default true)
  • --enable_jvm_debugging Specifies whether to start JVM with the debugging capability.
  • --enable_pre_run_check Ensure that changes to the schema have been applied before starting a local deployment. (default true)
  • --local_service_grpc_port uint16 Port on which the local version of Improbable's public gRPC services are started. (default 22000)
  • --local_service_http_port uint16 Port on which the local version of Improbable's public HTTP services are started. (default 21000)
  • --network_check_timeout duration Timeout for internet connection check spatial does at startup. (default 10s)
  • --runtime_log_level string The minimum log level required to display a log message in the CLI. Permitted values: debug, info, warn, error. (default "info")
  • --runtime_version string Specify a SpatialOS Runtime version to start a deployment with (required). (Deprecated aliases: fabric_version, experimental_runtime)
  • --show_internal_runtime_logs If true, all runtime logs will be displayed (including internal system logs).
  • --snapshot string Relative path to a snapshot to be used when launching. If this flag is not specified and no legacy snapshot flags are set in your deployment configuration, SpatialOS attempts to launch using the default snapshot snapshots/default.snapshot.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local worker-flag get

Gets a value of a given worker flag for a local deployment. Command logs message with flag value or error details in case of an exception.

spatial local worker-flag get <worker_type> <flag_name> [flags]

Options

  • --local_service_grpc_port uint16 Port on which the local version of Improbable's public gRPC services are running. (default 22000)
  • --project string Project name - required if running this command outside of a SpatialOS project directory. If this flag is not specified and the command is run in a SpatialOS directory, projectName will be taken from spatialos.json.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local worker-flag list

Lists the worker flags of given worker type in a local deployment. For each flag it will print '<flag name>=<flag value> using info level logging.'

spatial local worker-flag list <worker_type> [flags]

Options

  • --local_service_grpc_port uint16 Port on which the local version of Improbable's public gRPC services are running. (default 22000)
  • --project string Project name - required if running this command outside of a SpatialOS project directory. If this flag is not specified and the command is run in a SpatialOS directory, projectName will be taken from spatialos.json.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local worker-flag set

Sets a value of a given worker flag for a local deployment. Command logs a message confirming setting of a flag with exit code 0 when the flag was set successfully or error details in case of an exception.

spatial local worker-flag set <worker_type> <flag_name> <value> [flags]

Options

  • --local_service_grpc_port uint16 Port on which the local version of Improbable's public gRPC services are running. (default 22000)
  • --project string Project name - required if running this command outside of a SpatialOS project directory. If this flag is not specified and the command is run in a SpatialOS directory, projectName will be taken from spatialos.json.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local worker launch

Launches an external worker. This command launches the specified launch_config for the specified worker for the current operating system. You can run this command with additional command line arguments, launch_config_args, which are passed directly to the command.

See the SpatialOS documentation for more information about how to configure launch configurations.

spatial local worker launch <worker> <launch_config> [-- <launch_config_args>] [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial local worker replace

Issues a request to replace a worker instance in the load balancing system of the locally-running deployment.

If you supply the ID of a 'replacing' worker instance that you want to take over some work, and the ID of an 'existing' worker instance whose work the replacing worker instance should take over, the load balancer will internally remap existing authority from the existing worker instance to the replacing worker instance.

If the 'replacing' worker is already connected, it will be assigned the 'existing' worker’s authority immediately. If the ‘replacing’ worker is not connected, it will receive the authority of the ‘existing’ worker upon connection to the deployment, but the 'existing' worker will lose authority immediately.

spatial local worker replace [flags]

Options

  • --existing_worker_id string The worker ID of a worker instance already connected to the deployment, whose load-balancing assignments should be taken over by the replacing worker instance
  • --local_service_grpc_port uint16 The port on which the local version of Improbable's public gRPC services are running. (default 22000)
  • --replacing_worker_id string The worker ID of the worker instance that should take over from the existing worker. The replacing worker instance can be connected to the deployment already, but it doesn't have to be.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial package clean

Cleans the contents of worker package output folders.

spatial package clean [options] [flags]

Options

  • --package_file string The path to the file that specifies the packages to unpack (default spatialos_worker_packages.json)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial package get

Downloads a package with id (type, name, version) from Improbable's package service with local caching and saves it to the specified file location or saves the unzipped files to the specified directory when the --unzip flag is provided.

spatial package get <type> <name> <version> <file|directory> [flags]

Options

  • -f, --force Forces overwriting of the package file even if it already exists.
  • --unzip Unzip the downloaded package. The specified directory will be created if it does not exist.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial package unpack-to

Installs a single versioned worker package into the specified folder.

The target folder should not contain any user-created content, since it may be deleted and recreated as part of the unpacking process.

spatial package unpack-to <package-type> <package-name> <destination-folder> [flags]

Options

  • --force If true, package contents are always extracted, even if none of the packages have changed or not in a SpatialOS project directory.
  • --version string Optional version of the package. If not specified, the current SpatialOS SDK version is used.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial package unpack

Installs versioned worker packages according to spatialos_worker_packages.json.

The target paths specified in spatialos_worker_packages.json should not contain any user-created content, since it may be deleted and recreated as part of the unpacking process.

For more information about this file's format, see the SpatialOS documentation.

Any necessary folder structures will be created in the output folder.

spatial package unpack [flags]

Options

  • --force If true, package contents are always extracted, even if none of the packages have changed.
  • --package_file string The path to the file that specifies the packages to unpack (default spatialos_worker_packages.json)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial project assembly artifact

Commands for managing artifacts within a project's assembly.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly delete

Deletes the assembly in the specified project.

spatial project assembly delete <assembly_name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly download

Downloads a full assembly for a project. It is downloaded to a provided directory, build/assembly by default.

spatial project assembly download <assembly name> [output directory] [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly list

Lists the assemblies in the project.

spatial project assembly list [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly worker delete

Delete a worker assembly

spatial project assembly worker delete [flags]

Options

  • --assembly string Name of the assembly that contains the worker to be deleted.
  • --name string Name of the worker to delete.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly worker get

Prints out the details of a worker assembly

spatial project assembly worker get [flags]

Options

  • --assembly string Name of the assembly that contains the worker to retrieve information for.
  • --name string Name of the worker to retrieve information for.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project assembly worker list

Print out the list of worker assemblies for the given assembly name

spatial project assembly worker list [flags]

Options

  • --assembly string Name of the assembly to list worker information for.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project auth dev-auth-token create

Create a DevelopmentAuthenticationToken

spatial project auth dev-auth-token create [flags]

Options

  • --description string Description of the created token (required). The maximum length is 200 characters.
  • --lifetime duration Lifetime of the created token expressed as a sequence of values with time units (eg. 1h30m). Available time units are h(ours), m(inutes) and s(econds). The maximum value is 90 days (2160h). (default 30 days (720h))

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project auth dev-auth-token expire

Expire a DevelopmentAuthenticationToken. You can undo this operation by extending the lifetime of an expired DAT using the update command. Expired DATs are permanently deleted after one week.

spatial project auth dev-auth-token expire [flags]

Options

  • --id string The token ID (required).

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project auth dev-auth-token get

Retrieve a DevelopmentAuthenticationToken.

spatial project auth dev-auth-token get [flags]

Options

  • --id string The token ID (required).

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project auth dev-auth-token list

Retrieve the DevelopmentAuthenticationTokens for a project.

spatial project auth dev-auth-token list [flags]

Options

  • --include_expired Include expired tokens in the results.
  • --limit int32 Maximum number of returned results. (default 20)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project auth dev-auth-token update

Update a DevelopmentAuthenticationToken description and/or expiry time.

spatial project auth dev-auth-token update [flags]

Options

  • --id string The token ID (required).
  • --updated_description string Updated description for the token. The maximum length is 200 characters.
  • --updated_lifetime duration Updated lifetime for the token. The maximum value is 90 days, starting from the current day and time.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment launch

Orchestrate a new deployment to run the given code with and tag the deployment. Launching while uploading to the same assembly name in parallel can result in undefined behavior.

spatial project deployment launch <assembly name> <launch configuration> <deployment name> [flags]

Options

  • --cluster string The cluster to create the deployment in. For example, gce-us-central1-c. Leave blank to choose automatically. For a full list of clusters, contact your account manager.
  • --cluster_region string The region to create the deployment in. Choose one of en, us, ap, or cn. Leave blank to choose automatically.
  • --deployment_description string Description for the deployment.
  • --hide_overview_page Set flag to not open the deployment overview page.
  • --no_history Do not create a new history. You should normally never need to specify this.
  • --runtime_version string Specify a SpatialOS Runtime version to start a deployment with (required). (Deprecated aliases: fabric_version, experimental_runtime)
  • --snapshot string Path to the snapshot to start the deployment from. (default no snapshot)
  • --tags strings Comma-delimited list of tags to attach to the new deployment.
  • --upload_timeout duration Snapshot upload timeout ('2s', '1m', etc). (default 2m0s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment list live

List the live deployments for a project.

spatial project deployment list live [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment list stopped

List the stopped deployments for a project.

spatial project deployment list stopped <project name> [flags]

Options

  • --after string Using the "2 Jan 2006 15:04" format, only display deployments stopped after this time. If not specified, defaults to 3 days before --before.
  • --before string Using the "2 Jan 2006 15:04" format, only display deployments stopped before this time. If not specified, defaults to now.
  • --deployment string Only display stopped deployments with this name.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment stop

Stop and bring down the deployment that is identified by the given name.

spatial project deployment stop <deployment name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment tags add

Add a tag to a deployment.

spatial project deployment tags add <deployment name> <tag name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment tags delete

Delete a tag from a deployment.

spatial project deployment tags delete <deployment name> <tag name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment tags list

List all the tags for a deployment.

spatial project deployment tags list <deployment name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker-flag delete

Deletes a worker flag from the given deployment.

spatial project deployment worker-flag delete <project name> <deployment name> <worker type> <flag name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker-flag get

Gets the value of a worker flag from the given deployment.

spatial project deployment worker-flag get <project name> <deployment name> <worker type> <flag name> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker-flag list

Lists worker flags for the given deployment.

spatial project deployment worker-flag list <project name> <deployment name> <worker type> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker-flag set

Sets the given deployment's flag to the given value.

spatial project deployment worker-flag set <project name> <deployment name> <worker type> <flag name> <flag value> [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker port-forward

Connects to the worker on the specified port.

By default, the Spatial CLI will listen on the same port.

spatial project deployment worker port-forward -d <deployment_name> -w <worker_id> -p <port> [-l listenPort] [flags]

Options

  • -d, --deployment_name string Deployment name
  • -l, --listen_port uint16 Port to listen on locally
  • -p, --port uint16 Port on worker to connect to (default 80)
  • -w, --worker_id string Worker instance ID

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation* --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker replace

Issues a request to replace a worker instance in the load balancing system of the cloud-running deployment.

If you supply the ID of a 'replacing' worker instance that you want to take over some work, and the ID of an 'existing' worker instance whose work the replacing worker instance should take over, the load balancer will internally remap existing authority from the existing worker instance to the replacing worker instance.

If the ‘replacing’ worker is already connected, it will be assigned the ‘existing’ worker’s authority immediately. If the ‘replacing’ worker is not connected, it will receive the authority of the ‘existing’ worker upon connection to the deployment, but the ‘existing’ worker will lose authority immediately.

spatial project deployment worker replace [flags]

Options

  • --deployment_name string The name of the cloud-running deployment.
  • --existing_worker_id string The worker ID of a worker instance already connected to the deployment, whose load-balancing assignments should be taken over by the replacing worker instance.
  • --replacing_worker_id string The worker ID of the worker instance that should take over from the existing worker. The replacing worker instance can be connected to the deployment already, but it doesn't have to be.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project deployment worker shell

Opens basic interactive shell to the worker container.

You can use this to explore the file system and run debug commands.

Supported terminals on Windows are Command Prompt and mintty (with winpty). Unsupported terminals may produce unexpected results when using special keys such as arrow keys.

spatial project deployment worker shell [flags]

Options

  • --deployment_name string Deployment name
  • --worker_id string Worker instance ID

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history clone

Clone history with a snapshot.

spatial project history clone <old_history> <new_history> [flags]

Options

  • -k, --keep_tags Keep the existing tags. (default true)
  • -i, --snapshot int The snapshot ID of the history to start the new history from. If this flag is not specified, the most recent snapshot from the current history with the tags specified via the 'tags' flag is used.
  • -t, --tags strings If the 'snapshot' flag is specified, this specifies the tags the snapshot will have in the new history. If the 'snapshot' flag is not specified, this specifies the tags used to find the latest snapshot in the old history.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history create

Create a new history with the specified name and upload a snapshot to that history.

spatial project history create <history_name> <path_to_snapshot> [flags]

Options

  • -t, --tags strings Tags for the snapshot.
  • --upload_timeout duration Sets the timeout for snapshot uploads ('2s', '1m', etc). (default 2m0s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history delete

Deletes the history with the specified name and all associated snapshots of the history.

spatial project history delete <history> [flags]

Options

  • --force Delete the history without prompting for confirmation.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history list

List a project's histories.

spatial project history list [flags]

Options

  • --from string From this date (yyyy-mm-dd). (default "2000-01-01")
  • --to string Up to and including this date (yyyy-mm-dd). (default <TODAY>)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history snapshot convert

Converts a binary snapshot file to a text snapshot file, or vice versa.

spatial project history snapshot convert [flags]

Options

  • -i, --input string Input filename.
    • --input-format string Input format, 'binary' or 'text'.
  • -o, --output string Output filename.
    • --output-format string Output format, 'binary' or 'text'.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history snapshot create

Take a snapshot.

spatial project history snapshot create <deployment_name> [flags]

Options

  • --timeout duration Timeout for the snapshot request. (default 3m20s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history snapshot download

Download a snapshot from a history. If <snapshot_id> is 'latest' then the most recent snapshot is downloaded.

spatial project history snapshot download <deployment_name> <snapshot_id> <output_file> [flags]

Options

  • -t, --tags strings Tags used to filter available snapshots.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history snapshot list

List snapshots for a project within a time range. Use –from and –until to specify date range. Default lists snapshots taken on current day.

spatial project history snapshot list <deployment_name> [flags]

Options

  • --from string From this date (yyyy-mm-dd). (default "2000-01-01")
  • -t, --tags strings Tags used to filter available snapshots.
  • --until string Up to and including this date (yyyy-mm-dd). (default <TODAY>)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial project history snapshot upload

Upload a snapshot to the deployment.

spatial project history snapshot upload <deployment_name> <snapshot> [flags]

Options

  • -t, --tags strings Tags for the snapshot.
  • --upload_timeout duration Timeout for snapshot uploads. (default 2m0s)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation
  • --project_name string

For further information, see Options inherited from parent commands.


spatial runtime list-supported-versions

Lists currently supported versions of the SpatialOS Runtime.

spatial runtime list-supported-versions [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial schema check

Checks that schema doesn't contain errors.

spatial schema check [flags]

Options

  • -d, --dependency strings Library directory containing .schema files. Like --input, but no code is generated for these files. Can be specified multiple times. (default [[]])
  • -i, --input strings Input directory containing .schema files. Can be specified multiple times. (default [[${PROJECT_ROOT}/schema," [${PROJECT_ROOT}/build/dependencies/schema/${DEPENDENCY_NAME}"," ...]]"])
  • -R, --repository strings Repository directory containing subdirectories with schema dependencies. Equivalent to adding --dependency for each immediate subdirectory of the specified repository directory. Can be specified multiple times. (default [[]])
  • --version string Spatial SDK version to download the schema compiler executable from.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial schema clean

Cleans the provided directories and cache path.

spatial schema clean [flags]

Options

  • --cachePath string Path to store intermediate data in. (default .spatialos/schema_codegen_cache)

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial schema generate

Generates worker-specific code from the schema.

Use the --language flag to generate code for a specific language.

The input directory is searched for .schema files, which should define a (possibly partial) entity component schema in the SpatialOS schema language.

The .schema files are compiled via an intermediate protobuf representation to produce API code that can be used by workers and behaviours to create, read and write the state of entities in a SpatialOS simulation.

For more information on defining schemas, see the SpatialOS documentation.

spatial schema generate [flags]

Options

  • --cachePath string Path to store intermediate data in. (default .spatialos/schema_codegen_cache)
  • -d, --dependency strings Library directory containing .schema files. Like --input, but no code is generated for these files. Can be specified multiple times. (default [[]])
  • --force Regenerate all code, even if sources haven't changed.
  • -i, --input strings Input directory containing .schema files. Can be specified multiple times. (default [[${PROJECT_ROOT}/schema," [${PROJECT_ROOT}/build/dependencies/schema/${DEPENDENCY_NAME}"," ...]]"])
  • -L, --language string Language to generate code for. Supported values are (ast_proto,ast_json,cpp,csharp,java,proto). To generate code for different languages into different locations, run the command multiple times. The language flag is required.
  • -o, --output string Output directory for generated code. The directory will be fully cleaned before code generation.
  • -R, --repository strings Repository directory containing subdirectories with schema dependencies. Equivalent to adding --dependency for each immediate subdirectory of the specified repository directory. Can be specified multiple times. (default [[]])
  • --version string Spatial SDK version to download the schema compiler executable from.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial schema print

Prints all components defined in schema and dependencies.

spatial schema print [flags]

Options

  • -d, --dependency strings Library directory containing .schema files. Like --input, but no code is generated for these files. Can be specified multiple times. (default [[]])
  • -i, --input strings Input directory containing .schema files. Can be specified multiple times. (default [[${PROJECT_ROOT}/schema," [${PROJECT_ROOT}/build/dependencies/schema/${DEPENDENCY_NAME}"," ...]]"])
  • -R, --repository strings Repository directory containing subdirectories with schema dependencies. Equivalent to adding --dependency for each immediate subdirectory of the specified repository directory. Can be specified multiple times. (default [[]])
  • --version string Spatial SDK version to download the schema compiler executable from.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial service start

Start the local API service.

spatial service start [flags]

Options

  • --port int The port to run the local API service on. (default 9876)
  • --runtime_ip string If set, the SpatialOS runtime will bind to this IP instead of the default for the system (normally localhost). Only required if you want to connect a remote client to your local deployment.
  • --version string Specifies which version of the local API service to start (default "latest")

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial service status

Check the status of the local API service.

spatial service status [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial service stop

Stop the local API service.

spatial service stop [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial worker build

For each worker, runs the 'Build' task, which is specified, either directly or indirectly, in the worker's spatialos.<worker_name>.worker.json.

By default, this task will perform the steps necessary to build a standalone version of each worker, and normally runs 'Codegen' as its first step.

See the SpatialOS documentation for more information about customising this process.

Default behaviour and specifying worker names:

  • If run from the root of the application with no arguments, all workers will be affected.
  • If run from within a worker's directory with no arguments, only that worker will be affected.
  • If worker names are specified on the command line, only those workers will be affected, regardless of where it is run from.
spatial worker build [worker names] [flags]

Options

  • -t, --target string Specify which target to build. Builds all targets when not specified.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial worker clean

For each worker, runs the 'Clean' task, which is specified, either directly or indirectly, in the worker's spatialos.<worker_name>.worker.json.

By default, this task will perform the steps necessary to clean up the output of the 'Build' step.

See the SpatialOS documentation for more information about customising this process.

Default behaviour and specifying worker names:

  • If run from the root of the application with no arguments, all workers will be affected.
  • If run from within a worker's directory with no arguments, only that worker will be affected.
  • If worker names are specified on the command line, only those workers will be affected, regardless of where it is run from.
spatial worker clean [worker names] [flags]

Options

  • -t, --target string Specify which target to build. Builds all targets when not specified.

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.


spatial worker codegen

For each worker, runs the 'Codegen' task, which is specified, either directly or indirectly, in the worker's spatialos.<worker_name>.worker.json.

By default, this task processes the application's schema and generates code.

See the SpatialOS documentation for more information about customising this process.

Default behaviour and specifying worker names:

  • If run from the root of the application with no arguments, all workers will be affected.
  • If run from within a worker's directory with no arguments, only that worker will be affected.
  • If worker names are specified on the command line, only those workers will be affected, regardless of where it is run from.
spatial worker codegen [worker names] [flags]

Options inherited from parent commands

  • --json_output
  • --log_directory string
  • --log_level string
  • --main_config string
  • --no_animation

For further information, see Options inherited from parent commands.

All options inherited from parent commands

See individual commands for which options they inherit.

--option Definition
json_output Print output in JSON format. Useful when you need to parse the Spatial CLI output.
log_directory string Sets the directory log files will be created in. If not specified, this is set to <project_root>/logs when inside a project directory and logging is disabled when outside a project directory.
log_level string Sets the log level. Available log levels: debug, info, warning, error, fatal, or panic.
main_config string The path to your project's main configuration file (usually called spatialos.json)
no_animation Disable dynamic output elements such as the spinner, progress bars, etc.
project_name string This flag overrides the project name given in the spatialos.json file of the current SpatialOS project (if there is one).

Updated 2 months ago


Reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.