5. CLI API

Usage: reana-client [OPTIONS] COMMAND [ARGS]...

  REANA client for interacting with REANA server.

Options:
  -l, --loglevel [DEBUG|INFO|WARNING]
                                  Sets log level
  --help                          Show this message and exit.

Configuration commands:
  ping  Check connection to REANA server.

Workflow management commands:
  create  Create a new workflow.
  delete  Delete a workflow.
  diff    Show diff between two workflows.
  list    List all workflows and sessions.

Workflow execution commands:
  logs      Get workflow logs.
  run       Shortcut to create, upload, start a new workflow.
  start     Start previously created workflow.
  status    Get status of a workflow.
  stop      Stop a running workflow.
  validate  Validate workflow specification file.

Workspace interactive commands:
  close  Close an interactive session.
  open   Open an interactive session inside the workspace.

Workspace file management commands:
  download  Download workspace files.
  du        Get workspace disk usage.
  ls        List workspace files.
  mv        Move files within workspace.
  rm        Delete files from workspace.
  upload    Upload files and directories to workspace.

Secret management commands:
  secrets-add     Add secrets from literal string or from file.
  secrets-delete  Delete user secrets by name.
  secrets-list    List user secrets.

5.1. reana-client

REANA client for interacting with REANA server.

reana-client [OPTIONS] COMMAND [ARGS]...

Options

-l, --loglevel <loglevel>

Sets log level

Options:DEBUG|INFO|WARNING

5.1.1. close

Close an interactive session.

The close command allows to shut down any interactive sessions that you may have running. You would typically use this command after you finished exploring data in the Jupyter notebook and after you have transferred any code created in your interactive session.

Examples:

$ reana-client close -w myanalysis.42
reana-client close [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

5.1.2. create

Create a new workflow.

The create command allows to create a new workflow from reana.yaml specifications file. The file is expected to be located in the current working directory, or supplied via command-line -f option, see examples below.

Examples:

$ reana-client create

$ reana-client create -f ./somedir/myreana.yaml

reana-client create [OPTIONS]

Options

-f, --file <file>

REANA specifications file describing the workflow and context which REANA should execute.

-n, --name <name>

Name of the workflow.

--skip-validation

If set, specifications file is not validated before submitting it’s contents to REANA server.

-t, --access-token <access_token>

Access token of the current user.

5.1.3. delete

Delete a workflow.

The delete command allows to remove workflow runs from the database and the workspace. By default, the command removes the workflow and all its cached information and hides the workflow from the workflow list. Note that workflow workspace will still be accessible until you use –include-workspace flag. Note also that you can remove all past runs of a workflow by specifying –include-all-runs flag.

Example:

$ reana-client delete -w myanalysis.42

$ reana-client delete -w myanalysis.42 –include-records

reana-client delete [OPTIONS]

Options

--include-all-runs

Delete all runs of a given workflow.

--include-workspace

Delete workspace from REANA.

--include-records

Delete all records of workflow, including database entries and workspace.

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

5.1.4. diff

Show diff between two workflows.

The diff command allows to compare two workflows, the workflow_a and workflow_b, which must be provided as arguments. The output will show the difference in workflow run parameters, the generated files, the logs, etc.

Examples:

$ reana-client diff myanalysis.42 myotheranalysis.43

$ reana-client diff myanalysis.42 myotheranalysis.43 –brief

reana-client diff [OPTIONS] WORKFLOW_A WORKFLOW_B

Options

-q, --brief

If not set, differences in the contents of the files in the twoworkspaces are shown.

-u, -U, --unified <context_lines>

Sets number of context lines for workspace diff output.

-t, --access-token <access_token>

Access token of the current user.

Arguments

WORKFLOW_A

Required argument

WORKFLOW_B

Required argument

5.1.5. download

Download workspace files.

The download command allows to download workspace files. By default, the files specified in the workflow specification as outputs are downloaded. You can also specify the individual files you would like to download, see examples below. Note that downloading directories is not yet supported.

Examples:

$ reana-client download # download all output files

$ reana-client download mydata.tmp outputs/myplot.png

reana-client download [OPTIONS] FILES

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-o, --output-directory <output_directory>

Path to the directory where files will be downloaded.

-t, --access-token <access_token>

Access token of the current user.

Arguments

FILES

Optional argument(s)

5.1.6. du

Get workspace disk usage.

The du command allows to chech the disk usage of given workspace.

Examples:

reana-client du -s

$ reana-client du -w myanalysis.42 -s

reana-client du [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

-s, --summarize

Display total.

5.1.7. list

List all workflows and sessions.

The list command lists workflows and sessions. By default, the list of workflows is returned. If you would like to see the list of your open interactive sessions, you need to pass the –sessions command-line option.

Example:

$ reana-client list –all

$ reana-client list –sessions

reana-client list [OPTIONS]

Options

-s, --sessions

List all open interactive sessions.

--format <_filter>

Format output according to column titles or column values (case-sensitive). Use <colum_name>=<columnn_value> format. For E.g. dislpay workflow with failed status and named test_workflow –format status=failed,name=test_workflow.

--json

Get output in JSON format.

--all

Show all workflows including deleted ones.

-v, --verbose

Set status information verbosity.

-t, --access-token <access_token>

Access token of the current user.

5.1.8. logs

Get workflow logs.

The logs command allows to retrieve logs of running workflow. Note that only finished steps of the workflow are returned, the logs of the currently processed step is not returned until it is finished.

Examples:

$ reana-client logs -w myanalysis.42
reana-client logs [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

--json

Get output in JSON format.

-t, --access-token <access_token>

Access token of the current user.

5.1.9. ls

List workspace files.

The ls command lists workspace files of a workflow specified by the environment variable REANA_WORKON or provided as a command-line flag –workflow or -w.

Examples:

$ reana-client ls –workflow myanalysis.42
reana-client ls [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

--format <_filter>

Format output according to column titles or column values (case-sensitive). Use <colum_name>=<columnn_value> format. For E.g. dislpay FILES named data.txt –format name=data.txt.

--json

Get output in JSON format.

-t, --access-token <access_token>

Access token of the current user.

5.1.10. mv

Move files within workspace.

The mv command allow to move the files within workspace.

Examples:

$ reana-client mv data/input.txt input/input.txt
reana-client mv [OPTIONS] SOURCE TARGET

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

Arguments

SOURCE

Required argument

TARGET

Required argument

5.1.11. open

Open an interactive session inside the workspace.

The open command allows to open interactive session processes on top of the workflow workspace, such as Jupyter notebooks. This is useful to quickly inspect and analyse the produced files while the workflow is stlil running.

Examples:

$ reana-client open -w myanalysis.42 jupyter
reana-client open [OPTIONS] interactive-session-type

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-i, --image <image>

Docker image which will be used to spawn the interactive session. Overrides the default image for the selected type.

-t, --access-token <access_token>

Access token of the current user.

Arguments

interactive-session-type

Required argument

5.1.12. ping

Check connection to REANA server.

The ping command allows to test connection to REANA server.

Examples:

reana-client ping
reana-client ping [OPTIONS]

5.1.13. rm

Delete files from workspace.

The rm command allow to delete files and directories from workspace. Note that you can use glob to remove similar files.

Examples:

$ reana-client rm -w myanalysis.42 data/mydata.csv

$ reana-client rm -w myanalysis.42 ‘code/*’

reana-client rm [OPTIONS] SOURCES

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

Arguments

SOURCES

Optional argument(s)

5.1.14. run

Shortcut to create, upload, start a new workflow.

The run command allows to create a new workflow, upload its input files and start it in one command.

Examples:

$ reana-client run -n myanalysis-test-small -p myparam=mysmallvalue

$ reana-client run -n myanalysis-test-big -p myparam=mybigvalue

reana-client run [OPTIONS] SOURCES

Options

-f, --file <file>

REANA specifications file describing the workflow and context which REANA should execute.

-n, --name <name>

Name of the workflow.

--skip-validation

If set, specifications file is not validated before submitting it’s contents to REANA server.

-p, --parameter <parameters>

Additional input parameters to override original ones from reana.yaml. E.g. -p myparam1=myval1 -p myparam2=myval2.

-o, --option <options>

Additional operatioal options for the workflow execution. E.g. CACHE=off.

-t, --access-token <access_token>

Access token of the current user.

Arguments

SOURCES

Optional argument(s)

5.1.15. secrets-add

Add secrets from literal string or from file.

Examples:

$ reana-client secrets-add –from-literal PASSWORD=password

$ reana-client secrets-add –from-file ~/.keytab

$ reana-client secrets-add –from-literal USER=reanauser

–from-literal PASSWORD=password

—from-file ~/.keytab

reana-client secrets-add [OPTIONS]

Options

--from-literal <from_literal>

Secrets to be uploaded from literal string.e.g. PASSWORD=password123

--from-file <from_file>

Secrets to be uploaded from file.

--overwrite

Overwrite the secret if already present

-t, --access-token <access_token>

Access token of the current user.

5.1.16. secrets-delete

Delete user secrets by name.

Examples:

$ reana-client secrets-delete PASSWORD
reana-client secrets-delete [OPTIONS] [SECRETS]...

Options

-t, --access-token <access_token>

Access token of the current user.

Arguments

SECRETS

Optional argument(s)

5.1.17. secrets-list

List user secrets.

Examples:

$ reana-client secrets-list
reana-client secrets-list [OPTIONS]

Options

-t, --access-token <access_token>

Access token of the current user.

5.1.18. start

Start previously created workflow.

The start command allows to start previously created workflow. The workflow execution can be further influenced by passing input prameters using -p or –parameters flag and by setting additional operational options using -o or –options. The input parameters and operational options can be repetitive. For example, to disable caching for the Serial workflow engine, you can set -o CACHE=off.

Examples: n t $ reana-client start -w myanalysis.42 -p sleeptime=10 n t $ reana-client start -w myanalysis.42 -p myparam1=myvalue1 -p myparam2=myvalue2 -o CACHE=off

reana-client start [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

-p, --parameter <parameters>

Additional input parameters to override original ones from reana.yaml. E.g. -p myparam1=myval1 -p myparam2=myval2.

-o, --option <options>

Additional operational options for the workflow execution. E.g. CACHE=off. (workflow engine - serial) E.g. –debug (workflow engine - cwl)

5.1.19. status

Get status of a workflow.

The status command allow to retrieve status of a workflow. The status can be created, queued, running, failed, etc. You can increase verbosity or filter retrieved information by passing appropriate command-line options.

Examples:

$ reana-client status -w myanalysis.42

$ reana-client status -w myanalysis.42 -v –json

reana-client status [OPTIONS]

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

--filter <_filter>

Filter output according to column titles (case-sensitive).

--json

Get output in JSON format.

-t, --access-token <access_token>

Access token of the current user.

-v, --verbose

Set status information verbosity.

5.1.20. stop

Stop a running workflow.

The stop command allows to hard-stop the running workflow process. Note that soft-stopping of the workflow is currently not supported. This command should be therefore used with care, only if you are absolutely sure that there is no point in continuing the running the workflow.

Example:

$ reana-client stop -w myanalysis.42–force
reana-client stop [OPTIONS]

Options

--force

Stop a workflow without waiting for jobs to finish.

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

5.1.21. upload

Upload files and directories to workspace.

The upload command allows to upload workflow input files and directories. The SOURCES argument can be repeated and specifies which files and directories are to be uploaded, see examples below. The default behaviour is to upload all input files and directories specified in the reana.yaml file.

Examples:

$ reana-client upload -w myanalysis.42

$ reana-client upload -w myanalysis.42 code/mycode.py

reana-client upload [OPTIONS] SOURCES

Options

-w, --workflow <workflow>

Name or UUID of the workflow. Overrides value of REANA_WORKON environment variable.

-t, --access-token <access_token>

Access token of the current user.

Arguments

SOURCES

Optional argument(s)

5.1.22. validate

Validate workflow specification file.

The validate command allows to check syntax and validate the reana.yaml workflow specification file.

Examples:

$ reana-client validate -f reana.yaml
reana-client validate [OPTIONS]

Options

-f, --file <file>

REANA specifications file describing the workflow and context which REANA should execute.