Command Line

The cyrus command line application that is used to submit API commands, retrieve the results, and check the status of running jobs. All available Cyrus APIs can be accessed using cyrus.

Installation

The cyrus command line application can be downloaded by logging into https://api-authorization.cyrusbio.com and clicking the “Get Files” button. Below are specific instructions for installing the application in Windows, MacOS, and Linux

Windows

  1. Download the Windows engine-client executable from https://api-authorization.cyrusbio.com

  2. Rename the file to cyrus.exe and move cyrus.exe into %USERPROFILE%\AppData\Local\Microsoft\WindowsApps

  3. Open PowerShell by opening the Windows menu and typing “PowerShell”

  4. Run cyrus help

  5. If the application is correctly installed you should see a usage message like this:

    A screenshot of the output of the cyrus help command. it shows basic usage instructions for the application

     

Mac OS

 In an upcoming release Cyrus will distribute the Command Line Application as a signed binary, which will make this installation progress significantly simpler by eliminating steps 4-6.  For now, follow these steps

  1. Download the MacOS binary from https://api-authorization.cyrusbio.com/

  2. Copy the binary with the following command: cp <binary-name> /usr/local/bin/cyrus

  3. Make the file executable with chmod +x /usr/local/bin/cyrus

  4. Run cyrus, you will see a window like the one below.  click “Cancel”:

    A screenshot of an error message in OS X. it says 'cyrus cannot be opened because the developer cannot be verified' and has two buttons labelled 'Move to Trash' and 'Cancel'
  5. Open “System Preferences”, Click “Security and Privacy” and then the “General” tab, you should see a window like the one below.  Click “Allow Anyway”:

     

  6. Run cyrus again, you will see another window like the one below. Click “Open”

     

Linux

  1. Download the Linux binary from https://api-authorization.cyrusbio.com/

  2. Copy the binary with the following command: cp <binary-name> /usr/local/bin/cyrus

  3. Make the file executable with chmod +x /usr/local/bin/cyrus

Upgrading

Once the command line application has been initially installed, it can be upgraded to the latest version by running the command cyrus upgrade. If an upgrade is available, you will be prompted to install it.

Initial Configuration

Before using the command line application for the first time, you need to initialize the configuration.  To do this, run

cyrus init

You will be asked to entire your API client ID, secret key, server, and port.  For server, you should enter the domain name you were given during onboarding (engine.<codename>.cyrusbio.com or engine.playground.cyrusbio.com) and for the port you should enter “443”. You can get your client ID and secret from api-authorization.cyrusbio.com.

Submitting Jobs

A job can be submitted with a command like this:

cyrus submit <job type> <job options>

Where <job type> and <job options> vary depending on the job being submitted.  See the specific documentation section for details.

The command will return a job ID and the username that the job was submitted under. The job ID is a unique ID which can be used to retrieve the results later.

the option --comment can be used to add a human readable comment to your job, this can be used to annotate jobs with information about the experiment being run, to make them easier to track.

Retrieving Results

To get the results of a completed job, run the following command: 

cyrus get <job id> --output-dir <output directory>

Where  <job id> is the ID of the job and <output directory> is the directory results should be output to.  The output directory will be created if it does not already exist. If the job is still Running, you cannot get the results yet and the command will exit.

Listing running jobs

To list the currently running jobs, run the following command:

cyrus list

This will result in a table listing the Job ID, status, age of the job, comments, and the options the job was run with.

Deleting jobs

To delete completed jobs, run the following command:

cyrus delete <job id>

where <job id> is the ID of a submitted job.