epic(cli): refactor ado CLI

[AlessandroPomponio]

[AlessandroPomponio]

ado CLI Command Structure Diagram

This diagram visualizes the complete structure of the ado CLI, showing all
commands, subcommands, and their primary options.

Display diagram

graph LR
    ADO[ado CLI]

    ADO --> CONTEXT[context]
    ADO --> CONTEXTS[contexts]
    ADO --> CREATE[create]
    ADO --> DELETE[delete]
    ADO --> DESCRIBE[describe]
    ADO --> EDIT[edit]
    ADO --> GET[get]
    ADO --> SHOW[show]
    ADO --> TEMPLATE[template]
    ADO --> UPGRADE[upgrade]
    ADO --> VERSION[version]

    %% CONTEXT
    CONTEXT --> CONTEXT_ARG["[context_name]<br/>View or set active context"]

    %% CONTEXTS
    CONTEXTS --> CONTEXTS_OPT["--output/-o<br/>List available contexts"]

    %% CREATE
    CREATE --> CREATE_AC[actuatorconfiguration]
    CREATE --> CREATE_CTX[context]
    CREATE --> CREATE_SPACE[discoveryspace/space]
    CREATE --> CREATE_SS[samplestore]
    CREATE --> CREATE_OP[operation]

    CREATE_AC --> CREATE_AC_OPT["--file/-f<br/>--set<br/>--dry-run"]
    CREATE_CTX --> CREATE_CTX_OPT["--file/-f<br/>--dry-run"]
    CREATE_SPACE --> CREATE_SPACE_OPT["--file/-f<br/>--set<br/>--with<br/>--use-latest<br/>--new-sample-store<br/>--use-default-sample-store<br/>--dry-run"]
    CREATE_SS --> CREATE_SS_OPT["--file/-f<br/>--new-sample-store<br/>--dry-run"]
    CREATE_OP --> CREATE_OP_OPT["--file/-f<br/>--set<br/>--with<br/>--use-latest<br/>--dry-run"]

    %% DELETE
    DELETE --> DELETE_AC[actuatorconfiguration]
    DELETE --> DELETE_CTX[context]
    DELETE --> DELETE_DC[datacontainer]
    DELETE --> DELETE_SPACE[discoveryspace/space]
    DELETE --> DELETE_SS[samplestore]
    DELETE --> DELETE_OP[operation]

    DELETE_AC --> DELETE_AC_OPT["resource_id(s)<br/>--force"]
    DELETE_CTX --> DELETE_CTX_OPT["resource_id(s)<br/>--delete-local-db"]
    DELETE_DC --> DELETE_DC_OPT["resource_id(s)<br/>--force"]
    DELETE_SPACE --> DELETE_SPACE_OPT["resource_id(s)<br/>--force"]
    DELETE_SS --> DELETE_SS_OPT["resource_id(s)<br/>--force"]
    DELETE_OP --> DELETE_OP_OPT["resource_id(s)<br/>--force"]

    %% DESCRIBE
    DESCRIBE --> DESCRIBE_DC[datacontainer]
    DESCRIBE --> DESCRIBE_SPACE[discoveryspace/space]
    DESCRIBE --> DESCRIBE_EXP[experiment]

    DESCRIBE_DC --> DESCRIBE_DC_OPT["resource_id"]
    DESCRIBE_SPACE --> DESCRIBE_SPACE_OPT["[resource_id]<br/>--file/-f<br/>--use-latest"]
    DESCRIBE_EXP --> DESCRIBE_EXP_OPT["resource_id<br/>--actuator-id"]

    %% EDIT
    EDIT --> EDIT_AC[actuatorconfiguration]
    EDIT --> EDIT_DC[datacontainer]
    EDIT --> EDIT_SPACE[discoveryspace/space]
    EDIT --> EDIT_SS[samplestore]
    EDIT --> EDIT_OP[operation]

    EDIT_AC --> EDIT_AC_OPT["resource_id<br/>--editor<br/>--patch/-p<br/>--patch-file"]
    EDIT_DC --> EDIT_DC_OPT["resource_id<br/>--editor<br/>--patch/-p<br/>--patch-file"]
    EDIT_SPACE --> EDIT_SPACE_OPT["resource_id<br/>--editor<br/>--patch/-p<br/>--patch-file"]
    EDIT_SS --> EDIT_SS_OPT["resource_id<br/>--editor<br/>--patch/-p<br/>--patch-file"]
    EDIT_OP --> EDIT_OP_OPT["resource_id<br/>--editor<br/>--patch/-p<br/>--patch-file"]

    %% GET
    GET --> GET_ACT[actuator]
    GET --> GET_AC[actuatorconfiguration]
    GET --> GET_CTX[context]
    GET --> GET_DC[datacontainer]
    GET --> GET_SPACE[discoveryspace/space]
    GET --> GET_EXP[experiment]
    GET --> GET_SS[samplestore]
    GET --> GET_MR[measurementrequest]
    GET --> GET_OP[operation]
    GET --> GET_OPR[operator]

    GET_ACT --> GET_ACT_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>--show-deprecated<br/>Output config options"]
    GET_AC --> GET_AC_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>Output config options"]
    GET_CTX --> GET_CTX_OPT["[resource_id]<br/>--output/-o<br/>Output config options"]
    GET_DC --> GET_DC_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>Output config options"]
    GET_SPACE --> GET_SPACE_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>--matching-point<br/>--matching-space<br/>--matching-space-id<br/>Output config options"]
    GET_EXP --> GET_EXP_OPT["[resource_id]<br/>--details<br/>--output/-o<br/>Output config options"]
    GET_SS --> GET_SS_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>Output config options"]
    GET_MR --> GET_MR_OPT["[resource_id]<br/>--from-sample-store<br/>--from-space<br/>--from-operation<br/>--output/-o<br/>Output config options"]
    GET_OP --> GET_OP_OPT["[resource_id]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--details<br/>--output/-o<br/>Output config options"]
    GET_OPR --> GET_OPR_OPT["[resource_id]<br/>--details<br/>--output/-o<br/>Output config options"]

    %% SHOW
    SHOW --> SHOW_DETAILS[details]
    SHOW --> SHOW_ENTITIES[entities]
    SHOW --> SHOW_RELATED[related]
    SHOW --> SHOW_REQUESTS[requests]
    SHOW --> SHOW_RESULTS[results]
    SHOW --> SHOW_SUMMARY[summary]

    SHOW_DETAILS --> SHOW_DETAILS_SPACE[discoveryspace/space]
    SHOW_DETAILS --> SHOW_DETAILS_OP[operation]
    SHOW_DETAILS_SPACE --> SHOW_DETAILS_SPACE_OPT["[resource_id]<br/>--use-latest"]
    SHOW_DETAILS_OP --> SHOW_DETAILS_OP_OPT["[resource_id]<br/>--use-latest"]

    SHOW_ENTITIES --> SHOW_ENTITIES_SPACE[discoveryspace/space]
    SHOW_ENTITIES --> SHOW_ENTITIES_OP[operation]
    SHOW_ENTITIES_SPACE --> SHOW_ENTITIES_SPACE_OPT["[resource_id]<br/>--use-latest<br/>--file/-f<br/>--include<br/>--property-format<br/>--output/-o<br/>--output-file<br/>--property<br/>--aggregate<br/>--no-trunc"]
    SHOW_ENTITIES_OP --> SHOW_ENTITIES_OP_OPT["[resource_id]<br/>--use-latest<br/>--property-format<br/>--output/-o<br/>--output-file<br/>--property<br/>--no-trunc"]

    SHOW_RELATED --> SHOW_RELATED_AC[actuatorconfiguration]
    SHOW_RELATED --> SHOW_RELATED_DC[datacontainer]
    SHOW_RELATED --> SHOW_RELATED_SPACE[discoveryspace/space]
    SHOW_RELATED --> SHOW_RELATED_SS[samplestore]
    SHOW_RELATED --> SHOW_RELATED_OP[operation]
    SHOW_RELATED_AC --> SHOW_RELATED_AC_OPT["[resource_id]<br/>--use-latest"]
    SHOW_RELATED_DC --> SHOW_RELATED_DC_OPT["[resource_id]<br/>--use-latest"]
    SHOW_RELATED_SPACE --> SHOW_RELATED_SPACE_OPT["[resource_id]<br/>--use-latest"]
    SHOW_RELATED_SS --> SHOW_RELATED_SS_OPT["[resource_id]<br/>--use-latest"]
    SHOW_RELATED_OP --> SHOW_RELATED_OP_OPT["[resource_id]<br/>--use-latest"]

    SHOW_REQUESTS --> SHOW_REQUESTS_OP[operation]
    SHOW_REQUESTS_OP --> SHOW_REQUESTS_OP_OPT["[resource_id]<br/>--use-latest<br/>--output/-o<br/>--output-file<br/>--hide<br/>--no-trunc"]

    SHOW_RESULTS --> SHOW_RESULTS_OP[operation]
    SHOW_RESULTS_OP --> SHOW_RESULTS_OP_OPT["[resource_id]<br/>--use-latest<br/>--output/-o<br/>--output-file<br/>--hide<br/>--no-trunc"]

    SHOW_SUMMARY --> SHOW_SUMMARY_SPACE[discoveryspace/space]
    SHOW_SUMMARY_SPACE --> SHOW_SUMMARY_SPACE_OPT["[resource_id(s)]<br/>--use-latest<br/>--query/-q<br/>--label/-l<br/>--with-property/-p<br/>--hide<br/>--output/-o<br/>--output-file<br/>--render"]

    %% TEMPLATE
    TEMPLATE --> TEMPLATE_ACT[actuator]
    TEMPLATE --> TEMPLATE_AC[actuatorconfiguration]
    TEMPLATE --> TEMPLATE_CTX[context]
    TEMPLATE --> TEMPLATE_SPACE[discoveryspace/space]
    TEMPLATE --> TEMPLATE_SS[samplestore]
    TEMPLATE --> TEMPLATE_OP[operation]

    TEMPLATE_ACT --> TEMPLATE_ACT_OPT["--output-file<br/>--include-schema"]
    TEMPLATE_AC --> TEMPLATE_AC_OPT["--actuator-identifier<br/>--output-file<br/>--include-schema"]
    TEMPLATE_CTX --> TEMPLATE_CTX_OPT["--local-context<br/>--output-file<br/>--include-schema"]
    TEMPLATE_SPACE --> TEMPLATE_SPACE_OPT["--from-experiment/-e<br/>--output-file<br/>--include-schema"]
    TEMPLATE_SS --> TEMPLATE_SS_OPT["--output-file<br/>--include-schema"]
    TEMPLATE_OP --> TEMPLATE_OP_OPT["--operator-name<br/>--operator-type<br/>--parameters-only-schema<br/>--output-file<br/>--include-schema"]

    %% UPGRADE
    UPGRADE --> UPGRADE_AC[actuatorconfiguration]
    UPGRADE --> UPGRADE_DC[datacontainer]
    UPGRADE --> UPGRADE_SPACE[discoveryspace/space]
    UPGRADE --> UPGRADE_SS[samplestore]
    UPGRADE --> UPGRADE_OP[operation]

    UPGRADE_AC --> UPGRADE_AC_OPT["--apply-legacy-migrator<br/>--list-legacy-migrators"]
    UPGRADE_DC --> UPGRADE_DC_OPT["--apply-legacy-migrator<br/>--list-legacy-migrators"]
    UPGRADE_SPACE --> UPGRADE_SPACE_OPT["--apply-legacy-migrator<br/>--list-legacy-migrators"]
    UPGRADE_SS --> UPGRADE_SS_OPT["--apply-legacy-migrator<br/>--list-legacy-migrators"]
    UPGRADE_OP --> UPGRADE_OP_OPT["--apply-legacy-migrator<br/>--list-legacy-migrators"]

    %% VERSION
    VERSION --> VERSION_OPT["Display ado version"]

    %% Styling
    classDef commandClass fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef subcommandClass fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    classDef optionClass fill:#f3e5f5,stroke:#4a148c,stroke-width:1px

    class ADO commandClass
    class CONTEXT,CONTEXTS,CREATE,DELETE,DESCRIBE,EDIT,GET,SHOW,TEMPLATE,UPGRADE,VERSION commandClass
    class CREATE_AC,CREATE_CTX,CREATE_SPACE,CREATE_SS,CREATE_OP subcommandClass
    class DELETE_AC,DELETE_CTX,DELETE_DC,DELETE_SPACE,DELETE_SS,DELETE_OP subcommandClass
    class DESCRIBE_DC,DESCRIBE_SPACE,DESCRIBE_EXP subcommandClass
    class EDIT_AC,EDIT_DC,EDIT_SPACE,EDIT_SS,EDIT_OP subcommandClass
    class GET_ACT,GET_AC,GET_CTX,GET_DC,GET_SPACE,GET_EXP,GET_SS,GET_MR,GET_OP,GET_OPR subcommandClass
    class SHOW_DETAILS,SHOW_ENTITIES,SHOW_RELATED,SHOW_REQUESTS,SHOW_RESULTS,SHOW_SUMMARY subcommandClass
    class TEMPLATE_ACT,TEMPLATE_AC,TEMPLATE_CTX,TEMPLATE_SPACE,TEMPLATE_SS,TEMPLATE_OP subcommandClass
    class UPGRADE_AC,UPGRADE_DC,UPGRADE_SPACE,UPGRADE_SS,UPGRADE_OP subcommandClass

Loading

Simplified Command Tree

ado
├── context [context_name]
├── contexts [--output/-o]
├── create <resource_type>
│   ├── actuatorconfiguration
│   ├── context
│   ├── discoveryspace (space)
│   ├── samplestore
│   └── operation
├── delete <resource_type> <resource_id(s)>
│   ├── actuatorconfiguration
│   ├── context
│   ├── datacontainer
│   ├── discoveryspace (space)
│   ├── samplestore
│   └── operation
├── describe <resource_type> [resource_id]
│   ├── datacontainer
│   ├── discoveryspace (space)
│   └── experiment
├── edit <resource_type> <resource_id>
│   ├── actuatorconfiguration
│   ├── datacontainer
│   ├── discoveryspace (space)
│   ├── samplestore
│   └── operation
├── get <resource_type> [resource_id]
│   ├── actuator
│   ├── actuatorconfiguration
│   ├── context
│   ├── datacontainer
│   ├── discoveryspace (space)
│   ├── experiment
│   ├── samplestore
│   ├── measurementrequest
│   ├── operation
│   └── operator
├── show <subcommand>
│   ├── details <resource_type> [resource_id]
│   │   ├── discoveryspace (space)
│   │   └── operation
│   ├── entities <resource_type> [resource_id]
│   │   ├── discoveryspace (space)
│   │   └── operation
│   ├── related <resource_type> [resource_id]
│   │   ├── actuatorconfiguration
│   │   ├── datacontainer
│   │   ├── discoveryspace (space)
│   │   ├── samplestore
│   │   └── operation
│   ├── requests <resource_type> [resource_id]
│   │   └── operation
│   ├── results <resource_type> [resource_id]
│   │   └── operation
│   └── summary <resource_type> [resource_id(s)]
│       └── discoveryspace (space)
├── template <resource_type>
│   ├── actuator
│   ├── actuatorconfiguration
│   ├── context
│   ├── discoveryspace (space)
│   ├── samplestore
│   └── operation
├── upgrade <resource_type>
│   ├── actuatorconfiguration
│   ├── datacontainer
│   ├── discoveryspace (space)
│   ├── samplestore
│   └── operation
└── version

Command Summary Table

Command	Purpose	Resource Types Supported
context	View/set active context	N/A
contexts	List available contexts	N/A
create	Create resources and start operations	actuatorconfiguration, context, discoveryspace, samplestore, operation
delete	Delete resources	actuatorconfiguration, context, datacontainer, discoveryspace, samplestore, operation
describe	Human-friendly resource descriptions	datacontainer, discoveryspace, experiment
edit	Edit resource metadata	actuatorconfiguration, datacontainer, discoveryspace, samplestore, operation
get	List and retrieve resources	actuator, actuatorconfiguration, context, datacontainer, discoveryspace, experiment, samplestore, measurementrequest, operation, operator
show	Display resource-related content	discoveryspace, operation (via subcommands)
template	Generate resource templates	actuator, actuatorconfiguration, context, discoveryspace, samplestore, operation
upgrade	Upgrade resources	actuatorconfiguration, datacontainer, discoveryspace, samplestore, operation
version	Display ado version	N/A

Key Features

Common Options Across Commands

• --use-latest: Automatically use the most recently created resource
  (supported by get, describe, show subcommands)
• --output/-o: Specify output format (table, json, yaml, csv, etc.)
• --query/-q: Filter by field values using JSONPath
• --label/-l: Filter by metadata labels
• --file/-f: Specify configuration file
• --dry-run: Validate without executing (create command)

Resource Type Aliases

• discoveryspace = space
• actuatorconfiguration = ac
• samplestore = store
• datacontainer = dcr
• operation = op
• context = ctx
• experiment = exp
• measurementrequest = request

Show Subcommands

The show command is unique in having multiple subcommands:

• details: High-level overview and related resources
• entities: Entity data and measurements
• related: One-hop related resources
• requests: Request timeseries (operations only)
• results: Result timeseries (operations only)
• summary: Formatted summaries (spaces only)

[AlessandroPomponio]

ado CLI Commands - What They Do

Top-Level Commands

ado context [context_name]

Manages the active execution context. Without arguments, displays the current
context. With a context name, switches to that context.

ado contexts

Lists all available contexts and indicates which one is currently active.

ado create <resource_type>

Creates new resources or starts operations based on YAML configuration files.

ado delete <resource_type> <resource_id(s)>

Deletes resources and their associated data. Supports batch deletion of multiple
resources.

ado describe <resource_type> [resource_id]

Provides human-readable descriptions of resources and experiments.

ado edit <resource_type> <resource_id>

Edits the metadata of existing resources (labels, descriptions, annotations).
Does not modify core configuration.

ado get <resource_type> [resource_id]

Retrieves and lists resources with filtering and output options. Can list all
resources of a type or retrieve a specific one.

ado show <subcommand>

Displays detailed content and analysis related to resources. This is the only
command with actual subcommands.

Subcommands:

• details - Shows high-level overview and statistics about a space or
  operation
• entities - Displays entities and their measurement data
• related - Shows resources directly connected to the specified resource
  (one-hop relationships)
• requests - Shows the timeseries of measurement requests during an
  operation
• results - Shows the timeseries of measurement results during an
  operation
• summary - Generates formatted summaries of discovery spaces

ado template <resource_type>

Generates template YAML files for creating resources. Can include JSON schemas
for validation.

ado upgrade <resource_type>

Upgrades resources to the latest schema version and applies migrations.

ado version

Displays the installed version of ado-core.

[AlessandroPomponio]

Note on Resources Supported by ADO Commands

create

Supports:

• CoreResourceKinds (except datacontainers, which cannot be created manually)
• context

---

delete

Supports:

• CoreResourceKinds
• context

---

describe

Does NOT support:

• Some CoreResourceKinds:
  • actuatorconfiguration
  • samplestore
  • operation
• context

---

edit

Supports:

• CoreResourceKinds

---

get

Supports:

• CoreResourceKinds
• actuator
• experiment
• measurementrequest
• operator

---

template

Supports:

• CoreResourceKinds (except datacontainers)
• actuator (to be removed — see refactor(cli): remove ado template actuator #976)
• context

---

upgrade

Supports:

• CoreResourceKinds

[AlessandroPomponio]

From the above (non-show commands), we should think about:

• feat(cli): add support for ado describe actuatorconfiguration
  • Could include information such as what actuator it is for, in what operations it's being used**
• feat(cli): add ado describe samplestore
  • Could include information on the spaces whose entities are from this samplestore: how many spaces there are, their ids, how many entities are in the store, etc.**
• feat(cli): add ado describe operation
  • Could have info on how many measurements were submitted, how many entities, successful/non successful measurements, etc.**
• feat(cli): add ado describe context
  • Could have info on whether the context is local or remote, address of the db, what has been run as part of this context (how many sample stores, how many spaces, operations, etc.)**
• refactor(cli): remove ado get measurementrequest
  • Not sure if it's useful

**might not be possible in describe, since we use only the __rich__ method

[AlessandroPomponio]

With regards to ado show #874 provides some suggestions on how it should be reworked. It suggests having 4 sub commands:

• data
• related
• stats
• trace

data

The issue says that data is easier for users to understand and remember than entities. However, if I was a user trying to run ado show data operation, I would be confused as to why i'm only seeing entities and their values but not datacontainers, as those are pieces of data as well. With that said, we also wouldn't be able to use a different term like measurements, as it would conflict with the proposed trace, and also it would be weird to do something like ado show measurement --include missing.

related

Unchanged

stats

The issue suggests merging details and summary, while providing additional stats types. This seems fine, we can replace summary by supporting its output types. My only worry is that a tabular output could be very wide since column headers might be long-ish

trace

This is largely fine. There would need to be a required flag of sorts to choose whether to display requests or results. It would be a bit weird to have a yaml option for output as it would be clashing with the semantics that are proper of get, but I don't see how else to handle it

[AlessandroPomponio]

At the moment show requests/results return only high-level information, e.g.:

(ado-core) alessandropomponio@MacBook-Pro-di-Alessandro ~/D/G/p/ado (maj_sigterm_graceful_fix)> ado show requests op --use-latest --no-trunc
INFO:   Using operation random_walk-1.8.1.dev21+g824191c8.d20260506104511.dirty-297731.
┌───────┬────────────┬───────────────┬──────────────┬────────────────────────────┬─────────────────────────────────────────────────┬──────────────────────────────────────┬─────────┬──────────────┬────────────────────┬──────────────────────┬──────────┐
│ INDEX │ Request ID │ Request Index │ Request type │ Timestamp                  │ Experiment ID                                   │ Entity IDs                           │ Status  │ Measurements │ Valid Measurements │ Invalid Measurements │ Metadata │
├───────┼────────────┼───────────────┼──────────────┼────────────────────────────┼─────────────────────────────────────────────────┼──────────────────────────────────────┼─────────┼──────────────┼────────────────────┼──────────────────────┼──────────┤
│ 0     │ 7b72fc     │ 0             │ measured     │ 2026-05-06 13:35:43.831423 │ custom_experiments.calculate_pressure_ideal_gas │ ['mol.0.1-temperature.270-volume.1'] │ Success │ 1            │ 1                  │ 0                    │ {}       │

(ado-core) alessandropomponio@MacBook-Pro-di-Alessandro ~/D/G/p/ado (maj_sigterm_graceful_fix)> ado show results op --use-latest --no-trunc
INFO:   Using operation random_walk-1.8.1.dev21+g824191c8.d20260506104511.dirty-297731.
┌───────┬──────────────────────────────────────┬────────────┬───────────────┬──────────────┬─────────────────────────────────────────────────┬──────────────────────────────────┬───────┬──────────────────────┬──────────┐
│ INDEX │ Result UID                           │ Request ID │ Request Index │ Request type │ Experiment ID                                   │ Entity ID                        │ Valid │ Number of Properties │ Metadata │
├───────┼──────────────────────────────────────┼────────────┼───────────────┼──────────────┼─────────────────────────────────────────────────┼──────────────────────────────────┼───────┼──────────────────────┼──────────┤
│ 0     │ fff09877-57f9-4cfc-a333-818d636f251a │ 7b72fc     │ 0             │ measured     │ custom_experiments.calculate_pressure_ideal_gas │ mol.0.1-temperature.270-volume.1 │ True  │ 1                    │ {}       │

To get the value of the measurement one would need to do something like:

(ado-core) alessandropomponio@MacBook-Pro-di-Alessandro ~/D/G/p/ado (maj_sigterm_graceful_fix) [1]> ado get measurementrequest a5085d --from-operation random_walk-1.8.1.dev21+g824191c8.d20260506104511.dirty-297731
WARN:   This resource only supports the following output format: ['json', 'yaml'].
INFO:   We will output using yaml.
entities:
- constitutive_property_values:
  - property:
      identifier: temperature
    value: 276
    valueType: NUMERIC_VALUE_TYPE
  - property:
      identifier: volume
    value: 9
    valueType: NUMERIC_VALUE_TYPE
  - property:
      identifier: mol
    value: 0.8
    valueType: NUMERIC_VALUE_TYPE
  generatorid: no_priors_characterization
  identifier: mol.0.8-temperature.276-volume.9
experimentReference:
  actuatorIdentifier: custom_experiments
  experimentIdentifier: calculate_pressure_ideal_gas
measurements:
- entityIdentifier: mol.0.8-temperature.276-volume.9
  experimentReference:
    actuatorIdentifier: custom_experiments
    experimentIdentifier: calculate_pressure_ideal_gas
  measurements:
  - property:
      targetProperty:
        identifier: pressure
    value: 203.98148289493332
    valueType: NUMERIC_VALUE_TYPE
  uid: 864c5060-33a1-4927-a4bc-c49cb3fbd728
operation_id: random_walk-1.8.1.dev21+g824191c8.d20260506104511.dirty-297731
requestIndex: 17
requestid: a5085d
status: Success
timestamp: '2026-05-06T13:36:17.535339'

This information is instead meant to be accessed via show entities, e.g.:

(ado-core) alessandropomponio@MacBook-Pro-di-Alessandro ~/D/G/p/ado (maj_sigterm_graceful_fix)> ado show entities op --use-latest --no-trunc
INFO:   Using operation random_walk-1.8.1.dev21+g824191c8.d20260506104511.dirty-297731.
┌───────────────┬──────────────┬──────────────────────────────────┬─────────────────────────────────────────────────┬────────────────────────────┬─────┬─────────────┬────────┬────────────────────┬────────────┬──────────────┬───────┐
│ request_index │ result_index │ identifier                       │ experiment_id                                   │ generatorid                │ mol │ temperature │ volume │ pressure           │ request_id │ entity_index │ valid │
├───────────────┼──────────────┼──────────────────────────────────┼─────────────────────────────────────────────────┼────────────────────────────┼─────┼─────────────┼────────┼────────────────────┼────────────┼──────────────┼───────┤
│ 17            │ 0            │ mol.0.8-temperature.276-volume.9 │ custom_experiments.calculate_pressure_ideal_gas │ no_priors_characterization │ 0.8 │ 276         │ 9      │ 203.98148289493332 │ a5085d     │ 0            │ True  │
└───────────────┴──────────────┴──────────────────────────────────┴─────────────────────────────────────────────────┴────────────────────────────┴─────┴─────────────┴────────┴────────────────────┴────────────┴──────────────┴───────┘

[AlessandroPomponio]

I wonder if the solution to all these problems and the key to user intuition would be to have something like ado show measurements where a trace output format prints a tree-like structure of requests branching out into results (basically merging show requests and show results and removing redundant information that's repeated) and other output formats being handled similar to ado show entities.

With this option I see two criticalities:

• The include options that show entities has
• The inability to get a single request/result

[michael-johnston]

To get the value of the measurement one would need to do something like:

This is what we do know - we shouldn't do this anymore

This information is instead meant to be accessed via show entities, e.g.:

It's not that doesn't contain all the data c.f. the columns show in ado show requests/results which are from this same YAML

I think the solution for me is

ado show trace operation -> same as ado show requests operation`` ado show trace operation --with-results -> similar to ado show results operation`
ado show trace operation REQUESTID -> get the yaml of REQUESTID, c.f. ado get space [SPACEID]
ado show trace space (I can show a trace of everything added to a space)
ado show trace store (I can show a trace of everything added to store)

--with-results would do something like --property-format for show entities.

If not specified you get current result
If is specified you get results BUT with the missing request columns and the columns in request order i.e. you "expand" the results for each request

request headers

│ INDEX │ Request ID │ Request Index │ Request type │ Timestamp                  │ Experiment ID                                   │ Entity IDs                           │ Status  │ Measurements │ Valid Measurements │ Invalid Measurements │ Metadata │

result headers

│ INDEX │ Request ID │ Request Index │ Request type │ Timestamp                  │ Experiment ID                              | Result Index    │ Result UID |   Entity ID                          │  Valid │ Number of Properties │ Metadata  

Out: Entity IDS (a list) , Status , Measurements, Valid Measurements, Invalid Measurements
In: Result UID, Result Index, Entity ID, Valid, Number Of Properties

[AlessandroPomponio]

ado show trace operation REQUESTID -> get the yaml of REQUESTID, c.f. ado get space [SPACEID]

This is counterintuitive given the semantics of get and show, though. Also note that it would need to be something like ado show trace operation OPERATION_ID [something else to select a single measurement]

ado show trace space (I can show a trace of everything added to a space)
ado show trace store (I can show a trace of everything added to store)

Could you give me a few examples?

--with-results would do something like --property-format for show entities.

How would one choose between observed and target? Or what would be the options?

If not specified you get current result

What does current mean here?

If is specified you get results BUT with the missing request columns and the columns in request order i.e. you "expand" the results for each request

request headers

│ INDEX │ Request ID │ Request Index │ Request type │ Timestamp                  │ Experiment ID                                   │ Entity IDs                           │ Status  │ Measurements │ Valid Measurements │ Invalid Measurements │ Metadata │

result headers

│ INDEX │ Request ID │ Request Index │ Request type │ Timestamp                  │ Experiment ID                              | Result Index    │ Result UID |   Entity ID                          │  Valid │ Number of Properties │ Metadata  

Out: Entity IDS (a list) , Status , Measurements, Valid Measurements, Invalid Measurements In: Result UID, Result Index, Entity ID, Valid, Number Of Properties

I didn't quite get this.

I also didn't understand how we would handle --include and --aggregate from show entities in show trace

[AlessandroPomponio]

A possible new structure for the refactored CLI could be:

ado
├── context [context_name]
├── contexts [--output/-o]
├── create <resource_type>
│   ├── actuatorconfiguration
│   ├── context
│   ├── discoveryspace
│   ├── samplestore
│   └── operation
├── delete <resource_type> <resource_id(s)>
│   ├── actuatorconfiguration
│   ├── context
│   ├── datacontainer
│   ├── discoveryspace
│   ├── samplestore
│   └── operation
├── describe <resource_type> [resource_id]
│   ├── datacontainer
│   ├── discoveryspace
│   └── experiment
├── edit <resource_type> <resource_id>
│   ├── actuatorconfiguration
│   ├── datacontainer
│   ├── discoveryspace
│   ├── samplestore
│   └── operation
├── get <resource_type> [resource_id]
│   ├── actuator
│   ├── actuatorconfiguration
│   ├── context
│   ├── datacontainer
│   ├── discoveryspace
│   ├── experiment
│   ├── samplestore
│   ├── operation
│   └── operator
├── show <subcommand>
│   ├── measurements <resource_type> [resource_id]
│   │   ├── discoveryspace
│   │   └── operation
│   ├── tree
│   │   ├── actuatorconfiguration
│   │   ├── datacontainer
│   │   ├── discoveryspace
│   │   ├── samplestore
│   │   └── operation
│   ├── trace <resource_type> [resource_id]
│   │   ├── discoveryspace
│   │   ├── samplestore
│   │   └── operation
│   └── stats <resource_type> [resource_id(s)]
│   │   ├── datacontainer
│   │   ├── discoveryspace
│   │   ├── samplestore
│   │   └── operation
├── template <resource_type>
│   ├── actuator
│   ├── actuatorconfiguration
│   ├── context
│   ├── discoveryspace
│   ├── samplestore
│   └── operation
├── upgrade <resource_type>
│   ├── actuatorconfiguration
│   ├── datacontainer
│   ├── discoveryspace
│   ├── samplestore
│   └── operation
└── version

[AlessandroPomponio]

Focusing in on the show changes:

• Rename show entities to show measurements to clearly convey meaning
• Add show tree to replace show related with more advanced features (see feat(cli): ado tree mvp #984 - we can iterate there on the design)
• Merge show measurements and show requests in show trace
• Merge show details and show summary in show stats