# Run your first rote Play

> In five minutes, inspect and run a published Play without cloning a repository or rebuilding its method.

## Option A: start in an agent harness

Give this URI to a supported coding-agent harness and ask it to inspect and run the Play:

```text
https://play.modiqo.ai/modiqo/hello
```

The URI is the interface. The harness can inspect the published contract and guide setup if rote is not yet available.

## Option B: start in a terminal

### 1. Install rote

```bash
curl -fsSL https://getrote.dev/install | bash
```

### 2. Sign in

```bash
rote login
rote whoami
```

`rote whoami` should identify the signed-in account. Credentials remain local to the tools and services that use them; a published Play declares requirements but does not carry the user's secrets.

### 3. Inspect before running

```bash
rote play inspect https://play.modiqo.ai/modiqo/hello
```

The Play card describes the inputs, version, author, dependencies, services, declared writes, authentication, and privileged requirements.

### 4. Run the Play

```bash
rote play run https://play.modiqo.ai/modiqo/hello
```

A run produces a human report by default. Plays can also provide a one-line summary or canonical JSON for scripts and CI:

```bash
rote play run https://play.modiqo.ai/modiqo/hello --output=summary
rote play run https://play.modiqo.ai/modiqo/hello --output=json
```

## Run with parameters

Plays declare inputs as `key=value`. Inspect the Play first to see names, types, defaults, and allowed values:

```bash
rote play run https://play.modiqo.ai/<owner>/<name> key=value
```

Use a pinned URI when the exact release must remain stable:

```text
https://play.modiqo.ai/<owner>/<name>@<version>
```

## Create a Play when search comes up empty

Open a sequential workspace:

```bash
rote init my-useful-method --seq
```

Do the task once through rote's API, process, or browser reach. Each useful response becomes an addressable workspace artifact such as `@1` or `@2`. Query those artifacts instead of copying large payloads into the conversation.

When the result is proven:

1. preserve the reusable result through the pending save gate;
2. crystallize the workspace trace into a declared step graph;
3. inspect the generated contract;
4. lint it;
5. run normal, boundary, and failure cases;
6. release it locally;
7. optionally publish an immutable version to a registry namespace.

The complete tutorial is available at https://www.modiqo.ai/docs/03-create-your-first-play.md.

## Troubleshooting principles

- Inspect before running anything that touches credentials or writes data.
- Missing dependencies should fail with an explicit requirement rather than an unexplained stack trace.
- A hard failure names the failed step and blocks downstream work.
- Resume a failed run when the report provides a resume token; completed steps can restore from recorded outcomes.
- Use `rote guidance`, `rote grammar`, and `rote man` for live CLI documentation.

## Canonical links

- Human-readable tutorial: https://www.modiqo.ai/agent/tutorial/
- Full developer docs: https://www.modiqo.ai/docs/README.md
- Work with Plays: https://www.modiqo.ai/docs/02-work-with-plays.md
- Create a Play: https://www.modiqo.ai/docs/03-create-your-first-play.md
- Reference: https://www.modiqo.ai/docs/09-reference.md