> ## Documentation Index > Fetch the complete documentation index at: https://docs.ishlabs.io/llms.txt > Use this file to discover all available pages before exploring further. # study run > Command reference: ish study run. ## `ish study run` Run a study (creates participants for the latest iteration and dispatches simulations) Usage: `ish study run [id] [options]` ### Arguments Study ID (alias or UUID) - positional alias for --study (optional) ### Options Workspace ID Study ID Iteration to run (defaults to latest on the study) Person IDs/aliases (comma-separated or repeatable) Default: \[]. Randomly sample N people from the matching pool (max 20 per dispatch - split into multiple slices for larger cohorts) Use every AI person matching the filters (workspace-wide if no filters set) (capped at 20 per dispatch - split into multiple slices for larger cohorts) Substring match against person name Substring match against person bio Substring match against person occupation (repeatable) Default: \[]. Filter by gender (female, male, nonbinary; repeatable, OR semantics) Default: \[]. Filter by 2-letter country code (repeatable) Default: \[]. Minimum age (inclusive) Maximum age (inclusive) Filter by visibility: workspace (your workspace), shared (community-published), platform (admin-curated). Old values `private` / `public` are accepted and mapped to `workspace` / `platform`. Simulation config ID (required for media unless every person has one) Max interactions per participant (interactive / media only). Precedence: flag > iteration's stored value > CLI default (20). Max conversation turns per participant (chat studies only) Allow chat agent to end the conversation early when goals are met (chat studies only) Language code (e.g. en, sv) Wait for all simulations to reach a terminal state before returning Wait timeout in seconds (default 300; only with --wait) Per-POST timeout in seconds for the create-participants + dispatch calls (default 120). Bump if `study run` times out client-side after seeding participants but before dispatch - those participants exist server-side and are surfaced under `seeded_but_not_dispatched_*` in the error envelope so the agent can resume. Skip confirmation prompt Run simulation with local browser (Playwright) instead of remote Show browser window (local mode only) Slow down actions by ms (local mode only) Open Chrome DevTools (local mode only) Enable detailed debug logging to stderr and \~/.ish/local-sim.log Run N participants in parallel (local mode only). Browser: default all. Native iOS/Android: pools N auto-provisioned devices - simulators (iOS) / headless emulators from your AVDs (Android) - default 1, capped at 5, auto-sized to host RAM (and AVD count). Local target platform: 'web' (Playwright), 'android' (adb emulator), or 'ios' (simctl+idb simulator). Defaults to the iteration's platform. Native local mode: path to an .apk (android) / .app (ios) to install, or an installed package/bundle id to launch. The extension implies --platform. ## `ish study poll` Check simulation progress for a study Usage: `ish study poll [participant_id] [options]` ### Arguments Participant ID (alias or UUID; from `ish study run --json`.participant\_aliases\[]) (optional) ### Options Study ID (poll all simulations for study) Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/\) ## `ish study wait` Poll until simulations reach a terminal state (completed/errored/failed/cancelled) Usage: `ish study wait [participant_id] [options]` ### Arguments Participant ID (alias or UUID; from `ish study run --json`.participant\_aliases\[]) (optional) ### Options Study ID (wait for all participants in the study) Iteration ID (wait for participants in this iteration only) Max seconds to wait (default 300) Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/\) ## `ish study cancel` Cancel a running simulation Usage: `ish study cancel [options]` ### Arguments Participant ID (alias or UUID; from `ish study run --json`.participant\_aliases\[]) (required) ### Options Workspace ID; accepted for consistency (workspace is inferred from \) ## `ish study extend` Extend a terminal participant with more steps (and optionally a mid-run instruction) Usage: `ish study extend [options]` ### Arguments Participant to extend (alias or UUID). Must be in a terminal state (completed/failed/cancelled). (required) ### Options Extra interactions past the source's original cap (1-50; backend caps server-side) Default: "10". User message to inject as the new participant resumes. Accepts inline text, `@/path/to/file`, or `-` for stdin. Block until the new participant reaches a terminal state Wait timeout in seconds (default 300; only with --wait) Per-POST timeout in seconds for the dispatch call (default 120) Workspace ID; accepted for consistency (workspace is inferred from \) ## Global flags Every command accepts the global flags. output the version number Auth token (or set ISH\_TOKEN env var) Read auth token from a file (preferred over --token / ISH\_TOKEN) Default workspace ID; per-subcommand --workspace overrides Output as JSON (auto-enabled when piped) Extract a single field from the JSON response and print only its value (implies --json internally; supports dotted paths e.g. person.name) Force human-readable output even when stdout is piped (overrides JSON-when-piped auto-detection) Comma-separated fields to include in JSON output (e.g. alias,name,status) Include full UUIDs and timestamps in JSON output Disable colored output (also honored: NO\_COLOR env var) Suppress progress messages on stderr (no-op for read commands that emit none)