CLI FAQs

Please find the extended documentation for using the Rescale CLI here. This FAQ summarizes some of the common questions raised regarding the usage of Rescale CLI.

Also, the CLI defaults to the US platform (platform.rescale.com). If you are a user on any of the other global platforms (EU, JP, etc.), please specify your regional platform using the -X flag in your CLI command. For example:

java -jar /usr/local/bin/rescale.jar -X https://eu.rescale.com submit ...

There are a few ways for you to simplify the command and the API token integration:

1) Create a wrapper script

The following is a bash example and can be stored in a file at /usr/local/bin/rescale-submit:

#!/bin/bash 
java -jar /usr/local/bin/rescale.jar submit -p <api-token> -E -i $1

(replace <api-token> with your personal API token)

In this case the jar file is located at /usr/local/bin/rescale.jar. The user can now submit their jobs using the simple command:

rescale-submit <input-script>

2) Setting the RESCALE_API_KEY environment variable

Create the RESCALE_API_KEY environment variable in your terminal session, or add it to your profile file (such as ~/.bashrc or ~/.bash_profile):

export RESCALE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

3) Using profiles in a configuration file

By default, the CLI will look for the profile file in ~/.config/rescale/apiconfig. Create the file, and add the following contents:

[default]
apikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The CLI will use the [default] profile by default. A different named profile can be specified by using the --profile command line argument. It is also possible to use a different config file path by setting the RESCALE_CONFIG_FILE environment variable to the desired path.

The app supports the following commands:

"status" requests the specified job's status. Place in a loop to monitor continuously. It is recommended that an exponential backoff algorithm is used to monitor jobs that take longer.

java -jar /usr/local/bin/rescale.jar status [-p <api-token>] -j <job-id>

"stop" submits a request to cleanly shutdown the currently running job.

java -jar /usr/local/bin/rescale.jar stop [-p <api-token>] -j <job-id>

"sync" downloads the results files.

java -jar /usr/local/bin/rescale.jar sync [-p <api-token>] -j <job-id>

"list-info" retrieves useful metadata from the Rescale API.

Core types (-c):

java -jar /usr/local/bin/rescale.jar list-info -c [-p <api-token>]

Analyses (-a):

java -jar /usr/local/bin/rescale.jar list-info -a [-p <api-token>]

Note: If you have set the API key according to methods 2 or 3 in the section above, you may omit [-p <api-token>] from the above commands.

Command Line Options Description
-h Help
-E or --end-to-end Runs the job end-to-end, including uploading input files, submitting the job, monitoring for the results and downloading the results files.
-p <API token> Specifies the API token
-f <filter> ... Specifies one or more output file name filters used to limit the files that are downloaded. This option is only applicable when using the --end-to-end flag. See the Output File Filtering section for more details.
-q or --quiet Suppresses all logging output that would normally go to STDOUT. Json blobs resulting from queries or created items will still be output. This is useful when piping the script output to another script.

In addition, there are a few advanced Java system properties that can be specified:

rescale.loglevel (TRACE, DEBUG, INFO, WARNING, ERROR, OFF)
https.proxyHost
https.proxyPort
https.proxyUser
https.proxyPassword

For example, to run with DEBUG logging turned on and use proxy.com:8888 as a proxy server, the following command can be used:

java -Drescale.loglevel=DEBUG -Dhttps.proxyHost=proxy.com -Dhttps.proxyPort=8888 -jar /usr/local/bin/rescale.jar status -p <api-token> -j <job-id>

Note: There is no spacing between the -D and the name of the system property. In addition, the -D switches should also be specified before the -jar option.

If the proxy requires Windows authentication, the https.proxyUser and https.proxyPassword system properties can be set. The https.proxyUser value should be set to DOMAIN\username. The https.proxyPassword property can be set to the Windows password for the user. If you do not want to embed the password in the command line, this property can be omitted and the CLI will prompt you to enter your password in the console when it launches.