Manage via CLI

Overview

The Seven Bridges RHEO gives you the ability feature to run complex analysis workflows on the Seven Bridges Platform with minimal manual intervention.

The Command Line Interface allows you to manage the automations using commands which are described below.

Manage automations

Manage code packages

Manage automation members

Manage automation runs

Manage automations

List automations

List all automations you have access to. The list will return an ID for every automation which is required for issuing other commands for the automations (e.g. for listing automation members).

You can also list a single automation by using a name argument and specifying the exact name of the automation.

Usage:
sb automations list [--name <name>] [flags]
 
Arguments:
name The name of the specific automation you wish to list. The name must be an exact match.
 
Flags:
-h, --help

Create a new automation

Create a new automation.

Usage:
sb automations create --name <name>
 
Arguments:
name                              The automation name.
description                       The automation description.
billing-group <id>]               The ID of the billing group. This field is not required for Enterprise users.
secret-settings <json_string>]    User-defined secret settings for the automation (for example a password to authenticate against an external service).
memory_limit                                            The memory limit specified in MB. The default value is 500Mb while the maximum allowed is 4000Mb. If no limit is set for a code package or automation run, this value will be used.
project-based                      Use this argument to allow running automations directly from within your projects.                                       
 
Flags:
-h, --help

Get details of an automation

Get the details of a specified automation.

Usage:
sb automations get <automation-id>
 
Arguments:
automation-id   The ID of the specific automation you are querying. Use the list automations command to obtain the ID.
 
Flags:
  -h, --help

Edit an automation

Get the details of a specified automation by changing its name, billing group or secret settings.

Usage:
            sb automations update --automation-id <automation-id_value> [--name <name_value>] [--description <description_value>] [--secret-settings <secret-settings_value>] [--billing-group <billing-group_value>] [--project-based project-based_value>]
 
Arguments:
            automation-id       The ID of the specific automation you are querying. Use the list automations command to obtain the ID.
            name                The name of the automation.
            description         The automation description.
            secret-settings     The automation secret settings as json string. (default “{}“)
            billing-group       The automation billing group uuid as a string.
            project-based.      Use this argument to allow running automations directly from within your projects.
 
Flags:
  -h, --help

Archive an automation

Use this command to archive an automation. Archived automations can no longer be run, but can be restored. Previous automation runs of archived automations remain visible.

If you archive an automation, all accompanying code packages are archived as well.

Usage:
sb automations archive <automation-id>

 
Arguments:
automation-id   The ID of the automation you are archiving. Use the list automations command to obtain the ID.
 
Flags:
  -h, --help

Restore an automation

Restoring (or unarchiving) an automation makes the automation available for execution. If you restore an automation, all accompanying code packages are restored as well.

Usage:
sb automations restore <automation-id>

 
Arguments:
automation-id   The ID of the automation you are restoring. Use the list automations command to obtain the ID.
 
Flags:
  -h, --help

Manage code packages

Create a code package

The command for creating a code package. Use the file argument to specify the path to the code package file.

Usage:
sb automations packages create
 
Arguments:
automation-id                        The ID of the automation the code package is created for.
version                              The version identifier for this code package. Has to be unique within an automation.
file <local_path_to_file>    Path to local code package file created with 'freyja build' command.
memory_limit                             Set the memory limit for the code package, specified in MB. The default value is 500Mb while the maximum allowed is 4000Mb. If omitted, the limit will be inherited from the automation entity when creating an automation run. 
python                               Set Python version to be used when the Package is executed. If omitted, default version (3.8) will be used.

Flags:
-h, --help

List code packages

Automations can have multiple code packages. This command retrieves the list of deployed code packages for a specific automation or for all automations you have access to.

Usage:
sb automations packages list [--automation-id <automation-id>]
 
Arguments:
automation-id   The ID of the specific automation you are listing the code packages for. Use the list automations command to obtain the ID. If omitted, code packages from all automations the user has access to are listed.
 
Flags:
     -h, --help

Archive a code package

This command archives a code package .

Usage:
sb automations packages archive <package-id>
 
Arguments:
package-id   The ID of the code package you are archiving.
 
Flags:
-h, --help

Restore a code package

This command restores an archived code.

Usage:
sb automations packages restore <package-id>

Arguments:
package-id   The ID of the code package you are restoring.
 
Flags:
-h, --help

Output code package schema

Output the input-output schema for given a code package to the STDOUT.

Usage:
sb automations packages schema [--package_id <package_id>]
 
Arguments:
package-id   The ID of the specific code package you want the output the schema for.
 
Flags:
     -h, --help

Download code package file

To download a code package file associated with a code package entity, first get the file ID of the code package file using 'sb automations packages get' and then download the file using the 'sb download' command.

For this operation to be successful, you will need at least COPY permission on the automation.

Usage:
sb automations packages get <package-id> --output table
 
Arguments:
package-id   The ID of the specific code package you want to download.
 
Flags:
     -h, --help

Set a custom URL for a code package

This command sets a custom URL for a code package. Users get redirected to this URL when starting a new automation run on the automation GUI. This allows automation developers to provide their users with a customized automation setup page instead of using the default one.

Usage:
sb automations packages update --package-id <package-id_value> --custom-url <custom-url_value>
 
Arguments:
package-id   The ID of the specific code package you want to set the custom       URL for. Use the list code packages command to obtain the ID. 
custom_url   The URL you want to set for the code package.

Flags:
-h, --help

Manage automation members

The following commands are available for managing automation members.

List members

List all members of an automation. For each member, the response lists their username and permissions for the specified automation.

Usage:
sb automations members list --automation-id <automation-id>
 
Arguments:
automation-id   The ID of the specific automation you are querying. Use the list automations command to obtain the ID.
 
Flags:
-h, --help

Add an automation member

Add an existing Platform user to the automation and specify their permissions. Only automation admins can add new members to an automation.

Usage:
  sb automations members create --automation-id <automation-id_value> --user <user_value> --team <team_value> --division <division_value> --read --write --copy --execute --admin
 
Flags:
      --automation-id string   The ID of the automation you are adding a new member to.
      --user string            The username of the person you are adding to the automation.
      --team string            The ID of the team you are adding to the automation.
      --division string        Division slug you are adding to the automation.
      --read                   The member can view file names, metadata, and workflows. This is automatically assigned when a member is created. (default true)
      --write                  The member can add, modify, and remove files and workflows.
      --copy                   The member can view file content, copy, and download files.
      --execute                The member can execute workflows and abort automations.
      --admin                  The member can modify another user's permissions, add or remove people.
  -h, --help                   help for create

Delete a member

Delete a member from the automation. Only automation admins can delete other automation members.

Usage:
  sb automations members delete --automation-id <automation-id_value> [--user <user_value>] [--team <team_value>] [--division <division_value>]
 
Flags:
      --automation-id string   The ID of the automation from which you are removing a member.
      --user string            The username of the member you are removing. Can be a slug of division or id of team.
      --team string            The ID of the team you are removing.
      --division string        Division slug you are removing.
  -h, --help                   help for delete

Get member's permissions

Get information on member's permission in an automation.

Usage:
  sb automations members get --automation-id <automation-id_value> [--user <user_value>] [--team <team_value>] [--division <division_value>]
 
Flags:
      --automation-id string   The ID of the automation containing the member(s) whose permissions you are querying.
      --user string            The username of the member whose permissions you are querying.
      --team string            The ID of the team you are querying.
      --division string        Division slug you are querying.
  -h, --help                   help for get

Change member's permissions

Change member's permissions in an automation. Only automation admins can change permissions for automation members.

Usage:
  sb automations members update --automation-id <automation-id_value> [--user <user_value>] [--team <team_value>] [--division <division_value>] [--read] [--write] [--copy] [--execute] [--admin]
 
Flags:
      --automation-id string   The ID of the automation containing the member whose permissions you’d like to update.
      --user string            The username of the automation member whose permissions you are updating.
      --team string            The ID of the team that you are updating.
      --division string        Division slug that you are updating.
      --read                   This permission allows a automation member to view file names, metadata, and automations. Read permissions are assigned by default. (default true)
      --write                  This permission allows a automation member to add, modify, and remove files and automation.
      --copy                   This permission allows a automation member to view file content, copy, and download files.
      --execute                This permission allows a automation member to execute and abort automations.
      --admin                  This permission allows a automation member to modify another user's permissions and add or remove people.
  -h, --help                   help for update

Manage automation runs

List automation runs

List all automation runs, including all runs the user has access to, only those from a specific automation, only those from a specific code package, and/or filtered by specified criteria.

You can also use this command to obtain run IDs that are required for querying automation runs using the other available commands.

Usage:
sb automations runs list [--automation-id <automation-id>][--name <run-name>][--package-id <package-id>][--status <status> <status> ...][--created-by <username>][--created-from <created-from>[--created-to <created-to> ][--order-by <attribute>][--order [asc|desc]]
 
Arguments:
automation-id          The ID of the specific automation you are listing the runs for. Use the list automations command to obtain the ID.
name                   The name of the automation run you want to list. The search is partial and case-insensitive.
package-id             The ID of the code package you are listing the automation runs for.
status                 Filter the automation runs by their status.
created-by <username>  List runs for the specified user.
created-from           Enter the starting date for querying automation runs started on the specified date and onwards (see below for more information).
created-to             Enter the ending date for querying automation runs before the specified date. You can use it in combination with the created_from to specify a time interval.
order-by <attribute>     Return results sorted by this attribute name, e.g. ‘created_by’, ‘created_from’, etc. By default results are sorted by ‘created_on’ in descending order (most recent first).
      [--order [asc|desc] ] 
 
Flags:
     -h, --help

Get details of an automation run

Get details of a specific automation run. The response will also include output values which are mapped to the schema.

Usage:
sb automations runs get <run-id>

Arguments:
run-id   The ID of the specific automation run you are querying. Use the list automation runs command to obtain the ID.
 
Flags:
-h, --help

Start a new automation run

Start a new automation run.

Usage:
      sb automations start [<filename>] [--name <name_value>] [--package-id <package-id_value>] [--inputs <inputs_value>] [--settings <settings_value>] [--resume-from <resume-from_value>] [--automation-id <automation-id_value>] [--automation-name <automation-name_value>] [--secret-settings <secret-settings_value>] [--memory-limit <memory-limit_value>] [flags]
 
Arguments:
      filename                   File path to a yaml or json file which contains parameter values.
 
Flags:
      --name string              Name of automation run.
      --package-id string        Id of the package used.
      --inputs string            Automation run inputs as json string. (default "{}")
      --settings string          Automation run settings as json string. (default "{}")
      --resume-from string       Automation run from which to resume.
      --automation-id string     Id of the automation.
      --automation-name string   Name of automation. Must be exact match.
      --secret-settings string   Automation run secret settings as json string. (default "{}")
      --memory-limit int         Automation run memory limit in MB. If omitted, memory limit of code package or automation entity is used, in that order.
  -h, --help                     help for start

The 'inputs' will be mapped to input ports of the main step of the automation, while settings are added to the automation configs and accessed via the config_ attribute present in all steps.

Provide parameters via YAML or JSON file

Alternatively, you can provide the automation parameters in a YAML or JSON file. This will allow you to maintain automation parameters inside an organized and annotated file template instead of providing the arguments (in particular automation inputs, settings, and secret settings) in form of a long command line string. Note that the command line flags override values set in the parameters file.

When starting a new automation, you can modify the local YAML or JSON file and then provide the file path as an argument to the sb automations start command.

Usage:
      $ sb automations start file-name.yml

automation-name: rna-seq
name: rna-seq run using file-name.yml
inputs:
  string_input: string-value
  boolean_flag: True
  input_files:
    - 6077d039bafb037fca80ca12 # Platform file IDs
    - 6077d039bafb037fca80ca34
secret-settings:
  secret_key: 1234

Stop an automation

Stop a running automation.

Usage:
sb automations stop <run-id>

Arguments:
run-id   The ID of the specific automation run you are stopping. Use the list automation runs command to obtain the ID.
 
Flags:
-h, --help

Rerun an automation

Reruns an automation. To rerun an automation, specify the ID of the automation run you wish to rerun. The inputs and settings are automatically taken from the originating run unless new inputs and settings are provided.

In addition, you can specify a different code package allowing you to run a different version of the automation while preserving all other settings.

Usage:
        sb automations rerun [--name <name_value>] [--inputs <inputs_value>] [--package-id <package-id_value>] [--settings <settings_value>] [--resume-from <resume-from_value>] --automation-run-id
        <automation-run-id_value> [--secret-settings <secret-settings_value>] [--merge] [flags]

Arguments:

        run-id      The ID of the automation run you are rerunning. Use the list automation runs command to obtain the ID.
        merge       If specified, the new inputs and settings are added to previous ones instead of replacing them.
        memory_limit Set the memory limit for the rerunning an automation, specified in MB. The default value is 500Mb while the maximum allowed is 4000Mb.  

Flags:
  -h, --help

Edit an automation run

Update automation run details. Only the run name can be changed, all other attributes are currently read-only.

Usage:
sb automations runs update --run-id <run-id_value> [--name <name_value>]
  
Arguments:
--name New name of automation run.
 
Flags:
-h, --help

Access automation run log file

This command outputs the content of the log file to the terminal. The exact number of the most recent lines the log should return is determined using the last argument. Still active automation runs may have their log entries delayed for up to 2 minutes.

Usage:
sb automations log <automation_run_id> [--last <last_value>]

Arguments:
automation_run_id     The ID of the automation run you are querying.
last                  The number of most recent lines the log should return.                     
  
Flags:
  -h, --help

View the automation state file

View the current content of the automation state file.

Usage:
sb automations state <run-id>

Arguments:
run-id   The ID of the specific automation run you are viewing the state file for. Use the list automation runs command to obtain the ID.
 
Flags:
-h, --help

The output of this command can be piped into standard linux tools like 'grep' and 'less' or redirected to a file to save permanently.

Run state information supports streaming, i.e. current state information can be retrieved while the automation is still running.