16.1. Overview of clara

clara is a command line interface for managing and interacting with the Clara Deploy SDK. clara looks for a file named config.yaml in ~/.clara/. You can specify an alternate configuration by setting the --config flag and can point to a remote host using the --host flag. You can execute commands with --verbose flag to get command output with additional details.

Note: Using kubectl and/or argo cli to manage clara jobs might leave clara in an inconsistent state.

16.1.1. Syntax

Use the following syntax to run clara commands from you terminal window:

clara [command] [type] [flags]

  • command: Specifies the operation to perform on one or more resources. clara supports several commands: create, delete, describe, download, list etc. These commands are explained in detail in the clara commands documentation.

  • type: Specifies the resource type. Resource types are case-sensitive. Currently, clara has four resource types: “pipeline”, “job”, “model” and “payload” . Many commands do not support every type. For more information on which types are supported by an individual command, run clara [command] --help.

  • flags: Specifies optional or required flags. For example, you can use the --config flag to specify the location of an alternate configuration.

If you need help, run clara --help from the terminal window.

16.1.2. Commands

The following table includes short descriptions and the general syntax for all clara commands. This table will expand as support is added for additional commands.

Command

Syntax

Description

cancel

clara cancel [flags]

Cancel a resource

config

clara config [flags]

Configures NGC credentials for CLI

create

clara create [type] [flags]

Create a resource.

delete

clara delete  [type] [flags]

Delete a resources.

describe

clara describe [type] [flags]

Describe a resource.

download

clara download JOB_ID:SRC_PATH [DEST_PATH] [flags]

Download files associated with a job.

list

clara list [type] [flags]

List all instances of specified resource type.

logs

clara logs [flags]

Read clara job operator logs.

start

clara start [type] [flags]

Start a resource.

upload

clara upload [flags]

Upload a resource

version

clara version

Displays the clara cli and clara platform version info

For more information about a command, enter clara [command] --help in your terminal window.

16.1.3. Resource Types

The following table includes a list of all the supported resource types. This table will expand as we add support for additional resource types.

Note: Many commands do not support every type. For more information on which types are supported by an individual command, run clara [command] --help.

Resource Name

API Service

Description

pipeline

Pipelines Service

References a single pipeline in the Clara Deploy SDK.

job

Jobs Service

References a single instance of a pipeline execution on a payload in Clara Deploy SDK.

model

Models Service

References a TRITON model

payload

Payloads Service

References a single payload in Clara Deploy SDK.

pipelines

Pipelines Service

References pipelines in the Clara Deploy SDK.

jobs

Jobs Service

References instances of pipeline executions on a payload in Clara Deploy SDK.

model

Models Service

References TRITON models

payloads

Payloads Service

References payloads in Clara Deploy SDK.

For more information about resource types, enter clara [command] [type] --help in your terminal window.

16.1.4. Examples: Common Operations

Use the following set of examples to help you familiarize yourself with running the commonly used clara operations:

# Configure NGC credentials for use by CLI. Default 'orgteam' is 'nvidia/clara'
$ clara config --key NGC_API_KEY [--orgteam NGC_ORG/NGC_TEAM] [-y|--yes]

# Upload model
$ clara create model -p [MODEL_DIRECTORY] -t [MODEL_TYPE] [--raw]

# List models
$ clara list models

# Create a new pipeline
$ clara create pipeline -p PIPELINE_DEFINITION_FILE

# See the pipeline definition being used
$ clara describe pipeline -p PIPELINE_ID

# Create a new job
$ clara create job -n NAME -p PIPELINE_ID [-f [FILE | DIRECTORY]] [-i JOB_PRIORITY] [--start]

# Start a created job
$ clara start job -j JOB_ID [-a KEY=VALUE]...

# Get job status and associated information
$ clara describe job -j JOB_ID

# Get list of jobs
$ clara list jobs [--all | --canceled | --faulted] [--quiet]

# Get list of all pipelines
$ clara list pipeliens

# Submit request to cancel job(s)
$ clara cancel jobs [-j JOB_ID1,JOB_ID2...] [--all]

# Upload payload
$ clara upload payload -p PAYLOAD_ID -f {FILE | DIRECTORY}

# Delete payloads
$ clara delete payloads -p PAYLOAD_ID[,PAYLOAD_ID...]

16.1.5. Plugins

Plugins extend clara functionality. They are described in more detail in the plugin overview document.

16.1.5.1. Examples: Creating and Using Plugins

Use the following set of examples to help you familiarize yourself with writing and using clara plugins:

# Create a simple plugin in any language and name the resulting executable file
# so that it begins with the prefix "clara-"
$ cat ./clara-hello
#!/bin/bash

# This plugin prints the words "hello world"
echo "hello world"

# With our plugin written, let's make it executable
$ sudo chmod +x ./clara-hello

# and move it to a location in our PATH
$ sudo mv ./clara-hello /usr/local/bin

# We have now created and "installed" a Clara plugin.
# We can begin using our plugin by invoking it from clara as if it were a regular command
$ clara hello
hello world
# We can "uninstall" a plugin by simply removing it from our PATH
$ sudo rm /usr/local/bin/clara-hello

We can think of plugins as a means to build more complex functaionlity on top of the existing kubectl commands.

16.1.5.2. Examples: Using the clara-platform plugin

clara-platform plugin is a command-line interface for managing clara deploy platform. More information about clara-platform can be found here.

# Start the Clara Deploy SDK (clara platform must be pulled for this command to work. See `clara-pull` plugin below)
$ clara platform start

# Stop the Clara Deploy SDK
$ clara platform stop

# Restart the Clara Deploy SDK
$ clara platform restart

16.1.5.3. Examples: Using the clara-dicom plugin

clara-dicom manages a DICOM Adapter that facilitates the input and output of DICOM files to and from the Clara Deploy SDK. More information about clara-dicom can be found here.

# Start the DICOM Adapter with default configuration
$ clara dicom start

# Start the DICOM Adapter with custom configuration
$ clara dicom start -f CONFIG-FILE

# Restart the DICOM Adapter
$ clara dicom restart

# Stop the DICOM Adapter
$ clara dicom stop

# Add (SCP) AE Title-Pipeline mapping
$ clara dicom create aetitle [-n NAME] -a AE_TITLE [-o] [-i UID1,UID2,UID3] [-p Job.Processor.Assembly.NameSpace.Class] key1=value1 key2=value2 key3=value3

# Delete (SCP) AE Title-Pipeline mapping
$ clara dicom delete aetitle -n NAME

# List all (SCP) AE Title-Pipeline mappings
$ clara dicom list aetitle

# Add DICOM Source for SCP
$ clara dicom create source -a AE_TITLE -i HOSTNAME_IP

# Delete DICOM Source of SCP
$ clara dicom delete source -n NAME

# List all DICOM Sources of SCP
$ clara dicom list source

# Add DICOM Destination for Clara SCU
$ clara dicom create destination -a AE_TITLE -i HOSTNAME_IP -N NAME -p PORT

# Delete DICOM Destination of SCU
$ clara dicom delete destination -n NAME

# List all DICOM Destinations of SCU
$ clara dicom list destination

16.1.5.4. Examples: Using the clara-render plugin

clara-render manages a cinematic render service that facilitates visualizing medical images that are output from the Clara Deploy SDK. More information about clara-render can be found here.

# Start the render service
$ clara render start

# Restart the render service
$ clara render restart

# Stop the render service
$ clara render stop

16.1.5.5. Examples: Using the clara-pull plugin

clara-pull facilitates installation of different Clara Components and Reference Pipelines. More information about clara-pull can be found here. If a version is not specified, the latest version of the resource is downloaded.

# Pull clara platform helm charts and configure CLI
$ clara pull platform [ -v VERSION_NUMBER ][ -y | --yes ]

# Pull clara dicom-adapter helm charts and configure CLI
$ clara pull dicomadapter [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull dicom-adapter [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull dicom [ -v VERSION_NUMBER ][ -y | --yes ]

# Install clara-renderer helm charts
$ clara pull clararenderer [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull clara-renderer [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull render [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull renderer [ -v VERSION_NUMBER ][ -y | --yes ]

# Install clara-monitor-server helm charts
$ clara pull claramonitoring [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull clara-monitor-server [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull monitor [ -v VERSION_NUMBER ][ -y | --yes ]
$ clara pull monitoring [ -v VERSION_NUMBER ][ -y | --yes ]

# Install clara management console helm charts
$ clara pull claraconsole [ -v VERSION_NUMBER ] [ -y | --yes ]
$ clara pull clara-console [ -v VERSION_NUMBER ] [ -y | --yes ]
$ clara pull console [ -v VERSION_NUMBER ] [ -y | --yes ]

# Pull clara pipeline
$ clara pull pipeline [-v VERSION_NUMBER] [-d DESTINATION_DIR]

16.1.5.5.1. Examples: Using the clara-monitor plugin

clara-monitor manages the monitoring service that monitors the logs of various clara components. More information about clara-monitor can be found here.

# Start the monitor server (clara monitoring chart must be pulled for this command to work)
$ clara monitor start

# Restart the monitor service
$ clara monitor restart

# Stop the monitor service
$ clara monitor stop

16.1.5.5.2. Examples: Using the clara-console plugin

clara-console manages the Clara Management Console instance. More information about clara-console can be found here.

# Start the Clara Management Console (the Clara Management Console chart must be pulled for this command to work)
$ clara console start

# Restart the Clara Management Console
$ clara console restart

# Stop the Clara Management Console
$ clara console stop