Skip to main content
This is the full happy path: define a study, give it something to experience, dispatch simulated people, and read back what they noticed. Every step shows the CLI and the MCP server side by side. New to the building blocks? Skim study, iteration, and people first; this page assumes them. The example runs an interactive study against a live URL. The same shape works for the other modalities (text, video, audio, image, document, chat) by swapping the content flag.

​
Before you start

  • The CLI installed and signed in (ish login), or an agent wired to the hosted MCP server. See the CLI quickstart or connect an agent.
  • A workspace to work in. The CLI uses your active workspace; the MCP server takes a workspace_id (for example w-6ec).
  • A public URL to point at.
1

Create the study and point it at a URL

A study is the persistent shape of what you want to learn: a modality, the assignments people work through, and the questions they answer. Passing --url on the CLI creates the first iteration in the same call, so you go from nothing to runnable at once. On the MCP server, create the study, then add iteration A with study_add_iteration.
ish study create \
  --name "Landing page first look" \
  --modality interactive \
  --url https://example.com \
  --assignment "First look:Land on the page and decide if you would keep reading" \
  --question "What stood out, and what was confusing?"
The CLI prints the new study id and an alias like s-b2c, and remembers it as your active study, so later commands need no id. On the MCP server, pass the returned study_id to the next call.
--assignment takes one task as Name:Instructions. Add more by repeating the flag. For multi-step checklists or richer question types, see study create and the study tools.
2

Choose who experiences it

A run with no audience reuses whatever participants already exist on the iteration. To resolve a fresh group, sample from the pool or generate people to fit a brief. Selection is shared across both surfaces. See people and audiences.
# sample three Swedish people aged 35 to 50 (deferred to the run step below)
# or generate people first when the pool is thin for your archetype
ish person generate \
  --description "Tech-savvy millennials in the US who use mobile banking" \
  --count 3
You can skip this step and let the run sample directly from the pool. Each dispatch is capped at 20 participants; for a bigger panel, run several slices.
3

Simulate the visits

Dispatch the simulation against the latest iteration. Pass an audience to resolve a fresh group, or none to reuse the iteration’s existing participants.
# sample one person and block until the run finishes
ish study run --sample 1 -y --wait

# or a demographic slice
ish study run --country SE --min-age 35 --max-age 50 --sample 3 -y --wait
A study run draws credits per participant who completes. The two surfaces guard the spend differently:
  • The CLI refuses without -y / --yes in a non-interactive context (the default for agents and CI), exiting 2 with error_kind: "ConfirmationRequired". Pass -y to confirm.
  • The MCP server is subscription-funded, so no per-dispatch approval is needed. To add a checkpoint before drawing credits, stage participants with study_run(dispatch=False) and dispatch them later with audience=None.
The full model is in runs and asks.
Interactive and media runs take one to five minutes. Many MCP clients cap a single tool call at about 30 seconds, which overrides timeout, so a blocking wait=True aborts before the run finishes. Prefer the default wait=False and poll with the returned next_action hint. On the CLI, --wait blocks safely from the terminal.
4

Read the reported journey

Read back what each simulated person noticed, where they got stuck, and the answers to your questions. See reactions and results.
# full results: per-participant sentiment, interview answers, interactions
ish study results

# leaner roll-up: counts, sentiment, one comment per participant
ish study results --summary
You see the reasoning behind every reaction, not just a number. To slice by assignment, sentiment, frame, or segment, see slicing results on the CLI and the study tools on the MCP.
If a run you just finished still reports status: draft, read runtime_status instead. The raw status column updates lazily and can lag a completed run.

​
What you just did

You defined a study, gave it a URL to experience, dispatched simulated people, and read their reported journey, before putting the page in front of anyone. Your audience, ish.

​
Next steps

Compare two versions

Add a second iteration with a changed URL or content, run it, and read the two side by side.

Run a wider panel

Sample by country, age, gender, or occupation, or split a large cohort across several dispatches.

React to creative instead

When the question is “which of these lands?”, reach for an ask rather than a study.

Share the results

Hand a public, read-only link to a stakeholder with ish study share.