1.0X Rescale CLI Basics

Basic Submission Syntax

With your API token and local copy of the App, a job can be submitted using the following command:

    java -jar /usr/local/bin/rescale.jar submit -p  -i

For users from other platforms (KR, JP, EU), please refer to CLI FAQs for additional flag required while using Rescale CLI. The contains the commands the user may want to run on Rescale. It can be any kind of .sh shell script that can be executed from the command line using the ./ prefix. Regardless of the type of script, the App will try to parse the script to minimize inadvertent issues related to environment setup and un-supported commands. The -p flag is used to read the Rescale API Token you created as shown here.

Simplifying CLI Commands

You can simplify the Rescale commands by creating wrapper scripts. You can also set the RESCALE_API_KEY environment variable (2) or create a profile in the configuration file (3) to omit -p from Rescale CLI commands. These additional steps will help the user in simplifying and using the Rescale CLI commands easily.

In particular, creating a simple wrapper script will reduce some potential sources of error when submitting a job.

The following is an example contents of a bash wrapper script:

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

Replace the <api-token> with the hash string of your API key token. The script also assumes that the Rescale CLI App (rescale.jar) is located in /usr/local/bin, so modify accordingly. Because the script will contain your private <api-token> value, it should be stored in a directory in your $PATH with limited permissions such as /usr/local/bin. Also, ensure that the script has the proper permissions so that it can be executed:

chmod +x /usr/local/bin/rescale-submit

For using the Rescale CLI commands, the Rescale API key must be used every time. Since the API Key is a long combination of letter, it will be helpful to create an environment variable and save it in your profile so that you can conveniently use the API variable rather than the actual key every time you use the commands. You can follow these steps for creating the environment variable –

  • On your terminal, type either vi ~/.bashrc OR vi ~/.bash_profile and hit ENTER.
  • This opens up a terminal editor where you can type the following : bash export RESCALE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • Once you finish typing, hit ESC first and then type :wq to save the changes.
  • You can test the variable by displaying the variable using echo $RESCALE_API_KEY. This will display the Rescale API key on the terminal.

By default, the CLI will look for the profile file in ~/.config/rescale/apiconfig. Create the file (vi ~/.config/rescale/apiconfig), 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.

If a user is using multiple profiles for different platforms they have to specify the URL to those platforms in the apiconfig as follows:

[default]apibaseurl = https://platform.rescale.comapikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
[eu]apibaseurl = https://eu.rescale.comapikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Submitting a Test Job – Hello World!

Let’s look at a very simple example. Again, this example assumes that you have set up a wrapper script called rescale-submit shown above.

To run a “Hello World!” job, from a shell terminal (such as in Linux, MacOS, or Cygwin) create a new run directory. Using the text editor of your choice, create a submit.sh input submission script containing:

Note: When copying the above script, ensure that there are no spaces following each environment variable.

Submit the job:

rescale-submit submit.sh

This will spin up a new cluster and submit the jobs with the commands from the script. The user can now login to the Rescale Web UI to tail and monitor the job. The job list will show the job as: “Hello World”

Job Submitted

The status page will show the progress of the job and the files can be tailed from within the UI by clicking on the file:

Live Tailing

The log will look something like this:

Running SGE version of Rescale Client App
Executing Command.
Parsing Input Files
No existing files to include
Found Analysis: user_included
No project with the specified name was found: null
Zipping Files
Creating temporary encrypted zip at /Users/rescale/helloworld/input.zip
Finished writing encrypted file
Uploading Files
Uploading: /Users/rescale/helloworld/run.sh
Uploading run.sh:
##############################| 288B / 288B
Uploading: /Users/rescale/helloworld/input.
Uploading input.zip:
##############################| 83.08KB / 83.08KB
Job: Saving Job
Job qMCOdb: Saved
Job qMCOdb: Submitting
Job qMCOdb: Starting polling cycle
Job qMCOdb: Status - Validated
Job qMCOdb: Status - Executing
Job qMCOdb: Status - Executing
Job qMCOdb: Status - Executing
Job qMCOdb: Status - Executing
Job qMCOdb: Status - Completed
Job qMCOdb: Finished...
Job qMCOdb: Downloading files to output/
Downloading output/submit.sh
Downloading output/run.sh
Downloading output/process_output.log
Downloading output/inputs/file2
Downloading output/inputs/file1
Downloading output/hello_world
Downloading output/file0
.
.
.
Finished downloading files.