Reference

Quick lookups for everything the journey covered. Live, exhaustive docs ship inside the CLI: rote guidance [topic], rote grammar [topic], rote man <topic>, rote how.

Install & identity

ROTE/bash4 lines

01curl -fsSL https://getrote.dev/install | bash02rote login                    # browser-based sign-in03rote whoami                   # ok: [email protected]04rote pull powerpack --yes     # optional: curated adapters + plays in one command

Running plays

ROTE/bash7 lines

01rote play run <target> [key=value …]        # target: URI | org/name[@ver] | local name | path02rote play run <target> … --output=summary   # one line03rote play run <target> … --output=json      # canonical structured result04rote play run <target> … -y/--yes           # skip confirm prompts (CI / non-TTY)05rote play run <target> … --resume <run_id>  # continue a failed/interrupted run06rote play run <target> … --max-concurrency <N>07rote play run <target> … --dry-run

URI forms

ROTE/text3 lines

01https://play.modiqo.ai/<owner>/<name>            # floats to latest release02https://play.modiqo.ai/<owner>/<name>@1.2.3      # pinned, immutable03https://play.modiqo.ai/install?play=<owner>/<name>@1.2.3    # bootstrap/install URI

Finding & vetting

ROTE/bash4 lines

01rote play search "<query>"                  # local + registry02rote play inspect <uri> [--json]            # the play card: params, ACCESS block, version03rote explore "<intent>"                     # cross-adapter capability discovery04rote play run https://play.modiqo.ai/modiqo/play-dag play=<uri-or-path>   # x-ray any DAG

Workspace (explore → crystallize)

ROTE/bash9 lines

01rote init <name> --seq                      # open a workspace (flight recorder)02rote proc run <program> [args…]             # shell reach — capture as @N03rote browse <url>                           # browser reach — navigate → wait → snapshot → slice04rote query @N '<jq>' -r                     # read a field by reference05rote query schema @N                        # inspect a response's shape06rote query @N '<jq>' -s <var>               # save a scalar as $var07rote play pending write <ws> --name … --description …   # anchor reusable work08rote play pending list | show <ws> | discard <ws>09rote workspace export <ws> [--params <NAMES>] [-f shell|steps|typescript] [--with-presentation]

Authoring & publishing

ROTE/bash7 lines

01rote play lint <main.ts>                    # contract checks; fix what it names02rote play release <org/name> [--force] [--keep-local]03rote registry play push <play-path> <slug> [--private] [--dry-run] [--allow-undeclared-endpoints]04rote registry play pull <org/name> [--yes] [--no-deps]05rote registry play visibility <org/name> <public|private>06rote registry play list | search <q> | info <org/name> | delete | restore07rote play share create --audience <organization|users> [--user <handle>] [--expires-in <dur>]

The chain: lint → test (happy + negative) → release → push → canonical readback (run the published URI). Versions are immutable; every change is a bump.

Adapters (API reach)

ROTE/bash5 lines

01rote adapter new <id> [spec]                # from OpenAPI / Discovery / GraphQL / gRPC / catalog02<id>_probe   "<intent>"                     # semantic search over the API's operations03<id>_call    <method> key=value …           # execute one04<id>_batch_call                             # parallel batch05rote registry play find-by-adapter <adapter-id>

Step grammar cheat sheet

ROTE/yaml15 lines

01steps:02  my_step:03    type: process.exec                      # or adapter/<id>, adapter.auth.ensure,04    timeout_ms: 30000                       #    browser.navigate|wait|extract|click|type05    depends_on: [other_step]                # ordering edge (barrier)06    for_each: '$.items'                     # fan out per item → $item, $item_index07    max_concurrency: 408    argv:09    - python310    - -c11    - |212 13      …script; stdout is data, exit status is the failure signal…14    - $my_param                             # play parameter15    - '@other_step{$.stdout.text | fromjson | .field}'   # value edge (must be scalar)

Rules that bite:

Value-edge jq must resolve to a scalar; the dialect has fromjson, field access, join, map/select, to_entries — no tojson. Pack collections into a delimited scalar field (chr(31)/chr(30) separators) and unpack in the consumer.
No literal */ anywhere inside the frontmatter comment.
parameters: use param_type; quote non-string defaults (default: '20').
Steps have no TTY — pass --yes-style flags to any subcommand that might prompt.
Presentation: stepName("literal") only; call all three of out.human / out.summary / out.result; out.result takes an object literal.

The failure model

Situation	Step behavior	User sees
Expected absence (endpoint down, feature off, none found)	`{"ok":true,"warning":"…"}`, exit 0	`degraded`/`skipped` ledger row, play completes
Hard fault (bad input, missing required tool)	message → stderr, exit ≠ 0	step `FAILED`, dependents `BLOCKED`, `--resume` offered
Destructive work	own step, gated by `apply=true`	dry-run by default, labeled `skipped` stage

Representation parity

human, summary, json are views of one run. No semantic fact may silently disappear from a view that claims completeness. Truncate only with a declared count; make out.result the canonical superset; declare it:

ROTE/ts5 lines

01representations: {02  human:   "complete — …",03  json:    "canonical — …",04  summary: "intentionally lossy — …",05}

Compare views from the same run when testing (--resume <run_id> --output=json re-renders recorded outcomes).

Troubleshooting

Symptom	Likely cause → fix
`interactive prompt required but stdin is not a terminal`	confirm prompt in non-TTY → add `--yes`
`must resolve to scalar values`	value edge returns object/array → pipe to a field / `join(",")` / packed scalar
`JSONPath '…' returned no results`	unsupported jq filter (e.g. `tojson`) or wrong path → `rote query schema @N` during exploration
`frontmatter is closed early by a */`	literal `*/` inside the JSDoc frontmatter → remove/reword it
`data did not match any variant of untagged enum ParameterFormat`	unquoted non-string default → `default: '20'`
push rejected: visibility mismatch	play record is private, push assumed public → `--private` or flip with `registry play visibility`
push rejected: undeclared endpoints	steps call an adapter missing from `requires_endpoints` → declare it (escape hatch: `--allow-undeclared-endpoints`)
`FLOW_OUTPUT_BARE_CONSOLE_LOG`	`console.log` in a step/presentation → `process.stdout.write(JSON.stringify(x) + "n")`
run failed midway	fix the cause, then `rote play run … --resume <run_id>` — completed steps restore

Exemplars to copy from

Play	Why it's worth reading
`modiqo/hello`	9 steps · 2 layers; self-probing roots, value-edge fan-out, glyph stage ledger
`modiqo/play-dag`	4 steps · 3 layers; identity-gated URI pull; representation-parity contract
`modiqo/dns-propagation-check`	the canonical validate → parallel probes → verdict-join shape
`modiqo/dependency-vulnerability-check`	10 steps · 5 layers; per-ecosystem fan-out, staged resume points
`modiqo/cleanup-merged-git-branches`	destructive work done right: gated `apply=true` deletion stage