Common Use Cases

Overview

This page offers command-line examples for some commonly used scenarios with the Chaos Cloud Client App.

Auth

After the first login the client caches an encrypted login token, used for future sessions. At the moment these tokens don't expire automatically. The file is saved in the following locations on each operating system:

OS	Auth file location
Windows	%APPDATA%\Chaos Group\vcloud\client\auth
macOS	${HOME}/.ChaosGroup/vcloud/client/auth
Linux	${HOME}/.ChaosGroup/vcloud/client/auth

To reuse the token on another machine either copy the file to the appropriate location for that operating system, or set the VCLOUD_CLIENT_AUTH_TOKEN_PATH to the desired location.

For example, on Windows, assuming that the auth file is copied in C:\ccloud directory:

> set VCLOUD_CLIENT_AUTH_TOKEN_PATH="C:\\ccloud\\auth"
:: No manual authentication needed now:
> ccloud job submit --sceneFile="some_scene.vrscene"

For Linux and macOS, assuming the file is copied in /home/<user>/ccloud:

$ export VCLOUD_CLIENT_AUTH_TOKEN_PATH="$HOME/ccloud/auth"
# No manual authentication needed now:
$ ccloud job submit --sceneFile="scene.vrscene"
# Or, for a single invocation:
$ VCLOUD_CLIENT_AUTH_TOKEN_PATH="$HOME/ccloud/auth" ccloud job submit --sceneFile="scene.vrscene"

Submitting jobs

Example with the addition of a --json flag, that makes parsing of the ccloud output easier:

$ ccloud --json job submit --sceneFile scene.vrscene --project test_project

{"status":"success","type":"analyze step"}
{"status":"success","type":"validate step"}
{"type":"progress","progress":0}
{"type":"progress","progress":15}
{"type":"progress","progress":34}
{"type":"progress","progress":100}
{"jobID":"DEll0jabB7AOoTc0","jobURL":"http://localhost:9090/jobs/DEll0jabB7AOoTc0","message":"Scene uploaded successfully. Job ID: DEll0jabB7AOoTc0\nCheck the rendering progress on http://localhost:9090/jobs/DEll0jabB7AOoTc0","type":"output"}

Note that the --json flag must come before job submit.

Submit-Wait-Download

The --downloadOutput flag of the job submit command submits a set of scenes, waits for them to complete rendering and then downloads the outputs. It works with both sceneFile and batchFile.

When waiting for the render to finish, a progress bar is shown. Once the rendering is finished, it downloads the output to the directory specified by the --downloadOutput flag.

$ ccloud --json job submit --sceneFile /drive/scenes/toyota-chr/toyota-chr.vrscene --downloadOutput /drive/download/download-scenes/

{"status":"success","type":"analyze step"}
{"status":"success","type":"validate step"}
{"jobID":"IwuTUGmU6ydVBVyD","jobName":"toyota-chr","jobURL":"https://cloud.chaos.com/jobs/IwuTUGmU6ydVBVyD","message":"Job created.","type":"output"}
{"message":"Uploading started.","type":"info","uploadSize":"0.00B"}
{"type":"progress","progress":100}
{"jobID":"IwuTUGmU6ydVBVyD","jobURL":"https://cloud.chaos.com/jobs/IwuTUGmU6ydVBVyD","message":"Scene uploaded successfully. Job ID: IwuTUGmU6ydVBVyD\nCheck the rendering progress on https://cloud.chaos.com/jobs/IwuTUGmU6ydVBVyD","type":"output"}
{"type":"progress","progress":0}
{"type":"progress","progress":5}
{"type":"progress","progress":6}
{"type":"progress","progress":20}
{"type":"progress","progress":42}
{"type":"progress","progress":79}
{"type":"progress","progress":99}
{"type":"progress","progress":100}
{"message":"job IwuTUGmU6ydVBVyD is completed","jobId":"IwuTUGmU6ydVBVyD","state":"completed","type":"output"}
{"message":"Rendering finished, downloading outputs...","type":"output"}
{"message":"Downloading output for job 'IwuTUGmU6ydVBVyD' (586.72KB)","sizeString":"586.72KB","type":"output"}
{"type":"progress","progress":0}
{"type":"progress","progress":59}
{"type":"progress","progress":60}
{"type":"progress","progress":100}
{"type":"progress","progress":100}
{"message":"downloaded output of job IwuTUGmU6ydVBVyD successfully","type":"output"}

Clone Only Incomplete Frames

The --onlyUncompleted flag of the job resubmit command clones only frames from a job, that are not in a complete state - failed, canceled or paused frames.

$ ccloud --json job resubmit --id="IbJD218cTrXcO1Ps" --onlyUncompleted

{"message":"Job Ixd3TAudUv5eWBgb is started successfully from IbJD218cTrXcO1Ps","newJobID":"Ixd3TAudUv5eWBgb","type":"output"}

Status Check

Completed Job

$ ccloud --json job status --id DEll0jabB7AOoTc0

{"jobID":"DEll0jabB7AOoTc0","message":"job DEll0jabB7AOoTc0 is completed","state":"completed","type":"output"}

Active Job

$ ccloud --json job status --id DElti15NpajRV9K0

{"jobID":"DElti15NpajRV9K0","message":"job DElti15NpajRV9K0 is active (0%)","progress":"0%","state":"active","type":"output"}

Failed Job

$ ccloud --json job status --id DElti15NpajRV9K0

{"jobID":"DElti15NpajRV9K0","message":"job DElti15NpajRV9K0 is failed","state":"failed","type":"output"}

Uncompleted Frames

$ ccloud job status --id="IxZdIu9mWqlQRsQn"

{"message":"job IxZdIu9mWqlQRsQn is paused, not all frames were completed.","jobId":"IxZdIu9mWqlQRsQn","frames":[{"state":"paused","frameRange":"1-100"}],"state":"paused","type":"output"}

Downloading Completed Jobs

$ ccloud --json job download --id DEll0jabB7AOoTc0 --output "$HOME/Downloads"

{"type":"progress","progress":0}
{"type":"progress","progress":11}
{"type":"progress","progress":100}
{"message":"downloaded output of job DEll0jabB7AOoTc0 successfully","type":"output"}

Webhooks

Chaos Cloud currently does not support notifications via WebHooks. In the meantime, integrators can implement webhooks on their own, by writing their own component that uses ccloud job status periodically and calls their webhook.

Version Check and Update

Checking for updates (update is available)

$ ccloud --json version check

{"isDeprecated":"no","message":"New version 1.5.0 available.","newVersion":"1.5.0","type":"output"}

Checking for updates (the client is already up-to-date)

$ ccloud --json version check

{"isDeprecated":"no","message":"The Chaos Cloud Client is up to date.","type":"output"}

Checking for updates (the client is deprecated and should be updated)

$ ccloud --json version check

{"error":"ccloud: Cannot continue execution.\nUpdate by executing the following command:\n\n\
tccloud update\n\nIf the problem persists, please contact support@chaosgroup.com","isDeprecat
ed":"yes","type":"error"}

Updating (new version available)

$ ccloud --json update

{"type":"progress","progress":0}
{"type":"progress","progress":10}
{"type":"progress","progress":50}
{"type":"progress","progress":80}
{"type":"progress","progress":100}
{"message":"application updated successfully to version 1.5.0","newVersion":"1.5.0","type":"output","updated":"yes"}

Updating (already up-to-date)

$ ccloud --json update

{"message":"The Chaos Cloud Client is up to date.","type":"output","updated":"no"}

Start ccloud web server on a specified port

Use the --port global flag (before any subcommands like job and version)

$ ccloud --json --port 8080 job submit --sceneFile scene.vrscene --project test_project

Upload Only

Using the Upload Only feature you can submit a job, which is initially paused and can be manually started later, as opposed to the regular workflow, which starts the job immediately after it is uploaded.

$ ccloud --json job submit --sceneFile scene.vrscene --onlyUpload

{"status":"success","type":"analyze step"}
{"status":"success","type":"validate step"}
{"type":"progress","progress":100}
{"jobID":"GpW90CIoB5BU3Fvz","jobURL":"https://cloud.chaos.com/jobs/GpW77CIoB5BU3Fvz","message":"Scene uploaded successfully. Job ID: GpW77CIoB5BU3Fvz\nCheck the rendering progress on https://cloud.chaos.com/jobs/GpW77CIoB5BU3Fvz","type":"output"}

Batch Submit

To submit multiple scenes at once for rendering, use a batch file.

$ ccloud --json job submit --batchFile path/to/file.json

The batch file uses json syntax and represents an object in which all the options set in root keys are applied to all scenes. The actual scenes are described as an array of objects under the ‘scenes’ key. Example:

{
  "project": "test",
  "layers": true,
  "scenes": [
	{
  	"path": "adaptive_lights/scene.vrscene",
  	"name": "adaptive",
  	"creditLimit": 2,
  	"onlyUpload": true
	},
	{
  	"path": "loft_bedroom/scene.vrscene",
  	"name": "loft",
  	"width": 640,
  	"height": 480,
  	"onlyCPU": true
	},
	{
  	"path": "texture_maps/scene.vrscene"
	}
  ]
}

Json output from the batch submit:

{"status":"success","type":"analyze step"}
{"status":"success","type":"validate step"}
{"type":"progress","progress":100}
{"type":"progress","progress":100}
{"type":"progress","progress":0}
{"type":"progress","progress":4}
{"type":"progress","progress":100}
{"jobID":"Gpkok2L6mkA2bqn5","jobURL":"https://cloud.chaos.com/jobs/Gpkuk2L6mkA2bqn5","message":"Scene uploaded successfully. Job ID: Gpkuk2L6mkA2bqn5\nCheck the rendering progress on https://cloud.chaos.com/jobs/Gpkuk2L6mkA2bqn5","type":"output"}
{"jobID":"Gpkon_Ht7WI1Ur_4","jobURL":"https://cloud.chaos.com/jobs/Gpkon_Ht7WI1Ur_4","message":"Scene uploaded successfully. Job ID: Gpkon_Ht7WI1Ur_4\nCheck the rendering progress on https://cloud.chaos.com/jobs/Gpkon_Ht7WI1Ur_4","type":"output"}
{"jobID":"Gpkoq5y0LFrgsAZ9","jobURL":"https://cloud.chaos.com/jobs/Gpkoq5y0LFrgsAZ9","message":"Scene uploaded successfully. Job ID: Gpkoq5y0LFrgsAZ9\nCheck the rendering progress on https://cloud.chaos.com/jobs/Gpkoq5y0LFrgsAZ9","type":"output"}

Root key options

Key	Description
project (string, required)	The name of the project in which all the scenes of the batch are submitted.
layers (bool)	Specifies whether the different scenes in the batch are different layers of the same scene or not. Defaults to "false".
views (bool)	Specifies whether the scenes in the batch are different views of the same scene. Defaults to "false".
meta (array of strings)	A list of key-value pairs which are added to the metadata of the jobs that resulted from submitting the scenes. The strings must be in the key=value format.
scenes (array, required)	A list of objects, each of which describes a scene to be uploaded to the cloud. See below for definition of the scene object.

As shown in the example, each scene is itself represented as an object and these are the possible keys in it:

Key	Description
path (string, required)	Specifies path to a .vrscene file.
colorCorrectionsFile (string)	Specifies path to a color corrections file.
frameRange (string)	Defines a frame range for the animation. Only makes sense if the scene is actually an animation.
frameStep (int)	Defines a frame step for the animation (default 1). Only makes sense if the scene is actually an animation.
height (int)	Defines the height of the rendered image.
width (int)	Defines the width of the rendered image.
name (string)	Specifies a name for the rendering job.
onlyCPU (bool)	Use only CPU for rendering. Applicable for GPU scenes.
onlyUpload (bool)	Upload the scene and leave the job in paused state.

Multicamera Submit

If the scene has multiple cameras, you can submit all of them for rendering with the --allCameras flag:

$ ccloud job --json submit --sceneFile still.vrscene --allCameras

This is the result:

{"status":"success","type":"analyze step"}
{"status":"success","type":"validate step"}
{"type":"progress","progress":0}
{"type":"progress","progress":100}
{"jobID":"Gpk1UxX0tMdX7d-S","jobURL":"https://cloud.chaos.com/jobs/Gpk1UxX0tMdX7d-S","message":"Scene uploaded successfully. Job ID: Gpk1UxX0tMdX7d-S\nCheck the rendering progress on https://cloud.chaos.com/jobs/Gpk1UxX0tMdX7d-S","type":"output"}

If the scene has multiple cameras, but you want to submit only a specific one, you can use the --camera CameraName flag. Keep in mind that CameraName stands for the name of the specific camera in your scene. That name might differ from the one in the example below:

ccloud job --json submit --sceneFile cams.vrscene --camera VRayCam001