study create

Workspace ID

Study name Required.

Study description

Study modality (interactive, video, audio, text, image, document, chat)

Content type (per-modality enum - see ‘Content types by modality’ below). Changes how —title is presented to participants (e.g. content-type email renders —title as the Subject: line). Not used for interactive / chat.

Assignment as ‘Name:Instructions’ (repeatable) Default: [].

JSON file with assignments array

Inline JSON array of assignments (escape hatch)

Add a text question to the questionnaire (repeatable; type=text, timing=after) Default: [].

Questionnaire as inline JSON array, @file, or a JSON file path - supports text, slider, likert, single-choice, multiple-choice, number; timing=before|after

Text content to evaluate, or @filepath to read from file. Creates iteration A inline (text modality only)

URL to test. Creates iteration A inline (interactive modality only)

Screen format for interactive iterations: desktop (default) or mobile_portrait (hyphen/underscore variants accepted)

Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step iteration create flow.

Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step iteration create flow.

Participant-facing content title - the headline participants read before the body (text + media modalities - image, video, audio, document; optional). With —content-type email it becomes the email Subject: line. Not an internal label. Not used for interactive / chat.

Segmentation JSON for the inline iteration A - time_based {intervals_seconds, labels?}, section_based {sections[{name,label,…}]}, or page_based {} (text + media). 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). Lets one study create build a complete segmented iteration - no separate iteration create needed.

Content-config JSON for the inline iteration A (early_termination, selected_segment_indices) - text + media.

HTML version of the text, or @filepath - text modality (email rendering)

Email ‘From’ display name - text modality (email rendering)

Email sender address - text modality (email rendering)

Hero image URL - text modality (email rendering)

Saved chatbot endpoint id or alias. Creates iteration A inline (chat modality, external_chatbot mode)

ChatbotEndpointConfig JSON file (or - for stdin); embedded directly. Mutually exclusive with —endpoint (chat modality, external_chatbot mode)

Maximum conversation turns per participant (chat modality only; default 12)

Chat mode: external_chatbot (default) or participant_pair (two AI groups talk to each other) - chat modality only

Person IDs/aliases for group A (comma-separated or repeatable). Pass a single profile 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 group B. 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 - chat participant_pair mode

Side-B scenario + goal - chat participant_pair mode

Which side speaks first (default: a) - chat participant_pair mode

RoleCriteria filter for side A (JSON object 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. Use INSTEAD of —group-a or alongside it. chat participant_pair mode.

RoleCriteria filter for side B - same shape as —role-criteria-a. chat participant_pair mode.

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)