Orion CLI Quick Start for SaaS

The Orion CLI (OCLI) is a command line interface to the Orion Platform. It is installed as part of the Orion Platform Python package and lets you move data in and out of Orion, run jobs, and search molecules without writing any Python.

This guide walks through the basics for Orion SaaS users: the SaaS access levels, configuring a profile, uploading and downloading data, and running a job. For the complete list of commands and options, see the Orion CLI reference.

Before You Begin

OCLI is installed as part of the Orion Platform Python package. If you have not installed it yet, follow the Quick Start, then confirm the CLI is available:

(myvirtualenv) > ocli --help

Levels of OCLI Access

On Orion, the same OCLI is installed in every case. What you are allowed to do is controlled by the role and license assigned to your Orion account, giving two levels of access:

MT Modeler with API (Read-Only) (Light)

View, upload, and download Orion files, shard collections, and datasets (uploading a dataset requires a toolkit license). Also view existing jobs and molecule search databases and queries.

MT Modeler with API (Full)

Everything in the light level, plus starting and monitoring jobs and creating and running molecule search databases and queries.

ocli --help always lists every command regardless of your access level. More information about these and other roles can be found in the documentation of user profiles. If your role or license does not permit an action, ocli prints a helpful message instead of running it.

Note

Uploading Floe packages is not available at either level.

Configuring a Profile

Before OCLI can reach Orion, you must configure a profile with a token. Create a token by logging into Orion in a browser, opening your user profile, and clicking Create Token under My Tokens.

(myvirtualenv) > ocli config profile
Orion Url, ex: https://orion.eyesopen.us: <orion_url>
Orion Username: <orion_username>
Orion token: <orion_token>

See also

Reference: Configure an Orion Profile.

Working with Data

These data commands are available at both the light and full access levels.

Uploading a File

Upload a local file with ocli files upload. Orion returns the new file’s ID, which you use to refer to it later.

(myvirtualenv) > ocli files upload molecules.sdf
Uploaded file with id 1

Uploading a Dataset

To load molecules as a dataset (any OEChem-readable format except JSON), use ocli datasets upload. Orion runs the conversion for you and returns a dataset ID.

(myvirtualenv) > ocli datasets upload molecules.sdf
Created dataset with Id 1

Note

Uploading directly to a dataset requires a toolkit license. Uploading files and shard collections does not.

Uploading a Collection

A shard collection groups many files together under a single resource. Create one by uploading a list of files and giving it a name; Orion returns the new collection’s ID.

(myvirtualenv) > ocli collections upload my_collection shard1.oeb shard2.oeb
Created v1 collection with Id: 1 as /project/<project-id>/user/<username>/my_collection

Pass an existing collection’s ID instead of a name to add more files to it:

(myvirtualenv) > ocli collections upload <collection_id> shard3.oeb

A collection stays open for more uploads until you close it. Closing marks the collection ready and prevents further shards from being added; reopen it later if you need to add more:

(myvirtualenv) > ocli collections close <collection_id>
(myvirtualenv) > ocli collections open <collection_id>

Listing What You Have

List datasets you can access:

(myvirtualenv) > ocli datasets list

The same list pattern works for other Orion resources, for example ocli jobs list or ocli collections list.

Browse Orion’s virtual filesystem, just like ls on a local machine:

(myvirtualenv) > ocli ls /project/<project-id>/user/<username>/

Downloading Data

Download a dataset to your local filesystem, choosing any OEChem-writable format except JSON by the output file extension:

(myvirtualenv) > ocli datasets download <dataset_id> output.oeb.gz

Organizing Data

Create folders, move items between them, and remove items.

(myvirtualenv) > ocli mkdir /project/<project-id>/user/<username>/my_data
(myvirtualenv) > ocli mv dataset://<dataset_id> /project/<project-id>/team/
(myvirtualenv) > ocli rm /project/<project-id>/user/<username>/molecules.sdf --dry-run=True

Note

Add --dry-run=True to mv or rm to preview the change before it happens.

See also

Reference: Folders, Datasets, File Commands, and Collections.

Running a Job (Full)

Starting jobs requires the Full API level. A job is an instantiation of a WorkFloe; starting one is a three-step pattern: find the WorkFloe, start the job, then watch or fetch its logs. At the light level you can run the info, list, watch, and logs commands below, but not start or cancel.

Find the WorkFloe you want to run:

(myvirtualenv) > ocli workfloes list --name=<workfloe_name>

Start a job against that WorkFloe. --wait blocks until the job finishes, and appending -- --help prints the parameters a WorkFloe expects.

(myvirtualenv) > ocli jobs start <workfloe_id> "My Job" --wait \
    --in <dataset_id> --out results.oedb

Check on a job, follow it, or fetch its logs:

(myvirtualenv) > ocli jobs info <job_id>
(myvirtualenv) > ocli jobs watch <job_id>
(myvirtualenv) > ocli jobs logs <job_id>
(myvirtualenv) > ocli jobs cancel <job_id>

For floes with many parameters, export the parameters of a previous job to a JSON file, edit it, and reuse it with --param-file:

(myvirtualenv) > ocli jobs export-params <job_id> --output params.json
(myvirtualenv) > ocli jobs start <workfloe_id> "My Job Re-run" \
    --param-file params.json

See also

Reference: Jobs, Starting a Job, and WorkFloes. More worked examples live in the CLI examples page.

Searching Molecules (Full)

Creating databases and running queries requires the Full API level. Create and manage molecule search databases with ocli molsearch db and run queries against them with ocli molsearch query. At the light level you can list and inspect existing databases and queries, but not create or run them.

(myvirtualenv) > ocli molsearch db list
(myvirtualenv) > ocli molsearch query --help

See also

Reference: Molecule Search Database Commands and Molecule Search Query Commands.

Where to Go Next

  • Orion CLI — the complete command and option reference.

  • Orion Client examples — additional worked command line examples, including converting an uploaded file to a dataset with an ETL floe.

  • Global options such as --json, --timeout, and --max-retries are described in the Options section of the reference.