Documentation/01 · Run your first play

Run your first play

Where you are in the journey: you've never touched this product. Five minutes from now you'll have run a real, published automation against live data — without writing a line of code, cloning a repo, or reading an API doc.

What a play is

A play is a saved, runnable unit of work. Someone — a teammate, your org, a stranger on the public hub — did a piece of work once, carefully: probing DNS records, auditing lockfiles against a vulnerability database, checking whether a website is launch-ready. Then they crystallized it: the work became a typed, versioned artifact with declared inputs, a dependency graph of steps, and an honest report at the end.

A play lives at a URI. The URI is the whole interface:

ROTE/text2 lines
https://play.modiqo.ai/<owner>/<name>          ← always the latest versionhttps://play.modiqo.ai/<owner>/<name>@1.1.0    ← pinned forever to 1.1.0

That's the center of gravity of this whole product. Everything else in these docs — workspaces, modalities, DAGs, crystallization — exists to make these URIs plentiful, trustworthy, and yours to create.

Run one

You need the rote CLI and a signed-in identity:

ROTE/bash3 lines
curl -fsSL https://getrote.dev/install | bashrote loginrote whoami        # ok: [email protected]

(Play URIs also come in an install flavor — https://play.modiqo.ai/install?play=owner/name@version — which walks a machine with nothing on it through setup and the play in one link.)

Now run a real play — this one checks whether a DNS record has propagated across the internet's big public resolvers:

rote play run https://play.modiqo.ai/modiqo/dns-propagation-check domain=yourdomain.com

What you get back, in about a third of a second of actual work:

ROTE/text24 lines
dns-propagation-check  run_id: run_20260812_162456.478_0   [layer 1]    validate_input  .......................... @1  (25ms)   [layer 2 — 4 parallel]    query_quad9  ............................. @2  (192ms)    query_google  ............................ @3  (92ms)    query_cloudflare  ........................ @4  (105ms)    discover_authoritative  .................. @5  (185ms)   [layer 3]    compute_verdict  ......................... @6  (34ms)   Summary: 6/6 completed, 0 failed, 0 blocked DNS PROPAGATION  yourdomain.com A   stages  ████████████████████████  6/6 ok VERDICT  consistent  Every reachable public resolver matches the reference value set.  Resolver agreement: 100%

Pause on what just happened, because it's the product in miniature:

What happens when you run a play URI
  1. You gave it a URI. No git clone, no npm install, no reading source first (though you can — see below).
  2. Identity and authorization were checked. Public plays resolve for anyone; running them and pulling private ones requires the right membership. Access is a property of the play, not of your copy-paste diligence.
  3. The play's declared dependencies were verified — this one needs python3 and dig, and it says so in a manifest, so the failure mode for a missing tool is a clear message, not a stack trace.
  4. A graph of steps executed — notice [layer 2 — 4 parallel]. The play's author didn't write threading code; they declared which steps depend on which, and the runner parallelized the rest.
  5. You got an honest report. The stages bar tells you how many sources actually answered. If Quad9 had been unreachable, you'd see a labeled degraded row — a visible unknown, never a silent gap.

Look before you run

You never have to run blind. Every play has an inspectable play card:

rote play inspect https://play.modiqo.ai/modiqo/dns-propagation-check

The card shows what the play does, its parameters (names, defaults, allowed values), what it accesses (services, writes, authentication, privileged access), its version, and its author. For anything that touches your machine or credentials, read the card first — that's what it's for.

Parameters are just key=value

Plays declare their inputs. Pass them inline:

ROTE/bash2 lines
rote play run https://play.modiqo.ai/modiqo/dns-propagation-check \  domain=modiqo.ai record_type=TXT resolvers=cloudflare,google

Everything has a sane default; the card tells you what's available. Wrong input fails closed with a message that names the rule (record_type must be one of A, AAAA, CNAME, MX, TXT, NS, or CAA) — the play refuses to guess.

Three views of one result

Every run can be rendered three ways, and a well-authored play keeps them in agreement:

ROTE/bash3 lines
rote play run <uri> <params>                    # full human report (default)rote play run <uri> <params> --output=summary   # one line, for scripts' logsrote play run <uri> <params> --output=json      # canonical structured facts

The JSON is the machine's view — pipe it into jq, feed it to CI, archive it:

ROTE/bash2 lines
rote play run https://play.modiqo.ai/modiqo/dependency-vulnerability-check root=. --output=json \  | jq '.result.findings[] | {id, severity, package: .package.name}'

When something fails

A play that hits a hard fault fails closed: the failed step is named, everything downstream shows BLOCKED, and the runner hands you a resume token:

ROTE/text4 lines
    validate_input  .......................... FAILED  (process exited with code 2)      blocked: compute_verdict, discover_authoritative, query_cloudflare, ...   Retry: rerun this play with --resume run_20260812_162600.844_24

--resume re-executes only what didn't complete — finished steps restore from their recorded outcomes. For a play that spent two minutes querying an API before a transient network blip, that's two minutes you don't pay twice.

Try a few more

ROTE/bash8 lines
# Is it down, or is it just you? DNS + TLS + HTTP probes correlated with provider status feedsrote play run https://play.modiqo.ai/modiqo/provider-outage-triage target=https://github.com # Is this package name free on npm, PyPI, and crates.io?rote play run https://play.modiqo.ai/modiqo/package-name-search names=my-cool-tool # Audit a project's lockfiles against the OSV vulnerability databaserote play run https://play.modiqo.ai/modiqo/dependency-vulnerability-check root=~/code/my-project

You are now productive. You can run any play whose URI reaches you — in chat, in a runbook, in a README. The next section makes plays part of your daily work: finding them, comparing them, and sharing yours.

Next: 2 · Work with plays →