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: [].

SSR dimension to measure, e.g. purchase_intent (repeatable). Auto-adds a ‘Would you buy this?’ question and reports an ish of purchase intent (a distribution + mean) on the results. 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 (treated as markdown → canonical content_doc), or @filepath to read from file. Creates iteration A inline (text modality only)

Markdown content, or @filepath to read from file. Parsed to the canonical content_doc block AST (ish.doc/1). Creates iteration A inline (text modality only). Mutually exclusive with —content-text.

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 or local file path of the media file (local files are auto-uploaded). Creates iteration A (video, audio, document modalities).

Comma-separated image URLs or local file paths (local files are auto-uploaded; URLs and paths may be mixed). Creates iteration A (image modality).

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. Text (content_doc, ADR-0015) is block-id based: heading_based {split_level} auto-splits at headings (the default - author one ## per section), or section_based {sections[{segment_id,name,label,start_block_id}]} for manual block-id boundaries. Video/audio: time_based {intervals_seconds, labels?}. Sections are SEMANTIC (a long article is usually 3-6, not one per block). The old paragraph_start/end form is DEAD on content_doc (errors every participant at run) - use heading_based or start_block_id. Lets one study create build a complete segmented iteration.

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

Paste-exact HTML (e.g. a branded email), or @filepath. Creates iteration A inline (text modality) as the ADR-0015 format:html carrier - rendered source-faithful, re-sanitized backend-side. Mutually exclusive with —content-md / —content-text.

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 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 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)

Print the projectable field names for the response instead of the data, then exit (also: —fields ?)

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)