3. User guide

3.1. Environment variables

3.1.1. REANA_SERVER_URL

You can set this environment variable in order to specify to which REANA cloud instance your client should connect and a valid token. For example:

$ export REANA_SERVER_URL=https://reana.cern.ch

3.1.2. REANA_ACCESS_TOKEN

You should specify valid access token for the REANA cloud instance you would like to use. For example:

$ export REANA_ACCESS_TOKEN=XXXXXXX

The token should have been given to you by the REANA cluster administrators.

3.1.3. REANA_WORKON

You can set this environment variable in order to specify a concrete workflow you would like to work on. (As an alternative to specifying --workflow option in commands.) For example:

$ export REANA_WORKON=myfirstanalysis

will work on the latest run of your “myfirstanalysis” workflow.

Note that you can also specify a concrete run number:

$ export REANA_WORKON=myfirstanalysis.3

which will permit to work on the third run of the “myfirstanalysis” workflow, for example to check out past input and output files.

You can list all your workflow runs and their statuses by doing:

$ reana-client workflows

and set REANA_WORKON to the one you would like to work on.

3.2. Usage

3.2.1. Overview

Please see the Getting Started section for a basic reana-client use case scenario.

3.2.2. Uploading analysis assets

Uploading files or directories to an analysis workspace is simple as:

$ reana-client upload file1 file2 directory1
File file1 was successfully uploaded.
File file2 was successfully uploaded.
File directory1/file3 was successfully uploaded.

If you want to upload all input files defined in the reana.yaml of the analysis, you can just run:

$ reana-client upload
File file1 was successfully uploaded.
File file2 was successfully uploaded.

Directory structures are maintained, i.e. directory1 exists in the workspace.

Note that symbolic links are resolved at the moment of upload so that a hard copy of the link target is uploaded to the cloud storage workspace. The link is not maintained throughout the workflow execution.

3.2.3. Downloading outputs

Downloading files from an analysis workspace works in the same way:

$ reana-client download result.png
File plot.png downloaded to /myfirstanalysis.

In the same way you can download all outputs defined in the reana.yaml file of the analysis, by just running:

$ reana-client download

Note that downloading directories is not yet supported.

3.2.4. Running analysis

If you have fully working analysis with reana.yaml, you can run the workflow easily via the run wrapper command, which will create a new workflow, upload analysis inputs, and start the workflow run.

$ vim reana.yaml
$ reana-client run -n myanalysis
[INFO] Creating a workflow...
myanalysis.1
[INFO] Uploading files...
File code/helloworld.py was successfully uploaded.
File data/names.txt was successfully uploaded.
[INFO] Starting workflow...
myanalysis.1 has been started.
$ export REANA_WORKON=myanalysis
$ reana-client status
NAME         RUN_NUMBER   CREATED               STATUS    PROGRESS
myanalysis   1            2018-11-07T12:45:18   running   1/1
$ reana-client download results/plot.png

3.3. Examples

You can get inspiration on how to structure your REANA-compatible research data analysis from several reana-demo-... examples provided on GitHub.

3.4. Commands

The full list of reana-client commands with their documented options is available in the CLI API documentation.