The ado CLI

ado comes with a CLI utility that is designed to be familiar for users of kubectl and oc. It allows creating and retrieving resources, managing multiple backends, executing actuators, and more.

This page provides documentation for every command that we support, presented in alphabetical order. Refer to the navigation pane on the left to go to the section you are more interested in.

CLI reference¶

ado¶

ado supports a set of generic options that are passed down to all the other commands.

ado [--context | -c <context-file.yaml>] \
    [--log-level | -l <value>]

• --context | -c allows overriding the active context with one loaded from a file. This feature should only be used when running on remote Ray clusters.
• --log-level | -l configures the logging level. This does not affect child processes.

Resource Type Shorthands¶

Many ado CLI commands accept resource types as arguments. To make commands more concise, ado supports shorthand aliases for resource type names. You can use either the full name or the shorthand interchangeably in any command.

Available Shorthands¶

Usage Examples¶

# These commands are equivalent:
ado get discoveryspace space-abc123
ado get space space-abc123

# These commands are equivalent:
ado create actuatorconfiguration -f config.yaml
ado create ac -f config.yaml

# These commands are equivalent:
ado delete operation op-xyz789
ado delete op op-xyz789

ado context¶

ado supports storing configuration and authentication details for multiple backends, which in ado terms are called contexts.

The complete syntax of the ado context command is as follows:

ado context [CONTEXT_NAME]

Examples¶

Getting the current context¶

Similar to oc project, users can see the name of the currently active context by running:

ado context

Listing available contexts¶

Similar to oc projects, users can list available contexts by running:

ado contexts

It's also possible to output this information in multiple formats via the -o/--output flag:

# List context names only
ado contexts -o name

# Export contexts as YAML
ado contexts -o yaml

# Export contexts as JSON
ado contexts -o json

Switching between contexts¶

To switch between the available contexts, specify the target context name to the ado context command. In this example we assume that the my-context context exists:

ado context my-context

ado create¶

The ado CLI provides the create command to create resources given a YAML file with their configuration.

The complete syntax of the ado create command is as follows:

ado create RESOURCE_TYPE [--file | -f <FILE.yaml>] \
                         [--set <jsonpath=json-value>] \
                         [--with <resource=value>] \
                         [--new-sample-store] \
                         [--use-default-sample-store] [--dry-run]

Where:

• RESOURCE_TYPE is one of the supported resource types for ado create. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuator
  • actuatorconfiguration (ac)
  • context (ctx)
  • operation (op)
  • samplestore (store)
  • discoveryspace (space)

• --file or -f is a path to the resource configuration file in YAML format. It is mandatory in all scenarios, except when running ado create samplestore --new-sample-store.

• --set allows overriding fields in the provided resource configuration. It supports using JSONPath syntax. See the examples section for more information.
• --with enables you to create resources together with other resources they depend on, or to reference existing resource identifiers during creation. For example, you can create a space along with a sample store definition, or create an operation together with an actuator configuration and a space definition. See the Examples section for more details.
• --use-latest allows reusing the latest identifier of a certain resource kind from the current context's metastore. It is only supported for spaces and operations during ado create. Ignored if --with is used.
• --new-sample-store creates a new sample store. Only available when running ado create on space and samplestore. If running ado create space --new-sample-store, the sampleStoreIdentifier contained in the DiscoverySpaceConfiguration will be disregarded. It is ignored if --with or --use-latest are used.
• --use-default-sample-store uses the default sample store. Only available when running ado create space. Alias for --set sampleStoreIdentifier=default. It is ignored if --with, --use-latest, or --new-sample-store are used.
• --dry-run is an optional flag to only validate the resource configuration file provided and not actually creating the resource.

Examples¶

Creating a Discovery Space¶

In this example, we assume that the file ds.yaml exists and contains a valid Discovery Space definition.

ado create -f ds.yaml

Validating a Sample Store definition¶

In this example, we assume that the file sample-store.yml exists, but we make no further assumptions on whether its content is a valid Sample Store definition or not.

ado create -f sample-store.yml --dry-run

Creating a new sample store with no file¶

ado create samplestore --new-sample-store

Creating a space with a new sample store¶

Note that if the space definition ds.yaml contains an sampleStoreIdentifier, it will be ignored, and a new one will be created.

ado create space -f ds.yaml --new-sample-store

Create a space overriding the sample store identifier¶

ado create space -f ds.yaml --set "sampleStoreIdentifier=abcdef"

Another option is to use:

ado create space -f ds.yaml --with store=abcdef

Create a space while providing a sample store definition¶

ado create space -f ds.yaml --with store=store_definition.yaml

Create a space reusing the latest sample store identifier¶

ado create space -f ds.yaml --use-latest samplestore

Create a space renaming a property identifier in the space¶

ado create space -f ds.yaml --set "entitySpace[0].identifier=abcdef"

ado delete¶

The ado CLI provides the delete command to delete resources given their unique identifier.

The complete syntax of the ado delete command is as follows:

ado delete RESOURCE_TYPE RESOURCE_ID [RESOURCE_ID ...] \
           [--force] \
           [--delete-local-db] [--no-delete-local-db]

Where:

• RESOURCE_TYPE is the type of resource you want to delete. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuatorconfiguration (ac)
  • context (ctx)
  • datacontainer (dcr)
  • operation (op)
  • samplestore (store)
  • discoveryspace (space)

• RESOURCE_ID is the unique identifier of the resource to delete. Multiple resource IDs can be provided to delete multiple resources of the same type in a single command.

• --force enables forced deletion of resources in the following cases:

  • When attempting to delete operations while other operations are executing.
  • When attempting to delete sample stores that still contain data.

• When deleting a local context, users can specify the flags --delete-local-db or --no-delete-local-db to explicitly delete or preserve a local DB when deleting its related context. If neither of these flags are specified, the user will be asked whether to delete the DB or not.

Examples¶

Deleting a context¶

ado delete context my-context

Deleting a local context and preserving the local db¶

ado delete context my-local-context --no-delete-local-db

Deleting a single space¶

ado delete space space-abc123-456def

Deleting multiple operations¶

ado delete operation op-id-1 op-id-2 op-id-3

Deleting multiple operations with force flag¶

ado delete operation op-id-1 op-id-2 op-id-3 --force

Deleting multiple discovery spaces¶

ado delete space space-1 space-2 space-3

ado describe¶

ado provides the describe command to retrieve readable information about resources.

The complete syntax of the ado describe command is as follows:

ado describe RESOURCE_TYPE [RESOURCE_ID] [--file | -f <file.yaml>] \
             [--use-latest] [--actuator-id <actuator>]

Where:

• RESOURCE_TYPE is the type of resource you want to describe. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • experiment
  • datacontainer (dcr)
  • discoveryspace (space)

• RESOURCE_ID is the unique identifier of the resource to describe.

• The --file (or -f) flag is currently only available for spaces and allows getting a description of the space, given a space configuration file.
• --use-latest flag is currently only available for spaces and allows describing the most recently created space from the current context.
• --actuator-id (optional) can be used only when the resource type is experiment and is used to indicate what actuator the experiment belongs to.

Examples¶

Describing a Discovery Space¶

ado describe space space-abc123-456def

ado edit¶

ado automatically stores metadata in the backend for some of the resources you can create. The fastest way to update these metadata is to use the ado edit command.

The complete syntax of the ado edit command is as follows:

ado edit RESOURCE_TYPE RESOURCE_ID [-p | --patch <YAML>] \
    [--patch-file <FILE>] [--editor <NAME>]

Where:

• RESOURCE_TYPE is the type of resource you want to edit. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuatorconfiguration (ac)
  • datacontainer (dcr)
  • operation (op)
  • samplestore (store)
  • discoveryspace (space)

• RESOURCE_ID is the unique identifier of the resource to edit.

• -p / --patch is an optional inline YAML/JSON string for non-interactive editing (similar to oc / kubectl patch -p). It is merged into the resource's existing stored metadata using a one-level strategic update: labels are merged as key–value maps; other top-level fields from the patch replace the previous values. You can use a patch string or a file, not both. When using --patch, the --editor flag is ignored.
• --patch-file is an optional path to a YAML/JSON file with the same merge behaviour as --patch. You may not use --patch and --patch-file together. When using --patch-file, the --editor flag is ignored.

• --editor is the name of the editor you want to use for interactive editing of metadata (ignored when --patch or --patch-file is specified). It must be one of the supported ones, which currently are:

  • vim
  • vi
  • nano (default if ADO_EDITOR is not set when using interactive edit)

For interactive mode, you can set the default editor with the ADO_EDITOR environment variable.

Examples¶

Editing an operation's metadata¶

ado edit operation randomwalk-0.5.0-123abc

Editing a space's metadata using a different editor¶

ado edit space space-abc123-456def --editor nano

Editing a space's metadata using a different editor (set by environment variable)¶

ADO_EDITOR=nano ado edit space space-abc123-456def

Merging metadata with an inline patch (non-interactive, oc-style)¶

ado edit space space-abc123-456def -p "labels: { team: front }"

Merging metadata from a file (non-interactive)¶

ado edit space space-abc123-456def --patch-file extra-metadata.yaml

ado get¶

ado allows getting resources in a similar way to kubectl. Users can choose to either get all resources of a given type or specify a resource identifier to restrict results to a single resource.

The complete syntax of the ado get command is as follows:

ado get RESOURCE_TYPE [RESOURCE_ID] [--output | -o <default | yaml | json | config | raw>] \
                                    [--output-file <path>] \
                                    [--use-latest] \
                                    [--exclude-default | --no-exclude-default] \
                                    [--exclude-unset | --no-exclude-unset ] \
                                    [--exclude-none | --no-exclude-none ] \
                                    [--minimize] \
                                    [--query | -q <path=value>] \
                                    [--label | -l <key=value>] \
                                    [--details] [--show-deprecated] \
                                    [--matching-point <point.yaml>] \
                                    [--matching-space <space.yaml] \
                                    [--matching-space-id <space-id>] \
                                    [--from-sample-store <sample-store-id>] \
                                    [--from-space <space-id>] [--from-operation <operation-id>]

Where:

• RESOURCE_TYPE is the type of resource you want to get. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuatorconfiguration (ac)
  • actuator
  • context (ctx)
  • datacontainer (dcr)
  • experiment (exp)
  • operation (op)
  • operator
  • samplestore (store)
  • discoveryspace (space)

• RESOURCE_ID is the optional unique identifier of the resource to get. If not specified, all resources of the given type are returned (unless --use-latest is used).

• --use-latest retrieves the most recently created resource of the specified type. This flag is ignored if a RESOURCE_ID is also provided (the explicit ID takes precedence).

• --output or -o determine the type of output that will be displayed:

  • The table format shows the identifier, the name, and the age of the matching resources.
  • The name format outputs only the resource identifiers, one per line (similar to kubectl get -o name).
  • The yaml format displays the full YAML document of the matching resources.
  • The json format displays the full JSON document of the matching resources.
  • The config format displays the config field of the matching resources.
  • The raw format displays the raw resource as stored in the database, performing no validation.

• --output-file allows writing the output to a specified file instead of stdout. Avoids truncating columns when used with the table format.

• --exclude-default (set by default) allows excluding fields that use default values from the output. Alternatively, the --no-exclude-default flag can be used to show them.
• --exclude-unset (set by default) allows excluding from the output fields whose values have not been set. Alternatively, the --no-exclude-unset flag can be used to show them.
• --exclude-none (set by default) allows excluding fields that have null values from the output. Alternatively, the --no-exclude-none flag can be used to show them.
• --exclude-field allows the user to exclude fields from the output using JSONPath expressions. Documentation for creating these expressions can be found here: https://github.com/h2non/jsonpath-ng?tab=readme-ov-file#jsonpath-syntax. This flag is only supported when using the yaml, json, or config output format.
• --minimize minimizes the output. This might entail applying transformations on the model, changing it from the original. If set, it implies --exclude-default, --exclude-unset, and --exclude-none. This option is ignored when the output type is table or raw.
• The --from-sample-store, --from-space, --from-operation flags are available only for ado get requests and allow specifying what samplestore/space/operation the measurement request belongs to.
• When using the --details flag with the table output format, additional columns with the description and the labels of the matching resources are printed.
• The --show-deprecated flag is available only for ado get experiments and allows displaying experiments that have been deprecated. They are otherwise hidden by default.

Searching and Filtering¶

See searching the metastore for detailed information on the following options, including syntax.

• By using (optionally multiple times) the --query (or -q) flag, users can restrict the resources returned by requiring that a field in the resource contains a given value. This flag can be specified multiple times (even in conjunction with -l to further filter results).
• By using (optionally multiple times) the --label (or -l) flag, users can restrict the resources returned by means of the labels set in the resource's metadata. Labels must be specified in the key=value format. This flag can be specified multiple times (even in conjunction with -q to further filter results).
• The --matching-point option allows the user to search for spaces containing an entity with particular values for some properties along with a particular set of experiments applied to it
• The --matching-space option allows searching for discoveryspaces which match a given configuration YAML.
• The --matching-space-id option works in the same way as --matching-space but allows the user to provide a space id instead of a configuration

Examples¶

Getting all Discovery Spaces¶

ado get spaces

Getting all Discovery Spaces with additional details¶

ado get spaces --details

Getting all Discovery Spaces that include granite-7b-base in the property domain¶

ado get space -q 'config.entitySpace={"propertyDomain":{"values":["granite-7b-base"]}}'

Getting all Discovery Spaces with certain labels¶

ado get spaces -l key1=value1 -l key2=value2

Getting all discovery spaces matching a point¶

Assuming you have the following file saved as point.yaml:

entity: # A key-value dictionary of constitutive property identifiers and values
  batch_size: 8
  number_gpus: 4
experiments: # A list of experiments
  - finetune-lora-fsdp-r-4-a-16-tm-default-v2.0.0

You can run:

ado get spaces --matching-point point.yaml

Getting all DiscoverySpaces and hiding fields¶

This example shows how to hide the propertyDomain.variableType and propertyDomain.domainRange fields from the Discovery Space's entity space:

ado get space space-df8077-7535f9 -o yaml \
  --exclude-field "config.entitySpace[*].propertyDomain.variableType" \
  --exclude-field "config.entitySpace[*].propertyDomain.domainRange"

Getting an actuator configuration and hiding the status for the "created" event¶

ado get actuatorconfiguration actuatorconfiguration-myactuator-123456 -o yaml \
  --exclude-field 'status[?(@.event="created")]'

Getting a single Operation¶

ado get operation randomwalk-0.5.0-123abc

Getting the YAML of a single Operation¶

ado get operation randomwalk-0.5.0-123abc -o yaml

Getting only the identifiers of all Operations¶

ado get operations -o name

Getting the latest Discovery Space as YAML¶

ado get space --use-latest -o yaml

Getting the latest Operation as YAML¶

ado get operation --use-latest -o yaml

Displaying all current experiments¶

ado get experiments --details

Getting the yaml of a MeasurementRequest from an operation¶

ado get request measurement-request-123 --from-operation randomwalk-0.5.0-123abc -o yaml

Saving a Discovery Space configuration to a file¶

ado get space my-space-id -o yaml --output-file space.yaml

Saving all operations as JSON¶

ado get operations -o json --output-file operations.json

Saving resource identifiers to a file¶

ado get spaces -o name --output-file space-ids.txt

Saving table output to a file¶

ado get spaces --output-file spaces-table.txt

ado show¶

When interacting with resources, we might be interested in seeing some of their details, entities measured, or related resources. ado show provides this with the four following subcommands.

ado show details¶

show details supports displaying aggregate details about resources and related resources.

The complete syntax of the ado show details command is as follows:

ado show details RESOURCE_TYPE [RESOURCE_ID] [--use-latest]

Where:

• RESOURCE_TYPE is one of the supported resource types. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • discoveryspace (space)
  • operation (op)

• RESOURCE_ID is the unique identifier of the resource you want to see details for.

• --use-latest will use the identifier of the latest (i.e. most recent) resource of RESOURCE_TYPE from the current context. It is ignored if a RESOURCE_ID is provided.

Examples¶

Show details for a space¶

ado show details space space-abc123-456def

Show details for the latest space¶

ado show details space --use-latest

ado show entities¶

show entities supports displaying entities that belong to a space or an operation.

The complete syntax of the ado show entities command is as follows:

ado show entities RESOURCE_TYPE [RESOURCE_ID] [--use-latest] [--file | -f <file.yaml>]\
                  [--property-format {observed | target}] \
                  [--output | -o {table | csv | json}] \
                  [--output-file <path>] \
                  [--property <property-name>] \
                  [--include {sampled | matching | missing | unsampled}] \
                  [--aggregate {mean | median | variance | std | min | max}]

Where:

• RESOURCE_TYPE is one of the supported resource types. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • discoveryspace (space)
  • operation (op)

• RESOURCE_ID is the unique identifier of the resource you want to see entities for.

• --use-latest will use the identifier of the latest (i.e. most recent) resource of RESOURCE_TYPE from the current context. It is ignored if a RESOURCE_ID is provided.
• The --file (or -f) flag is currently only available for spaces and enables showing entities that match the space defined in the configuration file. NOTE: using this flag forces --include matching.

• --property-format defines the naming format used for measured properties in the output, one of:

  • observed: properties are named $experimentid.$property_id. There will be one row per entity.
  • target: properties are named $property_id. There will be one row per (entity, experiment) pair.

• --output (or -o) is the format in which to display the entity data. One of:

  • table (print to stdout)
  • csv (write CSV to stdout, or to file if --output-file is specified)
  • json (write JSON to stdout, or to file if --output-file is specified)

• --output-file specifies a file path to write the output to (except for table format which always prints to stdout).

• --property (can be specified multiple times) is used to filter what measured properties need to be output.

• --include (exclusive to spaces) determines what type of entities to include. One of:

  • sampled: Entities that have been measured by explore operations on the discoveryspace
  • unsampled: Entities that have not been measured by an explore operation on the discoveryspace
  • matching: Entities in the samplestore the discoveryspace uses, that match the discoveryspace's description
  • missing: Entities in the discoveryspace that are not in the samplestore the discoveryspace uses

• --aggregate allows applying an aggregation to the result values in case multiple are present. One of:

  • mean
  • median
  • variance
  • std
  • min
  • max

Examples¶

Show matching entities in a Space with target format and output them as CSV¶

Recommended approach using --output-file (ensures columns aren't truncated and handles file write errors):

 ado show entities space space-abc123-456def --include matching \
                                             --property-format target \
                                             -o csv --output-file entities.csv

Or to write CSV to stdout for piping:

 ado show entities space space-abc123-456def --include matching \
                                             --property-format target \
                                             -o csv > entities.csv

Show a subset of the properties of entities that are part of an operation and output them as JSON¶

ado show entities operation randomwalk-0.5.0-123abc -o json \
                                                    --property my-property-1 \
                                                    --property my-property-2

Save table output of entities to a file¶

ado show entities space space-abc123-456def --output-file entities-table.txt

ado show requests¶

show requests supports displaying the MeasurementRequests that were part of an operation.

The complete syntax of the ado show requests command is as follows:

ado show requests operation [RESOURCE_ID] [--use-latest] \
                            [--output | -o <table | csv | json>] \
                            [--output-file <path>] \
                            [--hide <field>]

• --use-latest will use the identifier of the latest (i.e. most recent) operation from the current context. It is ignored if a RESOURCE_ID is provided.
• --output (or -o) determines the output format. Output is written to stdout by default, or to a file if --output-file is specified.
• --output-file specifies a file path to write the output to. If not provided, output is written to stdout.
• --hide can be specified multiple times and allows hiding fields from the output.

Examples¶

Show measurement requests for an operation and save them as csv¶

ado show requests operation randomwalk-0.5.0-123abc -o csv > requests.csv

Or to write to a file directly (recommended - ensures columns aren't truncated and handles file write errors):

ado show requests operation randomwalk-0.5.0-123abc -o csv --output-file requests.csv

Show measurement requests for an operation and hide certain fields¶

ado show requests operation randomwalk-0.5.0-123abc --hide type --hide "experiment id"

Save table output of requests to a file¶

ado show requests operation randomwalk-0.5.0-123abc --output-file requests-table.txt

ado show results¶

show results supports displaying the MeasurementResults that were part of an operation.

The complete syntax of the ado show results command is as follows:

ado show results operation [RESOURCE_ID] [--use-latest] \
                           [--output | -o <table | csv | json>] \
                           [--output-file <path>] \
                           [--hide <field>]

• --use-latest will use the identifier of the latest (i.e. most recent) operation from the current context. It is ignored if a RESOURCE_ID is provided.
• --output (or -o) determines the output format. Output is written to stdout by default, or to a file if --output-file is specified.
• --output-file specifies a file path to write the output to. If not provided, output is written to stdout.
• --hide can be specified multiple times and allows hiding fields from the output.

Examples¶

Show measurement results for an operation¶

ado show results operation randomwalk-0.5.0-123abc -o csv > results.csv

Or to write to a file directly (recommended - ensures columns aren't truncated and handles file write errors):

ado show results operation randomwalk-0.5.0-123abc -o csv --output-file results.csv

Show measurement results for an operation and hide certain fields¶

ado show results operation randomwalk-0.5.0-123abc --hide uid

Save table output of results to a file¶

ado show results operation randomwalk-0.5.0-123abc --output-file results-table.txt

ado show related¶

show related supports displaying resources that are related to the one whose id is provided (e.g., operations run on a space).

The complete syntax of the ado show related command is as follows:

ado show related RESOURCE_TYPE [RESOURCE_ID] [--use-latest]

• RESOURCE_TYPE is one of the supported resource types. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuatorconfiguration (ac)
  • datacontainer (dcr)
  • discoveryspace (space)
  • operation (op)
  • samplestore (store)

• RESOURCE_ID is the unique identifier of the resource you want to see related resources for.

• --use-latest will use the identifier of the latest (i.e. most recent) resource of RESOURCE_TYPE from the current context. It is ignored if a RESOURCE_ID is provided.

Examples¶

Show resources related to a discovery space¶

 ado show related space space-abc123-456def

ado show summary¶

show summary supports generating overviews about discovery spaces. The content can be provided in the following formats:

• Markdown table (for high level overviews).
• Markdown text (for an easy to read and more in-depth format)
• CSV

The complete syntax of the ado show summary command is as follows:

ado show summary RESOURCE_TYPE [RESOURCE_IDS...] [--use-latest] \
                 [--query | -q <path=candidate>] \
                 [--label | -l <LABEL> ] \
                 [--with-property | -p <PROPERTY> ] \
                 [--output | -o <md | table | csv>] \
                 [--output-file <path>]

Where:

• RESOURCE_TYPE is always discoveryspace (space). See Resource Type Shorthands for the shorthand alias.
• RESOURCE_IDS are one or more space-separated space identifiers.
• --use-latest will add the identifier of the latest (i.e. most recent) space from the current context to the RESOURCE_IDS.
• By using (optionally multiple times) the --query (or -q) flag, users can restrict the resources returned by requiring that a field in the resource is equal to a provided value or that the content of a JSON document appear in the resource. This flag can be specified multiple times (even in conjunction with -l to further filter results).
• By using (optionally multiple times) the --label (or -l) flag, users can restrict the resources returned by means of the labels set in the resource's metadata. Labels must be specified in the key=value format. This flag can be specified multiple times (even in conjunction with -q to further filter results).
• --with-property | -p displays values for a subset of the constitutive properties. Cannot be used when the output format is md-report.

• --output (or -o) allows choosing the output format in which the information should be displayed. Can be one of either:

  • table (default) - for a formatted table output.
  • md-table - for a table in Markdown format.
  • md-report - for a report in Markdown format.
  • csv - for CSV format.

• --output-file specifies a file path to write the output to. If not provided, output is written to stdout.

Examples¶

Get the summary of a space as a rich table¶

ado show summary space space-abc123-456def

Get the summary of a space as a rich table and include the constitutive property MY_PROPERTY¶

ado show summary space space-abc123-456def -p MY_PROPERTY

Get the summary of multiple spaces as a rich table via identifiers¶

ado show summary space space-abc123-456def space-ghi789-123jkl

Get the summary of multiple spaces as a rich table via key-value labels¶

ado show summary space -l issue=123

Get the summary of a space as a Markdown report¶

ado show summary space space-abc123-456def -o md-report

Get the summary of a multiple spaces as a CSV file via key-value labels¶

ado show summary space -l issue=123 -o csv > summary.csv

Or to write to a file directly (recommended - ensures columns aren't truncated and handles file write errors):

ado show summary space -l issue=123 -o csv --output-file summary.csv

Save table summary output to a file¶

ado show summary space my-space-id --output-file summary-table.txt

Save markdown summary output to a file¶

ado show summary space my-space-id -o md --output-file summary.md

Get the summary of spaces that include granite-7b-base in the property domain¶

ado show summary space -q 'config.entitySpace={"propertyDomain":{"values":["granite-7b-base"]}}'

ado template¶

To assist in creating a resource configuration file, we typically start from a reference file. The ado template command allows you to create template files that you can edit to streamline the process.

The complete syntax of the ado template command is as follows:

ado template RESOURCE_TYPE [--output-file <PATH>] \
                           [--include-schema] \
                           [--operator-name <NAME>] \
                           [--operator-type <TYPE>] \
                           [--actuator-identifier <NAME>] \
                           [--from-experiment | -e <experiment_id | actuator_id:experiment_id>] \
                           [--local-context] \
                           [--no-parameters-only-schema]

Where:

• RESOURCE_TYPE is one of the supported resource types. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuator
  • actuatorconfiguration (ac)
  • context (ctx)
  • discoveryspace (space)
  • operation (op)
  • samplestore (store)

• --output-file can be used to specify a file path where the template will be saved. If not specified, the template will be written to stdout.

• --include-schema, if set, will also produce the JSON Schema of the resource the template was generated for.
• --operator-name (exclusive for operations) allows generating an operation template with a specific operator. If unset, a generic operation will instead be output.

• --operator-type (exclusive for operations) is the type of operator to generate a template for. Must be one of the supported operator types:

  • characterize
  • search
  • compare
  • modify
  • study
  • fuse
  • learn

• --actuator-configuration (exclusive for actuatorconfigurations) is the identifier of the actuator to output. If unset, a generic actuator configuration will be output.

• --from-experiment (exclusive for spaces) can either be the identifier of the experiment you want to have in your space or, in case multiple actuators implementing the same experiment identifier, the identifier of the actuator and that of the experiment in the form actuator_id:experiment_id. If unset, a generic space will be output.
• --local-context (exclusive for contexts) creates a template using SQLite instead of MySQL.
• --no-parameters-only-schema (exclusive for operations) when used with --include-schema, outputs a generic operation schema. By default (when not specifying this flag), the schema will be operator-specific.

Examples¶

Creating a template for a context¶

ado template context

Creating a template for a space that uses a specific experiment¶

ado template space --from-experiment finetune-gptq-lora-dp-r-4-a-16-tm-default-v1.1.0

Creating a template for a space that uses a specific experiment from a specific actuator¶

ado template space --from-experiment SFTTrainer:finetune-gptq-lora-dp-r-4-a-16-tm-default-v1.1.0

Creating a template for a Discovery Space with the schema¶

ado template space --include-schema

Creating an operation template for the Rifferla operator¶

ado template operation --operator-name rifferla

ado upgrade¶

Sometimes the models that are used in ado undergo changes that require updating stored representations of them in the metastore. When required, you can run this command to update all resources of a given kind in the database.

ado upgrade RESOURCE_TYPE [--apply-legacy-migrator <VALIDATOR_ID>] \
                          [--list-legacy-migrators]

Where:

• RESOURCE_TYPE is one of the supported resource types. See Resource Type Shorthands for shorthand aliases. Currently supported:

  • actuatorconfiguration (ac)
  • datacontainer (dcr)
  • discoveryspace (space)
  • operation (op)
  • samplestore (store)

• --apply-legacy-migrator applies a specific legacy migrator by identifier during the upgrade process. This option can be specified multiple times to apply multiple validators. Legacy validators handle deprecated field migrations and schema transformations.

• --list-legacy-migrators lists all available legacy migrators for the specified resource type, showing their identifiers, descriptions, and deprecated field paths.

Examples¶

Upgrade all operation resources¶

ado upgrade operations

List available legacy migrators for sample stores¶

ado upgrade samplestores --list-legacy-migrators

Apply a legacy migrator during upgrade¶

ado upgrade samplestores --apply-legacy-migrator samplestore_kind_entitysource_to_samplestore

ado version¶

When unsure about what ado version you are running, you can get this information with:

ado version

What's next¶