Robocorp CLI user manual

Robocorp CLI, part of the Robocorp Developer Tool, is a command-line tool that you can use to simplify creating, packaging, executing locally, and uploading your activities to Robocorp Cloud.

Here we look in detail at each command that the tool provides. For an example workflow and more information check out this article.

Overview

You can get a list of all available commands by calling the robo command with no arguments:

$ robo

usage: robo [-h] [--version]
            {activities,authorize,credentials,download,fix,init,libs,run,unwrap,upload,workspace,wrap}
            ...

Robocorp CLI -- command line tool for robocloud. Version number: 4.1.10

positional arguments:
  {activities,authorize,credentials,download,fix,init,libs,run,unwrap,upload,workspace,wrap}
                        command to be executed
    activities          List or update tracked activity directories.
    authorize           Convert an API key to a valid authorization JWT token.
    credentials         Save Robocorp Cloud API credentials for later use.
    download            Fetch an existing package from Robocorp Cloud.
    fix                 Automatically fix known issues inside packages.
    init                Create a directory structure and CLI support
                        structures for a package.
    libs                Manage library dependencies in an action oriented way.
    run                 Execute a specific activity (entrypoint).
    unwrap              Unpack a package back into a directory structure.
    upload              Push an existing package to Robocorp Cloud.
    workspace           Listing available workspaces and their activities.
    wrap                Build a package out of directory content.

optional arguments:
  -h, --help            show this help message and exit
  --version, -v         show program's version number and exit

You can get more information about the usage of each command by using the -h or --help optional argument. For example, calling:

robo init --help

would show details about the usage and supported arguments for the init command.

The robo command follows the principles of the Unix Philosophy. As a consequence, for example, when the command runs successfully, it returns a successful exit status, but no additional output unless necessary for the specific command.

The activities command

The robo activities command returns a list of the directories on your local system that have been initialized using the robo init command. The creation and last updated timestamps are shown for each of the listed directories.

usage: robo activities [-h] [--json] [--account ACCOUNT] [--config CONFIG]
                       [--debug]
                       [directory]

List or update tracked activity directories.

positional arguments:
  directory             directory to be used for this command

optional arguments:
  -h, --help            show this help message and exit
  --json, -j            output result in json format
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples:

$ robo activities

Updated at       | Created at       | Activity directory
29.03.2020 21:50 | 29.03.2020 09:54 | /home/user/robo/spacex-robot
01.04.2020 15:41 | 01.04.2020 15:41 | /home/user/robo/simple-robot

Using the --json parameter:

$ robo activities --json

[
  {
    "updated": 1585507839.171554,
    "created": 1585464882.9330618,
    "activity": "/home/user/robo/spacex-robot",
    "deleted": null
  },
  {
    "updated": 1585744909.381839,
    "created": 1585744909.381839,
    "activity": "/home/user/robo/simple-robot",
    "deleted": null
  },

The authorize command

The robo authorize command can be used to issue a valid JWT token to interact with a specific workspace in Robocorp Cloud.

usage: robo authorize [-h] [--minutes MINUTES] --workspace WORKSPACE
                      [--silent] [--account ACCOUNT] [--config CONFIG]
                      [--debug]

Convert an API key to a valid authorization JWT token.

optional arguments:
  -h, --help            show this help message and exit
  --minutes MINUTES, -m MINUTES
                        how many minutes authorization should be valid
  --workspace WORKSPACE, -w WORKSPACE
                        integer workspace id to use with this command
  --silent              do action silently, without showing any output
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Issue a JWT token for the Robocorp Cloud workspace with id 123, valid for the next 20 minutes:

robo authorize --workspace 123 --minutes 20

{
  "token": "TOKEN_VALUE_HERE",
  "expiresIn": 1200,
  "status": 200,
  "requested": {
    "expiresIn": 1200,
    "capabilities": {
      "secret": {
        "read": true
      },
      "livedata": {
        "read": true,
        "write": true
      },
      "workitemdata": {
        "read": true,
        "write": true
      },
      "artifact": {
        "write": true
      }
    }
  },
  "endpoint": "https://api.eu1.robocloud.eu/"
}

The credentials command

The robo credentials command allows you to grant access to your user account to the Robocorp CLI. In Robocorp Cloud, you can create one or more Access credentials, that you can use to perform operations acting as your user account.

usage: robo credentials [-h] [--json] [--endpoint ENDPOINT]
                        [--account ACCOUNT] [--config CONFIG] [--debug]
                        [credentials]

Save Robocorp Cloud API credentials for later use.

positional arguments:
  credentials           Robocorp Cloud API credentials to store

optional arguments:
  -h, --help            show this help message and exit
  --json, -j            output result in json format
  --endpoint ENDPOINT, -e ENDPOINT
                        Robocorp Cloud endpoint that this credentials belongs to.
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Example

To add these hypothetical access credentials obtained from Robocorp Cloud: 1:123456789abcd, you would use:

robo credentials 1:123456789abcd

The download command

The robo download command allows you to download the code for an existing activity in Robocorp Cloud as a ZIP archive.

usage: robo download [-h] [--force] [--package PACKAGE] --workspace WORKSPACE
                     --activity ACTIVITY [--account ACCOUNT] [--config CONFIG]
                     [--debug]

Fetch an existing package from Robocorp Cloud.

optional arguments:
  -h, --help            show this help message and exit
  --force               remove all safety nets and trust that you know what
                        you are doing
  --package PACKAGE, -p PACKAGE
                        filename for package (default: package.zip)
  --workspace WORKSPACE, -w WORKSPACE
                        integer workspace id to use with this command
  --activity ACTIVITY   integer activity id to use with this command
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Example

Download the code for the activity with id '123' in the workspace with id 456 into the current directory:

robo download --workspace 456 --activity 123

You can get the correct command ready to be copy-pasted into your terminal from each activity's detail page in the Robocorp Cloud UI, in the Robocorp CLI Assist section.

The fix command

The robo fix command allows you to fix issues in a directory that contains an activity package.

usage: robo fix [-h] [--directory DIRECTORY] [--dryrun] [--silent]
                [--account ACCOUNT] [--config CONFIG] [--debug]

Automatically fix known issues inside packages.

optional arguments:
  -h, --help            show this help message and exit
  --directory DIRECTORY, -d DIRECTORY
                        path of the directory the command will use (default:
                        .)
  --dryrun              do not actually do actions, just show what would be
                        done
  --silent              do action silently, without showing any output
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Fix the package contained in the current directory:

$ robo fix

Fixing executable files:
  + processing directory: entrypoints
  + processing directory: bin

Fix the package contained in the /home/user/package directory:

$ robo fix --directory /home/user/package

Fixing executable files:
  + processing directory: /home/user/package/entrypoints
  + processing directory: /home/user/package/bin

The init command

The robo init command allows you to create the initial directory structure and needed support files to create an activity package.

You can learn more about the initial directory structure here.

usage: robo init [-h] [--account ACCOUNT] [--config CONFIG] [--debug]
                 [directory]

Create a directory structure and CLI support structures for a package.

positional arguments:
  directory             directory to be used for this command

optional arguments:
  -h, --help            show this help message and exit
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Initialize an activity package in the current folder:

robo init

Initialize an activity package in the /home/user/package directory:

robo init --directory /home/user/package

The libs command

The robo libs command can be used to manage the library dependencies of an activity package.

When running in Robocorp Lab or Robocorp Cloud via the Robocorp App, the environment for your activity package will be prepared based on the contents of your config/conda.yml file. This command provides an action-oriented way to manage the dependencies for your activity package.

You can learn more about the initial directory and the conda setup here.

usage: robo libs [-h] [--conda CONDA] [--name NAME] [--add] [--remove] [--pip]
                 [--channel] [--json] [--account ACCOUNT] [--config CONFIG]
                 [--debug]
                 [detail]

Manage library dependencies in an action-oriented way.

positional arguments:
  detail                detail to add or remove

optional arguments:
  -h, --help            show this help message and exit
  --conda CONDA         optional path to the environment yaml file (default:
                        config/conda.yaml)
  --name NAME, -n NAME  change name of configuration
  --add                 add new library as requirement
  --remove, -r          remove library from requirements
  --pip, -p             operate on pip packages (the default is to operate on
                        conda packages)
  --channel             operate on channels (default is packages)
  --json, -j            output result in json format
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Add the numpy package using conda:

robo libs --add numpy

Add the robotframework-archivelibrary package using pip:

robo libs --add --pip robotframework-archivelibrary

Use the --pip argument for packages that are not available via conda.

Remove the robotframework-archivelibrary package:

robo libs --remove robotframework-archivelibrary

The run command

The robo run command allows you to run an activity package locally.

The command expects an entry point file. The entry point file is referenced directly without a relative path.

You can only run activities that have been packaged via the robo wrap command. While developing, remember to wrap your activity before running it. Otherwise, you might be running an outdated version of the activity.

usage: robo run [-h] [--package PACKAGE] [--variables VARIABLES]
                [--workarea WORKAREA] [--workspace WORKSPACE]
                [--account ACCOUNT] [--config CONFIG] [--debug]
                entrypoint

Execute a specific activity (entrypoint).

positional arguments:
  entrypoint            entrypoint to execute in this run

optional arguments:
  -h, --help            show this help message and exit
  --package PACKAGE, -p PACKAGE
                        filename for package (default: package.zip)
  --variables VARIABLES, -v VARIABLES
                        json file for environment variables (optional)
  --workarea WORKAREA   path to a directory to be used as workarea (default:
                        temp)
  --workspace WORKSPACE
                        integer workspace id for authorization
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Execute the activity in the current directory using the entrypoint.sh entry point:

robo run entrypoint.sh

Execute the activity in the current directory using the entrypoint.cmd entry point:

robo run entrypoint.cmd

Execute the activity in the current directory using the entrypoint.sh entry point, specifying a file that contains the environment variables to use:

robo run entrypoint.sh -v devdata/env.json -v devdata/env.json

The unwrap command

The robo unwrap command will unpack a package file back into a directory structure.

usage: robo unwrap [-h] [--force] [--directory DIRECTORY] [--package PACKAGE]
                   [--account ACCOUNT] [--config CONFIG] [--debug]

Unpack a package back into a directory structure. This command expects to get
package filename, and target directory. And using --force option, files will
be overwritten.

optional arguments:
  -h, --help            show this help message and exit
  --force               remove all safety nets and trust that you know what
                        you are doing
  --directory DIRECTORY, -d DIRECTORY
                        path of the directory the command will use (default:
                        .)
  --package PACKAGE, -p PACKAGE
                        filename for package (default: package.zip)
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Unpack a package with the name package.zip into the current directory:

robo unpack

Unpack a package with the name my-custom-package.zip into the current directory:

robo unpack --package my-custom-package.zip custom-directory

Unpack a package with the name my-custom-package.zip into a directory called my_directory:

robo unpack --package my-custom-package.zip --directory my_directory

The directory specified with the --directory parameter needs to exist beforehand.

The upload command

The robo upload command allows you to upload a package to an activity in Robocorp Cloud.

usage: robo upload [-h] [--force] [--package PACKAGE] --workspace WORKSPACE
                   --activity ACTIVITY [--account ACCOUNT] [--config CONFIG]
                   [--debug]

Push an existing package to Robocorp Cloud.

optional arguments:
  -h, --help            show this help message and exit
  --force               remove all safety nets and trust that you know what
                        you are doing
  --package PACKAGE, -p PACKAGE
                        filename for package (default: package.zip)
  --workspace WORKSPACE, -w WORKSPACE
                        integer workspace id to use with this command
  --activity ACTIVITY   integer activity id to use with this command
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Upload the existing package.zip file in the current directory as the code for the activity with id 123 in the workspace with id 456:

robo upload --workspace 456 --activity 123

You can get the correct command ready to be copy-pasted into your terminal from each activity's detail page in the Robocorp Cloud UI, in the Robocorp CLI Assist section.

The Workspace command

The robo workspace command allows you to list the workspaces associated with an account.

usage: robo workspace [-h] [--json] [--workspace WORKSPACE]
                      [--account ACCOUNT] [--config CONFIG] [--debug]

Listing available workspaces and their activities.

optional arguments:
  -h, --help            show this help message and exit
  --json, -j            output result in json format
  --workspace WORKSPACE, -w WORKSPACE
                        integer workspace id to use with this command
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

List the workspaces associated with the current account:

robo workspace

Identifier Type     Short                 Name (URL)
  xxx      private  private               John Doe (https://cloud.robocorp.com/private)
  xxx      shared   acmecompanyworkspace  Acme Company Workspace (https://cloud.robocorp.com/acmecompany)

The wrap command

The robo wrap command allows you to package your activity code into a ZIP file, ready to be executed locally or uploaded to Robocorp Cloud.

usage: robo wrap [-h] [--force] [--directory DIRECTORY] [--package PACKAGE]
                 [--ignore IGNORE] [--account ACCOUNT] [--config CONFIG]
                 [--debug]

Build a package out of directory content. This command expects to get package
filename, source directory, and an optional ignore file. When --force flag is
given, the existing package file will be overwritten.

optional arguments:
  -h, --help            show this help message and exit
  --force               remove all safety nets and trust that you know what
                        you are doing
  --directory DIRECTORY, -d DIRECTORY
                        path of the directory the command will use (default:
                        .)
  --package PACKAGE, -p PACKAGE
                        filename for package (default: package.zip)
  --ignore IGNORE, -i IGNORE
                        filename for ignore patterns
  --account ACCOUNT, -a ACCOUNT
                        account to use with this command
  --config CONFIG, -c CONFIG
                        path to configuration file
  --debug               be more verbose on output (for debugging purposes)

Examples

Wrap the activity contained in the current folder.

robo wrap

Wrap the activity contained in the current folder, overwriting the existing package file, if found:

robo wrap --force

Wrap the activity contained in the current folder into a file called my-package.zip

robo wrap --package my-package.zip

Wrap the activity contained in the current folder, excluding files that match patterns defined in a file called ignorefile.txt:

robo wrap --ignore ignorefile.txt

The ignore file follows the .gitignore file format, so you can reuse your existing .gitignore file, or create a new file only for this purpose.