> ## 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. # iteration > Command reference: ish iteration. ## `ish iteration list` List iterations for a study Usage: `ish iteration list [options]` ### Options Study ID Workspace ID; accepted for consistency (workspace is inferred from the study) ## `ish iteration create` Create a new iteration with run-time content/URL Usage: `ish iteration create [options]` ### Options Study ID (or set via `ish study use`) Workspace ID; accepted for consistency (workspace is inferred from the study) Iteration name (defaults to the next position letter A/B/C… if omitted) Iteration description Platform (browser, android, ios, figma, code) - interactive only URL to test - interactive only (optional for ios/android native apps) Native app bundle id (or .app/.apk path) - ios/android; supplies the iteration target so --url isn't required Screen format (mobile\_portrait, desktop) - interactive only; hyphen/underscore variants accepted. Default: desktop, or mobile\_portrait for native ios/android Locale code (e.g. en-US) - interactive only Figma file key - required when --platform=figma Figma start node id - required when --platform=figma Figma flow name - interactive only Text content to evaluate, or @filepath to read from file - text modality HTML version of the text, or @filepath to read from file - text modality Email 'From' display name - text modality (email rendering) Email sender address - text modality (email rendering) Hero image URL - text modality (email rendering) URL or local file path to media file - video, audio, document modalities Comma-separated image URLs or local file paths - image modality Content title shown to participants (the leading headline they read) - media modalities MIME type (e.g. video/mp4) - media modalities Ad copy or social post caption (or @filepath) - ads & social posts HTML version of copy text (or @filepath) Social platform (instagram, tiktok, facebook, linkedin, x) Copy position relative to media (before, after) Default: "after". Segmentation JSON - time\_based \{intervals\_seconds, labels?}, section\_based \{sections\[\{name,label,...}]}, or page\_based \{} - media modalities. section\_based sections are SEMANTIC: group related paragraphs into a few coherent sections (a long article is usually 3-6 sections, not one per paragraph; paragraph\_start/end just mark where each section begins and ends). Content config JSON - \{early\_termination, selected\_segment\_indices?} - media modalities Chat mode: external\_chatbot (default; probe a customer chatbot) or participant\_pair (two AI people talk to each other) Saved chatbot endpoint id - chat modality, external\_chatbot mode (legacy; prefer --endpoint) Inline chatbot endpoint config JSON - chat modality, external\_chatbot mode (legacy; prefer --endpoint-config) Max participant turns (1-50) - chat modality (default 12) End the chat session early when the participant signals stop - chat modality Saved chatbot endpoint id (alias or UUID) - chat modality, external\_chatbot mode Raw ChatbotEndpointConfig JSON file or `-` for stdin - chat modality, external\_chatbot mode Person IDs/aliases for side A (comma-separated or repeatable). Pass a single person and N on --group-b to broadcast (1×N rehearsal: fix side A, vary side B) - chat participant\_pair mode Default: \[]. Person IDs/aliases for side B (comma-separated or repeatable). When both sides are explicit they must be equal length, BUT if either side is a singleton it's auto-broadcast to match the other (1×N rehearsal) - chat participant\_pair mode Default: \[]. Side-A scenario + goal text, or @filepath - chat participant\_pair mode Side-B scenario + goal text, or @filepath - chat participant\_pair mode Which side speaks first (default: a) - chat participant\_pair mode RoleCriteria filter for side A (inline JSON or @filepath). Keys: occupation\[], min\_age, max\_age, gender\[], country\[], education\_level\_in\[], household\_in\[], locale\_type\_in\[], income\_level\_in\[], employment\_status\_in\[], requires\_captions, uses\_screen\_reader, prefers\_reduced\_motion, prefers\_high\_contrast, has\_any\_accessibility\_need. The five \*\_in arrays accept snake\_case spec values; the five accessibility filters are booleans. Persona-first: filters the eligible profile pool without altering personas. Use INSTEAD of --group-a or alongside it (criteria then validates the explicit list). chat participant\_pair mode. RoleCriteria filter for side B - same shape as --role-criteria-a. chat participant\_pair mode. Raw iteration details JSON (overrides individual flags) ## `ish iteration get` Get iteration details (accepts multiple IDs for batched lookup) Usage: `ish iteration get ... [options]` ### Arguments Iteration ID(s) - one or more aliases/UUIDs (space- or comma-separated) (required, variadic) ### Options Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish iteration update` Update an iteration Usage: `ish iteration update [options]` ### Arguments Iteration ID (required) ### Options Iteration name Iteration description Iteration details as JSON string Iteration label (uppercase letters) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish iteration delete` Delete an iteration Usage: `ish iteration delete [options]` ### Arguments Iteration ID (required) ### Options Skip confirmation prompt (required in --json / non-TTY) Workspace ID; accepted for consistency (inferred from alias / active context) ## 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)