ibm/using-ado-cli

Using the ado CLI

Command Verification

Always run --help before writing any ado command in documentation, comments, or code. Do not rely on memory or analogy to other CLIs.

# Verify top-level command
uv run ado [COMMAND] --help

# Verify subcommands
uv run ado [COMMAND] [SUBCOMMAND] --help
uv run ado [COMMAND] [SUBCOMMAND1] [SUBCOMMAND2] --help

Check:

• Command and subcommand names are correct
• Options are spelled correctly (e.g., --use-latest not --latest)
• Required arguments are included
• Optional flags match actual CLI behavior

Commands That do not exist

These plausible-sounding commands do not exist in ado. Do not write them:

| ❌ Does not exist | ✅ Correct equivalent | | ----------------- | --------------------------------------- | | ado run | ado create operation -f op.yaml | | ado start | ado create operation -f op.yaml | | ado execute | ado create operation -f op.yaml | | ado launch | ado create operation -f op.yaml | | ado list | ado get spaces / ado get operations | | ado status | ado show details space SPACE_ID |

Key principle: ado create operation both defines and starts the operation in a single command. There is no separate "run" step.

Point Testing with run_experiment

run_experiment is a separate CLI entry point (not an ado subcommand) for running a single entity through an experiment locally, without creating a space or operation. It is the correct tool for functional validation of custom experiments.

uv run run_experiment PATH_TO_POINT_YAML

A point YAML has the form:

entity:
  param_a: value_a
  param_b: value_b

experiments:
  - actuatorIdentifier: custom_experiments
    experimentIdentifier: my_experiment

It prints the result as a pandas Series and exits. No metastore or Ray cluster needed beyond a local Ray instance (started automatically).

Core Commands

ado get

Lists resources of a given type and gets resource YAML

#List all spaces
uv run ado get spaces

#Get the YAML for a space
uv run ado get space SPACE_ID -o yaml

ado create

Creates resources and starts operations.

# Create a discoveryspace
uv run ado create space -f space.yaml

# Create and start an operation
uv run ado create operation -f operation.yaml

Key point: ado create both defines AND initiates resources.

ado show

Retrieves details and data from resources.

# Get a summary of what has been sampled from the space
uv run ado show details space SPACE_ID

# Get latest results
uv run ado show results operation OPERATION_ID

# Get entities and measurements
uv run ado show entities space SPACE_ID
uv run ado show entities operation OPERATION_ID

ado describe

Outputs a human readable description

# Output a description of a space
# Dimensions, values, experiments
uv run ado describe space SPACE_ID

#Output a description of an experiment
# (input params, output params etc.)
uv run ado describe experiment EXPERIMENT_ID

Debugging

If commands are not given expected output use the -l flag to activate different log levels

e.g. for debug level logs

uv run ado -lDEBUG [COMMAND]

Terminology

Entities

Entities represent points in the discovery space with:

• Constitutive properties (inputs/priors) - what defines the point
• Measured properties (outputs/posteriors) - what was observed

Understanding show Commands

<!-- markdownlint-disable line-length -->

| Command | What It Shows | | ------------------------- | ------------------------------------------------------------------------ | | show entities operation | Entities (inputs) and their measurements (outputs) from this operation | | show entities space | All entities and measurements collected in this space | | show results operation | Results metadata from this operation (not the full measurement data) |

<!-- markdownlint-enable line-length -->

Example distinction:

# Get the actual measurement data for entities
uv run ado show entities operation op-123

# Get metadata about the operation's results
uv run ado show results operation op-123

Command-Line Shortcuts

--use-latest

Queries the current context's metastore to find the most recently created resource of the given type.

Without --use-latest:

# Step 1: Create space, note the ID from output
uv run ado create space -f space.yaml
# Output: Created space: space-abc123

# Step 2: Edit operation.yaml to add space-abc123
# Step 3: Create operation
uv run ado create operation -f operation.yaml

With --use-latest:

# Step 1: Create space
uv run ado create space -f space.yaml

# Step 2: Create operation using that space automatically
uv run ado create operation -f operation.yaml --use-latest

The --use-latest flag automatically fills in the latest space ID.

--set

Overrides individual fields in a resource YAML at creation time without editing the file. Takes path=JSON_document pairs; can be used multiple times.

# Override the sample store used by a space
uv run ado create space -f space.yaml --set sampleStoreIdentifier=my_store

# Override a nested operation parameter
uv run ado create operation -f operation.yaml --set parameters.budget=100

--with

Creates a resource from YAML inline and uses it in the current command.

Without --with:

# Create actuator configuration separately
uv run ado create actuatorconfiguration -f actuator.yaml

# Edit operation.yaml to reference the actuator config ID
uv run ado create operation -f operation.yaml

With --with:

# Create both in one command
uv run ado create operation -f operation.yaml \
  --with space=space.yaml \
  --with actuatorconfiguration=actuator.yaml

This creates the space and actuator configuration, then automatically references them when creating the operation.

Documentation Best Practices

When writing documentation with ado commands:

1. Always verify the command syntax with --help
2. Use realistic IDs in examples (e.g., space-abc123 not SPACE_ID in code blocks where actual output is shown)
3. Show expected output when helpful for clarity
4. Prefer shortcuts (--use-latest, --with) in tutorials to reduce friction
5. Explain terminology the first time: "entities (the inputs and their measurements)"

Example Documentation Pattern

## Creating and Running an Operation

First, create your discovery space:

\`\`\`bash ado create space -f space.yaml \`\`\`

Then create and start the operation, automatically using the space you just
created:

\`\`\`bash ado create operation -f operation.yaml --use-latest space \`\`\`

View the entities (inputs) and their measurements (outputs):

\`\`\`bash ado show entities operation --use-latest \`\`\`

Common Patterns

Query workflow

# List all operations
uv run ado get operations

# Get details on a specific operation
uv run ado get operation -o yaml op-123

# Get the entities and measurements
uv run ado show entities operation op-123

Create with dependencies

# Create everything in one command
uv run ado create operation -f operation.yaml \
  --with space=space.yaml \
  --with actuatorconfiguration=config.yaml

Iterative development

# Create space
uv run ado create space -f space.yaml

# Validate with dry-run
uv run ado create operation -f operation.yaml --dry-run --use-latest

# Actually create it
uv run ado create operation -f operation.yaml --use-latest

Related Resources

• For creating and structuring resource YAML files, see resource-yaml-creation
• For creating discoveryspace and operation YAML files, see formulate-discovery-problem
• For general development guidelines, see AGENTS.md