CLI (rescale-cli)

The Rescale CLI (rescale-cli) is a Java-based client application that wraps the Rescale REST API in ergonomic commands. Use it to submit and manage jobs, transfer files into and out of Rescale Cloud Storage, check job status, and inspect the software and hardware catalog from a terminal or a script. This page covers install, authentication, the commands you will use most often, and the submission script format.

When to use the CLI

Reach for the CLI when you want to:

• Drive Rescale from a shell script or CI job.
• Upload large input files with a multi-threaded transfer that handles authentication for you.
• Monitor running jobs and sync results to a local directory.
• Chain jobs together (submit a new job from inside a running job) without writing API glue code.

If you are already building a service on top of the Rescale API, prefer the REST API directly. The CLI is most useful as a local developer tool and as the transport for simulation input and output data.

Installing the CLI

CLI 1.1.x bundles its own Java runtime, so you do not need a separate Java install. Earlier 1.0.x releases require Java 8. This page assumes 1.1.x.

1. In the Rescale web UI, open Preferences > API.
2. Under your API token, download the installer for your operating system.
3. Run the installer.
   • macOS and Windows: double-click the package and follow the installer wizard.
   • Linux (RPM): sudo rpm -i rescale-cli-<version>.rpm
   • Linux (Debian/Ubuntu): sudo dpkg -i rescale-cli-<version>.deb
4. Verify the install with rescale-cli -h. You should see usage output.

If the command is not found, re-check the installation and your PATH. For installs without admin rights, see "Installing Rescale CLI Without Admin Privileges" under Citations.

Authenticating the CLI

Every command needs a Rescale API token. You can pass it on the command line with -p <api-token>, but two more convenient options are an environment variable or a config file.

Environment variable

On macOS or Linux, edit ~/.bashrc or ~/.bash_profile:

export RESCALE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

On Windows (cmd):

set RESCALE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Once set, you can omit -p from all CLI commands.

Configuration file

Create ~/.config/rescale/apiconfig (%USERPROFILE%\.config\rescale\apiconfig on Windows) with the following contents:

[default]
apikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The CLI uses the [default] profile automatically. To target additional regional platforms, add named profiles and select one with --profile:

[default]
apibaseurl = https://platform.rescale.com
apikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[eu]
apibaseurl = https://eu.rescale.com
apikey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Override the config path with the RESCALE_CONFIG_FILE environment variable.

Regional platforms

rescale-cli defaults to platform.rescale.com. If you are on another platform, pass -X with the base URL:

Region	Base URL
United States (commercial)	https://platform.rescale.com
Europe	https://eu.rescale.com
Japan	https://platform.rescale.jp
Korea	https://kr.rescale.com
ITAR	https://itar.rescale.com

Pick your platform to see just your values, here and across the docs:

Example:

rescale-cli -X https://platform.rescale.com submit -i submit.sh

Submitting a job

A submission is driven by a shell script, usually called submit.sh, that mixes Rescale directives (#RESCALE_* lines) with the commands you want to run on the cluster. The CLI parses the script to extract job settings and produces a sanitized runtime script.

Minimal "Hello World":

#!/bin/bash
#RESCALE_NAME="Hello World"
#RESCALE_CORES=1
#RESCALE_ANALYSIS=user_included
#RESCALE_ANALYSIS_VERSION=0
#RESCALE_CORE_TYPE=Emerald

echo "Hello World!" > hello_world
sleep 120

Watch for trailing spaces

Do not leave spaces after the #RESCALE_* values. The parser is strict and a trailing space will cause validation to fail.

Submit it:

rescale-cli submit -i submit.sh

The CLI zips the working directory into a temporary input.zip, uploads both run.sh and input.zip, creates the job, and submits it. The log prints the new job ID; record it for later commands. Passing --end-to-end (or -E) keeps the CLI running and polls for completion, then downloads results.

A typical LS-DYNA submit.sh:

#!/bin/bash
#RESCALE_NAME="LSDYNA Neon Example"
#RESCALE_ANALYSIS=ls_dyna
#RESCALE_CORE_TYPE=emerald
#RESCALE_CORES=2
#RESCALE_WALLTIME=1
#USE_RESCALE_LICENSE

ls-dyna -n $RESCALE_CORES_PER_SLOT -i neon.refined.rev01.k -p single

Monitoring, stopping, and deleting jobs

Check status:

rescale-cli status -j <job-id>

Place this in a loop with an exponential backoff to monitor long jobs.

Stop a running job cleanly:

rescale-cli stop -j <job-id>

Delete a completed job:

rescale-cli delete -j <job-id>

Transferring files

Upload standalone files

rescale-cli upload -f file1.dat file2.dat

Useful flags:

• -e returns extended metadata for each upload.
• --quiet suppresses non-JSON output so you can parse results in another script.
• -r <file>|- writes a JSON report of file IDs and results.
• --copy-to-cfs (CLI 1.1.271 or later) uploads into your Cloud File System library. One file per invocation.

Download files during a running job

rescale-cli download-file -j <job-id> -f shared/d3plot

The path is relative to the cluster working directory. Use the live-tailing window in the web UI to discover paths. Downloaded files are prefixed with a timestamp: download_<timestamp>_<original>.

Sync results after job completion

rescale-cli sync -j <job-id>

Filter options:

• -s <pattern> filters on the server side using string pattern matching. Recommended for large jobs. Commas act as AND: -s cpu,gpu returns only files containing both substrings.
• -f <glob> filters on the client side using shell globs. Works best in bash.
• --exclude <file1>,<file2> drops specific files.
• -n <job-id> syncs all jobs newer than the given ID.
• -d <seconds> enables continuous syncing with that delay between passes.
• -o <dir> writes into a specific output directory.
• --max-concurrent <n> tunes parallelism (default 5).

Example that downloads everything starting with d3 except a few large dump files:

rescale-cli sync -j <job-id> -f 'd3*' --exclude d3hsp,d3dump01.0000,d3dump01.0001

List files on a job

rescale-cli list-files -j <job-id>

Discovering software and hardware

rescale-cli list-info -a   # available analyses (software codes)
rescale-cli list-info -c   # available coretypes

Pass the code value into #RESCALE_ANALYSIS and #RESCALE_CORE_TYPE respectively. See "How to Retrieve Software Names and Versions for API and CLI Usage" under Citations for details.

Submission script directives

The #RESCALE_* directives in your script map to job settings. The important ones:

• #RESCALE_NAME=<string> job name.
• #RESCALE_ANALYSIS=<code> software, for example ls_dyna, ansys_fluent, or user_included for a bring-your-own-binary job. Repeat the RESCALE_ANALYSIS / RESCALE_ANALYSIS_VERSION pair for multi-analysis jobs (CLI 1.1.209 or later).
• #RESCALE_ANALYSIS_VERSION=<string> specific version code. Omit or leave blank to use the latest.
• #RESCALE_CORE_TYPE=<code> hardware, for example Emerald, Carbon, or Graphite.
• #RESCALE_CORES=<int> total cores. Allowed values depend on the coretype.
• #RESCALE_WALLTIME=<hours> hard wall clock. Jobs exceeding it are terminated.
• #RESCALE_PROJECT_ID=<project> assigns the job to a project.
• #RESCALE_EXISTING_FILES=<id1>,<id2> reuses files already on Rescale by ID.
• #USE_RESCALE_LICENSE uses Rescale-hosted licenses. Omit for customer-provided licenses, configured via #RESCALE_ENV_* directives. For example: #RESCALE_ENV_RLM_LICENSE=8112@license-proxy.rescale.com.
• #RESCALE_USER_DEFINED_LICENSE_SETTINGS=<stringified-json> fine-grained license feature counts.
• #RESCALE_LOW_PRIORITY=true runs in on-demand economy mode.
• #RESCALE_INBOUND_SSH_CIDR and #RESCALE_PUBLIC_KEY open SSH access to the head node.

The CLI parses your script with the SGE input parser by default. It strips module load ... and absolute /path/to/mpirun style lines so they do not fight the Rescale environment. The sanitized output is written to run.sh and that is what runs on the cluster.

Proxies, debugging, and JVM flags

Arguments prefixed with -J are passed through to the JVM as -D system properties. Useful ones:

• -J-Drescale.loglevel=DEBUG (levels: TRACE, DEBUG, INFO, WARNING, ERROR, OFF).
• -J-Dhttps.proxyHost=proxy.example.com -J-Dhttps.proxyPort=8888.
• -J-Dhttps.proxyUser=DOMAIN\\username and optionally -J-Dhttps.proxyPassword=.... Omit the password and the CLI will prompt.

Example:

rescale-cli -J-Drescale.loglevel=DEBUG -J-Dhttps.proxyHost=proxy.com -J-Dhttps.proxyPort=8888 \
  status -j <job-id>

For custom SSL certificates and corporate proxies, see "Configuring Rescale CLI for Proxy Servers and Custom SSL Certificates" under Citations.

If a transfer fails rather than the connection, the CLI also needs egress to the object storage behind the platform, not just to the platform host. The endpoint list is in Rescale Transfer Manager. A firewall blocking one of those produces a TLS or connection error rather than a clear message.

Updating and troubleshooting

• rescale-cli check-for-update reports whether a newer CLI is available.
• rescale-cli --version prints the installed version (useful for features gated on 1.1.209+ and 1.1.271+).
• If the CLI will not start with a Java error, see "Troubleshooting Java Errors in Rescale CLI" under Citations. The 1.1.x installers bundle their own JRE; 1.0.x requires Java 8 on your path.
• On macOS, a common symlink permission failure at install time is covered in "How to Fix Rescale CLI Symlink Installation Permission Error" under Citations.

Related

• REST API for the underlying HTTP surface.
• Developer overview for API key setup and an end-to-end flow.
• Writing an automation for scripts that run on Rescale before, during, or after your job, and when to put logic there instead of in a submit script.