CLI Client
Managing versions
Contents
The version command
Using the version command allows you to manage your Scalable Pixel Streaming versions across one or more installations of Scalable Pixel Streaming.
Commands
The following sub-commands are available for the version command:
create- Creates a new Version of an Applicationdelete- Deletes an existing Version of an Applicationlist- Lists all Application versions
Flags
The following flags are available for the version command:
-h, --help- print out help forversioncommand-s, --skeleton- Output the Version configuration JSON template--config- allow overriding the location that the configuration file is loaded from
The --skeleton flag
For a complete reference to the version JSON payload see the Scalable Pixel Streaming REST API documentation.
The --skeleton command allows retrieval of the version JSON payload template. This is useful if your version management needs are more involved that what the pre-defined flags of the CLI tool offer.
You can retrieve a valid version JSON payload template from running the following command:
sps-client version --skeleton
The above command will output a full JSON payload template for a version. The version JSON payload can be saved to a file to be modified and use with the various other version commands.
An example of a JSON version payload
{
"buildOptions": {
"credentials": {
"password": "",
"registry": "",
"username": ""
},
"input": {
"containerTag": "",
"type": "imageTag"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "",
"runtimeOptions": {
"args": [],
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": []
},
"turnServer": {
"enable": true
}
}
Using the version create command
To create a version using the version create command can be achieved multiple ways depending on your situation
- Supplying the relevant flags, including the
--nameand--applicationflags using a private container- This step requires the use of registry credentials to push your container image
- Supplying the relevant flags, including the
--nameand--applicationflags using a public container - Using a file containing the JSON payload of your Version with the
--filepathflag using a private container- This step requires the use of registry credentials to push your container image
- Using a file containing the JSON payload of your Version with the
--filepathflag using a public container - Supplying a compressed zip archive of your application (AWS only)
Creating a version using the --name and --application flags from a container
This step assumes you already have your application available in container format. If you do not already have this, refer to the documentation for the Image Builder Tool.
Using a public container
To create a version using the --name and --application flags from a public container, run the following command:
sps-client version create --name v1 --application myapp --tag <registry/repo/image:tag>
Flags explained
--tag- The container image tag used to create a version. Input in this format: registry/username/repository-name:imagetag
If the creation of the version v1 for the application myapp is successful, you should receive output in the form of JSON describing your newly created version. The output should look similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 200,
"status": "200 OK",
"response": {
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"timeCreated": "2023-08-14 06:25:17 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:25:17 +0000 UTC",
"turnServer": {
"enable": true
}
}
}
Using a private container
To create a version using the --name and --application flags from a private container, run the following command:
sps-client version create --name v1--application myapp --tag <registry/repo/image:tag> --registry <registry> --username <username> --password <password>
Flags explained
--tag- The container image tag used to create a version. Input in this format: registry/username/repository-name:imagetag--registry- The container registry where the image tag is stored (e.g. if using DockerHub this would behttps://index.docker.io/v1/)--username- The username for accessing the container registry--password- The password for accessing the container registry
If the creation of the version v1 for the application myapp is successful, you should receive output in the form of JSON describing your newly created version. The output should look similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 200,
"status": "200 OK",
"response": {
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"timeCreated": "2023-08-14 06:25:17 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:25:17 +0000 UTC",
"turnServer": {
"enable": true
}
}
}
If a version named v1 for the application myapp already exists, you should receive output similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 500,
"status": "500 Internal Server Error",
"response": "scalablepixelstreamingversions.sps.tensorworks.com.au \"myapp-v1\" already exists"
}
There are a range of option flags that can be associated with the version create command, for example, if you wanted to disable the TURN server that is deployed by default:
sps-client version create --name v1 --application myapp --tag <registry/repo/image:tag> --disable-turn-server
Creating a version using the --filepath and --application flags
The --filepath flag can be used in combination with other version create flags. The flags supplied as part of the command will take precedence over values from the JSON file
The --application flag is mandatory whether you are using the --filepath flag or not. Using the --filepath flag requires that you have a JSON file path to feed into this flag. The file should consist of a valid version JSON payload. See the --skeleton flag for information on how to obtain the version JSON payload.
Using a public container
Your version JSON payload does not need to be a complete JSON object. The following version JSON payload is valid when using a public container, the rest of the fields will be filled in by the server defaults:
{
"name": "v1",
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag"
}
}
}
To create a version using the --filepath flag, run the following command, changing the <path/to/version.json> with your file path:
sps-client version create --application myapp --filepath <path/to/version.json>
Using a private container
If you do not wish to store your credentials inside the version JSON payload, they can optionally be supplied using any or all of the --registry, --username and --password flags. For example, you can choose to store your registry and username inside the file, and just provide the password using the --password flag.
Your version JSON payload does not need to be a complete JSON object. The following version JSON payload is valid when using a private container, replacing <registry>, <username> and <password> with your own values, the rest of the fields will be filled in by the server defaults:
{
"name": "v1",
"buildOptions": {
"credentials": {
"registry": "<registry>",
"username": "<username>",
"password": "<password>"
},
"input": {
"containerTag": "registry/repo/image:tag"
}
}
}
To create a version using the --filepath flag, run the following command, changing the <path/to/version.json> with your file path:
sps-client version create --application myapp --filepath <path/to/version.json>
Windows example
An example of using the --filepath flag on Windows:
sps-client version create --application myapp --filepath "C:\Users\Example\app.json"
Linux example
An example of using the --filepath flag on Linux:
sps-client version create --application myapp --filepath /home/user/app.json
If the creation of the version v1 for the application myapp is successful, you should receive output in the form of JSON describing your newly created version. The output should look similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 200,
"status": "200 OK",
"response": {
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"timeCreated": "2023-08-14 06:25:17 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:25:17 +0000 UTC",
"turnServer": {
"enable": true
}
}
}
If a version named v1 for the application myapp already exists, you should receive output similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 500,
"status": "500 Internal Server Error",
"response": "scalablepixelstreamingversions.sps.tensorworks.com.au \"myapp-v1\" already exists"
}
Creating a version from a compressed zip
This feature is currently only supported on the AWS cloud platform
To create a version from a compressed zip of your application requires the use of the --archive flag. You can use the --archive flag with either the --name or --filepath flags. Run the following command, changing the <path/to/version.zip> with your file path
sps-client version create --name v1 --application myapp --archive <path/to/version.zip>
Windows example
sps-client version create --name v1 --application myapp --archive "C:\Users\MyProject\project.zip"
Linux example
sps-client version create --name v1 --application myapp --archive /home/user/project.zip
The command-line tool will upload your project to the Scalable Pixel Streaming server and proceed to build it into a container stored in the cloud providers container registry (on AWS this would be ECR). While the file is uploading, you should see the following output:
project.zip 34% |████████████████████████████████████████████████████████ (247/724 MB, 34 MB/s) [18s:14s]
When the upload has completed it will uncompress your project on the server, this can take some time depending on the size of your project.
If the creation of the version v1 for the application myapp is successful, you should receive output in the form of JSON describing your newly created version. The output should look similar to the following:
{
"server": "local",
"method": "POST",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 200,
"status": "200 OK",
"response": {
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"timeCreated": "2023-08-14 06:25:17 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:25:17 +0000 UTC",
"turnServer": {
"enable": true
}
}
}
Flags
The following flags are available for the application create command:
--all-servers- Run command on all servers registered-a, --application- Name of the SPS application--archive- Path to the archived application--args- Specifies additional arguments to run the Unreal application with--disable-http-server- Disable the bundled HTTP server--disable-turn-server- Disable the bundled TURN server-d, --dry-run- Display the JSON payload of the command without executing it--encapsulation- The type of output that the build process should produce, currently only reference is supported--external- Sets if the container is hosted externally-f, --filepath- The path to the SPS version configuration JSON file-h, --help- help for create--name- Version name, e.g.v1.0.1orv2. When created, the name will be parsed to lower case; any characters outside [^-a-z0-9] regex will be replaced with ‘-‘--password- The password for accessing the container registry--platform- The operating system that this version of the application was built for. (default “linux”)--registry- The container registry where the image tag is stored--resx- Specifies the X resolution of the packaged Unreal application. Same as setting -ResX at runtime--resy- Specifies the Y resolution of the packaged Unreal application. Same as setting -ResY at runtime--server- Run command on a specific server--set-active- This will set this version as the Active version on the application--tag- The container image tag used to create a version. Input in this format: registry-username/repository-name:image-tag--timeout- The number of seconds to wait for the request to complete. If set to 0 the request will wait forever (default 1)--type- The type of input provided to the build process. Currently only imageTag is supported (default “imageTag”)--username- The username for accessing the container registry--config- allow overriding the location that the configuration file is loaded from
Using the version delete command
To delete a version using the version delete command can be done one of two ways.
- Supplying the
--nameand--applicationflags - Using a file containing the JSON payload of your Version with the
--filepathand--applicationflags
Deleting a version using the --name and --application flags
To delete a version using the --name and --application flags, run the following command:
sps-client version delete --name v1 --application myapp
If the deletion of the version v1 for the application myapp is successful, you should receive output that looks similar to the following:
{
"server": "sps",
"method": "DELETE",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions/v1",
"statusCode": 200,
"status": "200 OK"
}
Deleting a version using the --filepath and --application flags
When using the --filepath flag to delete a version, the only field that will be used in the version JSON payload is the name. All other fields will be ignored as they are not used when deleting a version.
The --application flag is mandatory whether you are using the --filepath flag or not. Using the --filepath flag requires that you have a JSON file path to feed into this flag. The file should consist of a valid version JSON payload. See the --skeleton flag for information on how to obtain the version JSON payload.
Your version JSON payload does not need to be a complete JSON object, especially if using the version delete command, all that is required is the name field. The following version JSON payload is valid:
{
"name": "v1"
}
To delete a version using the --filepath flag, run the following command, changing the <path/to/version.json> with your file path:
sps-client version delete --application myapp --filepath <path/to/version.json>
Windows example
An example of using the --filepath flag on Windows:
sps-client version delete --application myapp --filepath "C:\Users\Example\app.json"
Linux example
An example of using the --filepath flag on Linux:
sps-client version delete --application myapp --filepath /home/user/app.json
If the deletion of the version v1 for the application myapp is successful, you should receive output that looks similar to the following:
{
"server": "sps",
"method": "DELETE",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions/v1",
"statusCode": 200,
"status": "200 OK"
}
The --delete-all flag
The --delete-all command will delete all versions and should be carefully considered when used with the --skip-confirmation and --all-servers flags.
When supplied with the version delete command the --delete-all command will delete all versions for a given application on a given server. To delete all versions, run the following command:
sps-client version delete --application myapp --delete-all
You will be prompted with a confirmation Are you sure you want to delete all? y/n
Answering y if you want to delete or n if you do not want to delete. You can also use the --skip-confirmation flag to skip showing this confirmation entirely.
Flags
--all-servers- Run command on all servers registered-a, --application- Name of the SPS application--delete-all- Delete all deployed versions of an application-d, --dry-run- Display the JSON payload of the command without executing it-f, --filepath- The path to the SPS version configuration JSON file-h, --help- help for delete-n, --name- The version name--server- Run command on a specific server--skip-confirmation- Skips the confirmation prompt--config- allow overriding the location that the configuration file is loaded from
Using the version list command
The version list command can be used in one of two ways:
- Running the
version listcommand with the--applicationflag to list all versions for the given application - Supplying the
--nameand--applicationflags to list information for a specific version
The version list command will retrieve all relevant information for a version.
To list all versions for a given application myapp, run the following command:
sps-client version list --application myapp
The above command will output JSON of a full list of all versions for the application myapp. The output should look similar to the following:
{
"server": "local",
"method": "GET",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions",
"statusCode": 200,
"status": "200 OK",
"response": [
{
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": true,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"status": "Ready",
"timeCreated": "2023-08-14 06:36:28 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:36:28 +0000 UTC",
"turnServer": {
"enable": true
}
},
{
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "blob"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v2",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"status": "BuildFailed",
"timeCreated": "2023-08-14 06:53:07 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:54:56 +0000 UTC",
"turnServer": {
"enable": true
}
},
{
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v3",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"status": "Ready",
"timeCreated": "2023-08-14 06:28:31 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:28:31 +0000 UTC",
"turnServer": {
"enable": true
}
}
]
}
Retrieving version information using the --name and --application flags
To retrieve version information using the --name and --application flags, run the following command:
sps-client version list --application myapp --version v1
The above command will output JSON for the specified version. The output should look similar to the following:
{
"server": "local",
"method": "GET",
"endpoint": "http://my-sps-server.com/api/v1/application/myapp/v1/versions/v1",
"statusCode": 200,
"status": "200 OK",
"response": {
"buildOptions": {
"input": {
"containerTag": "registry/repo/image:tag",
"type": "imageTag"
},
"output": {
"encapsulation": "container"
}
},
"engineVersion": "",
"httpServer": {
"enable": true
},
"name": "v1",
"platform": "linux",
"runtimeOptions": {
"args": null,
"pixelStreaming": {
"webRTC": {
"frontendToSendOffer": false,
"maxFps": 60
}
},
"resolution": {
"x": 1920,
"y": 1080
},
"volumeMounts": null
},
"status": "Ready",
"timeCreated": "2023-08-14 06:28:31 +0000 UTC",
"timeLastUpdated": "2023-08-14 06:28:31 +0000 UTC",
"turnServer": {
"enable": true
}
}
}
Flags
--all-servers- Run command on all servers registered-a, --application- Name of the SPS application-d, --dry-run- Display the JSON payload of the command without executing it-h, --help- help for list--name- Version name, e.g. v1.0.1 orv2. When created, the name will be parsed to lower case; any characters outside [^-a-z0-9] regex will be replaced with ‘-‘--server- Run command on a specific server--config- allow overriding the location that the configuration file is loaded from