Contact Us
Orca Knowledge Base
Table of Contents
< All Topics
Print

Orca Command Line Interface (CLI)

PostedJune 11, 2024
UpdatedJune 11, 2024
Bymichaeltsalmi

Overview

Orca’s Command Line Interface (CLI) is designed to streamline lab automation workflows by leveraging a YAML configuration file. This section provides documentation on how to use the CLI to manage and run your lab automation processes.

Getting Started

Prerequisites:

  • Ensure Python is installed on your system.
  • Install any necessary dependencies for Orca.
  • Ensure all equipment being used has appropriate drivers and Orca adapters
  • Ensure you have a properly formatted configuration file you would like to use

Launching the Orca Shell:

python path/to/orca.py

This command opens the Orca shell, where you can enter various commands to manage your workflows.

Commands

1. load

Description: Loads the configuration file into the Orca system.

Usage:

load --config <path_to_config_file>

Options:

  • --config <path_to_config_file>: Specifies the path to the YAML configuration file.

Example:

load --config examples/smc_assay/smc_assay_example.yml

2. init

Description: Initializes the lab instruments based on the configuration file.

Usage:

init [--config <path_to_config_file>] [--resources <resource_list>]

Options:

  • --config <path_to_config_file>: Specifies the path to the YAML configuration file. If not provided, the previously loaded configuration is used.
  • --resources <resource_list>: A comma-separated JSON list of resources to initialize. If not provided, all resources are initialized.

Example:

init --config examples/smc_assay/smc_assay_example.yml --resources [resource1, resource2]

3. run

Description: Runs the specified workflow.

Usage:

run --workflow <workflow_name> [--config <path_to_config_file>] [--stage <development_stage>]

Options:

  • --workflow <workflow_name>: Specifies the name of the workflow to be run. This name must match a workflow name defined in the configuration file.
  • --config <path_to_config_file>: Specifies the path to the YAML configuration file. If not provided, the previously loaded configuration is used.
  • --stage <development_stage>: Specifies the development stage to be run (e.g., prod, dev). If not provided, dev is run.

Example:

run --workflow sample_workflow --config examples/smc_assay/smc_assay_example.yml

4. run-method

Description: Runs a specific method within a workflow.

Usage:

run-method --method <method_name> --start-map <start_map_json> --end-map <end_map_json> [--config <path_to_config_file>] [--stage <development_stage>]

Options:

  • --method <method_name>: Specifies the name of the method to be run. This name must match a method name defined in the configuration file.
  • --start-map <start_map_json>: A JSON dictionary of labware mapped to it’s desired starting location. Labware names must match labware names defined in the method specified within the configuration file.
  • --end-map <end_map_json>: A JSON dictionary of labware mapped to it’s desired starting location. Labware names must match labware names defined in the method specified within the configuration file.
  • --config <path_to_config_file>: Specifies the path to the YAML configuration file. If not provided, the previously loaded configuration is used.
  • --stage <development_stage>: Specifies the development stage to be run (e.g., prod, dev). If not provided, dev is run.

Example:

run-method --method sample_method --start-map '{"plate-1": "pad-1", "final-plate": "pad-2"}' --end-map '{"plate-1": "pad-4", "final-plate": "pad-5"}' --config examples/smc_assay/smc_assay_example.yml

5. exit or quit

Description: Exits the Orca shell.

Usage:

exit

or

quit

Detailed Command Usage

load Command

  • Purpose: To load a configuration file into the Orca system.
  • When to use: Use this command at the beginning to load the necessary configuration before initializing or running workflows.

init Command

  • Purpose: To initialize lab instruments based on the provided configuration.
  • When to use: After loading the configuration file, use this command to set up the lab instruments before executing workflows or methods.

run Command

  • Purpose: To execute a predefined workflow from the configuration file.
  • When to use: Use this command to run an entire workflow as defined in your configuration file.

run-method Command

  • Purpose: To execute a specific method within a workflow.
  • When to use: Use this command to run individual methods for testing or specific tasks without executing the entire workflow. Useful for recovering runs during an error.

exit and quit Commands

  • Purpose: To exit the Orca shell.
  • When to use: Use these commands to terminate the Orca shell session.

Example Workflow

  1. Loading Configuration File: load --config examples/smc_assay/smc_assay_example.yml
  2. Initializing Instruments: init
  3. Running a Workflow: run --workflow sample_workflow
  4. Alternatively, Running a Specific Method:
    run-method --method sample_method --start-map '{"labware1": "location1"}' --end-map '{"labware1": "location2"}'