The command line tool is provided as a convenience for interacting with the Unity Simulation API. All of the commands exposed by the CLI are composed from calls to the API (see API docs). This document explains the syntax and function of each command.
Generally the format of the commands follows the usim <action> <target> format with additional options for some commands.
Many of the following commands use these arguments.
| Parameter | Description |
|---|---|
project-id |
A Unity project ID, example format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
filepath |
Full path to a file (to upload) |
built-player-dir |
The directory where a build generated by the Unity Editor is located |
build-id |
A 7-character Simulation Build ID |
app-param-id |
A 7-character Application Parameter ID |
run-definition-id |
A 7-character Run Definition ID |
run-execution-id |
A 7-character Run Execution ID |
Initiates the oauth flow to retrieve your authentication token.
Uses the locally stored refresh token to retrieve an updated authentication token.
Prints the locally stored authentication information. Useful for retrieving your access-token for direct API calls. See also: how-to doc.
Prints out the Unity projects associated with your Unity account.
Prints out more details of the Unity project ID that is provided.
Required arguments:
<project-id>
The Unity Simulation service operates against a single project at a time. Requests will be made against the project activated by this command.
Deactivating a project will result in having no active project. Note other commands requiring an active project will cease to function. Use activate project to activate a project.
Prints out a list of valid system parameters to be included in a run definition.
Prints out the application parameters that have been uploaded in the active project.
Uploads the specified file as an application parameter. The resulting app-param-id is used in a run definition.
Required arguments:
<filepath>
Downloads the application parameter file for the specified app-param-id.
Required arguments:
<app-param-id>
Optional Arguments:
--save-in=<outdir> where outdir is the directory to save the downloaded application parameter file.
Submits a request to delete the application parameter file for the specified app-param-id.
Note: run-definitions referencing the specified app-param-id will no longer be executable.
Required arguments:
<app-param-id>
Prints out the simulation builds that have been uploaded in the active project.
Zips the Unity simulation build found at the specified directory in the format expected by the Unity Simulation service.
Required arguments:
<built-player-dir>
Optional arguments:
<output-file-name> where output-file-name is the desired filename to save the output .zip file.
Uploads a zipped Unity simulation build file found at the specified path. The resulting build-id is used in a run definition.
Required arguments:
<filepath>
Downloads the Unity simulation build for the specified build-id.
Required arguments:
<build-id>
Optional arguments:
--save-in=<outdir> where outdir is the directory to save the downloaded build.
Submits a request to delete the Unity simulation build for the specified build-id.
Note: run-definitions referencing the specified build-id will no longer be executable.
Required arguments:
<build-id>
Prints the run definitions that have been uploaded in the active project. The executions of each run-definiton are also printed if present.
Prints the details of a run definition for the specified run-definition-id.
Required arguments:
<run-definition-id>
Proceeds through a sequence of steps to generate and upload a run-definition. Existing Unity simulation builds and application parameters for the active project are presented as options.
Uploads a run definition file found at the specified path.
Required arguments:
<filepath>
Initiates a run execution of the run definition for the specified run-definition-id.
Required arguments:
<run-definition-id>
Submits a request to delete the run definition for the specified run-definition-id.
Metadata for this run-definition and its executions as well as the data generated by the respective simulations will no longer be accessible.
Required arguments:
<run-definition-id>
Prints a summary of the status and progress of the run-execution for the specified run-execution-id.
Required arguments:
<run-execution-id>
Prints a detailed status of the simulation instances for the specified run-execution-id.
Required arguments:
<run-execution-id>
Optional arguments:
--states=<states> Simulation instance states to filter on. Where states is a sequence of comma separate values from the following choices:
all,ok,failed,not-run,pending,in-progress
(Note: Defaults to all)
-s, --short Prints only the status of the simulation run-execution.
--logs-arg Convenience flag to use in conjunction with the logs command. Prints out a special column that includes the execution-id, app-param-id, and instance-id to submit to the logs command.
Submits a cancellation request for the specified run-execution-id.
Required arguments:
<run-execution-id>
Submits a request to delete the metadata containing details of the run-execution and all data files generated by the the Unity simulation run-execution for the specified run-execution-id.
Required arguments:
<run-execution-id>
Optional arguments:
--data-only Metadata for this run-execution will be retained. Only the generated data files will be deleted.
Downloads a manifest in CSV format containing links to data files generated by the Unity simulation run-execution.
Required arguments:
<run-execution-id>
Optional arguments:
--expires=<expires-seconds>
--save-in=<outdir> where outdir is the directory to save the downloaded manifest.
Inspect the logs of a Unity Simulation run-execution instance.
Required arguments:
<run-execution-id>
<app-param-id>
<instance-id>
Optional arguments:
--count=<count> Where count is the number of log pages to retrieve. (Note: Defaults to 12)
--head If this flag is present, the count value begins at the first page and counts up, otherwise counts in reverse from the last page.