Skip to content

SKILL.md

Latest commit

 

History

History
333 lines (230 loc) · 8.76 KB

SKILL.md

File metadata and controls

333 lines (230 loc) · 8.76 KB
name using-ado-cli
description Guidelines for using ado CLI commands and documenting them correctly. Use when writing documentation that includes ado commands, verifying CLI syntax, or explaining ado CLI usage patterns to users.

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

Output format vs output file

For ado get and ado show subcommands:

  • -o / --output selects the output format (for example yaml, table, csv, or json; allowed values depend on the command — use --help).
  • --output-file PATH writes that formatted output to PATH instead of stdout. Prefer this over shell redirection for large output so encoding and table rendering stay consistent.

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 (console)
uv run ado get space SPACE_ID -o yaml

# Or write the same YAML to a file
uv run ado get space SPACE_ID -o yaml --output-file space.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

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)

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 (YAML to a file)
uv run ado get operation op-123 -o yaml --output-file op-123.yaml

# 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