diff --git a/.cursor/skills/using-ado-cli/SKILL.md b/.cursor/skills/using-ado-cli/SKILL.md index 125d8b7bb..f7c56a360 100644 --- a/.cursor/skills/using-ado-cli/SKILL.md +++ b/.cursor/skills/using-ado-cli/SKILL.md @@ -1,9 +1,6 @@ --- 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. +description: "Reference for ado CLI command syntax, flags, and usage patterns — covers get, create, edit, show, and describe subcommands, output formatting with -o and --output-file, convenience flags (--use-latest, --set, --with), debugging with -l, and run_experiment for local point testing. Use when writing or verifying ado CLI commands, looking up correct command syntax or flags, debugging unexpected CLI output, or explaining ado command patterns." --- # Using the ado CLI @@ -29,15 +26,27 @@ uv run ado [COMMAND] [SUBCOMMAND1] [SUBCOMMAND2] --help - Required arguments are included - Optional flags match actual CLI behavior -## Output format vs output file +## Output Format and File Handling 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. +- `--output-file PATH` writes formatted output to **PATH** instead of stdout. + +Shell redirects (`>`) work for simple cases. Prefer `--output-file` when: + +- **Pre-flight checks**: ado validates the path is writable before fetching, + avoiding failure after a long data fetch. +- **Stdout pollution**: `--output-file` writes only formatted output to the file; + logs stay on stderr. A redirect captures both. +- **Table truncation**: terminal-width column truncation applies to redirected + output but not to `--output-file`. + +```bash +uv run ado get space SPACE_ID -o yaml > space.yaml +uv run ado show entities operation OPERATION_ID -o csv --output-file entities.csv +``` ## Commands That do not exist @@ -167,33 +176,6 @@ uv run ado describe space SPACE_ID uv run ado describe experiment EXPERIMENT_ID ``` -## Using --output-file - -For `ado get` and `ado show` subcommands, output can be captured with a shell -redirect (`>`) or with the `--output-file PATH` flag. In many cases a redirect -(or pipe) is perfectly fine and fits naturally into terminal workflows: - -```bash -uv run ado get space SPACE_ID -o yaml > space.yaml -uv run ado show entities operation OPERATION_ID -o csv > entities.csv -``` - -Prefer `--output-file` in the following situations: - -- **Pre-flight checks**: ado validates that the path is writable before starting - a potentially long data fetch, avoiding a failure after fetch. -- **Stdout pollution**: if any log lines or warnings are mixed into stdout (e.g. - when another tool in the pipeline writes to stdout), a redirect captures that - noise alongside the data. `--output-file` writes only the formatted output to - the file; logs continue to go to stderr. -- **Table Truncation**: when output to terminal the table format (the default - for --output) may truncate columns to fit terminal width. This truncation is - not removed when the output is redirected, but is if --output-file specified - -```bash -uv run ado show entities operation OPERATION_ID -o csv --output-file entities.csv -``` - ## Debugging If commands are not given expected output use the -l flag to activate different @@ -205,16 +187,10 @@ e.g. for debug level logs uv run ado -lDEBUG [COMMAND] ``` -## Terminology - -### Entities - -Entities represent points in the discovery space with: +## show Commands Quick Reference -- **Constitutive properties** (inputs/priors) - what defines the point -- **Measured properties** (outputs/posteriors) - what was observed - -### Understanding show Commands +Entities are points in the discovery space — constitutive properties (inputs) +plus measured properties (outputs). @@ -226,13 +202,11 @@ Entities represent points in the discovery space with: -**Example distinction**: - ```bash -# Get the actual measurement data for entities +# Measurement data for entities uv run ado show entities operation op-123 -# Get metadata about the operation's results +# Metadata about the operation's results (not measurements) uv run ado show results operation op-123 ``` @@ -313,31 +287,11 @@ 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 +3. **Prefer shortcuts** (`--use-latest`, `--with`) in tutorials to reduce friction -5. **Explain terminology** the first time: "entities (the inputs and their +4. **Explain terminology** the first time: "entities (the inputs and their measurements)" -### Example Documentation Pattern - -```markdown -## 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 @@ -371,7 +325,11 @@ uv run ado create space -f space.yaml # Validate with dry-run uv run ado create operation -f operation.yaml --dry-run --use-latest space -# Actually create it +# If dry-run fails: check error message, fix the YAML, re-run dry-run +# Common issues: missing experiment references, invalid parameter types, +# unresolvable --use-latest (no resource of that type exists yet) + +# Once dry-run passes, actually create it uv run ado create operation -f operation.yaml --use-latest space ```