> ## 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. # ask > Command reference: ish ask. ## `ish ask run` Run an ask - append a round to the active ask, or `--new` to create a fresh ask Usage: `ish ask run [id] [options]` ### Arguments Ask alias or UUID to append to (defaults to active ask; ignored with --new) (optional) ### Options Ask ID; alternative to positional argument Create a new ask instead of appending a round Ask name (with --new; auto-generated if omitted) Ask description (with --new only) Workspace ID (with --new only) Round prompt - what participants respond to Required. Variant: text:"...", ./file.png, image:./file.png, ./file.png::label=B (repeatable) Default: \[]. JSON manifest of variants (alternative to --variant) Each participant picks a favourite variant (compatible with --wants-ratings; can be set together). Each participant rates every variant 1-5 (compatible with --wants-pick; can be set together). If neither is set, participants leave a free-form comment only. Questions as inline JSON, @file, or a JSON file path: \[\{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}] 2-letter language code (with --new only) Default: "en". 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 simulatable AI person matching the filters (with --new only) (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`. Drill-in subset (Pattern B) - append-round only. 1-indexed prior round to filter against. Pair with --subset-variant. Drill-in subset (Pattern B) - append-round only. Variant id (UUID) on the prior round whose pickers should inherit. Read from `aggregates.pick_buckets` or `variants[*].id` on the prior round's `ask results --json`. Wait until the round completes (or errors) Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) ## `ish ask list` List asks for a workspace Usage: `ish ask list [options]` ### Options Workspace ID Include archived asks alongside active ones (default: active only). ## `ish ask create` Create a new ask with a first round and dispatch to people Usage: `ish ask create [options]` ### Options Workspace ID Ask name Required. Ask description Round prompt - what participants respond to Required. Variant: text:"...", ./file.png, image:./file.png, ./file.png::label=B (repeatable) Default: \[]. JSON manifest of variants (alternative to --variant) Each participant picks a favourite variant (compatible with --wants-ratings; can be set together). Each participant rates every variant 1-5 (compatible with --wants-pick; can be set together). If neither is set, participants leave a free-form comment only. Questions as inline JSON, @file, or a JSON file path: \[\{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}] 2-letter language code Default: "en". 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 simulatable AI person matching the filters (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`. Create the ask in DRAFT status without billing or dispatching the round. Hand the draft id back to the user, then start it with `ish ask dispatch <id>`. People flags are still required because the participants are materialized at create time. Mutually exclusive with --wait (nothing to wait for). Wait until the first round completes (or errors) Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) ## `ish ask dispatch` Dispatch a draft ask - draws credits and starts the round Usage: `ish ask dispatch [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Wait until the first round completes (or errors) Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask get` Get full ask detail (accepts multiple IDs for batched lookup) Usage: `ish ask get [ids]... [options]` ### Arguments Ask alias(es)/UUID(s); defaults to active ask from `ish ask use` (optional, variadic) ### Options Ask ID; alternative to a single positional argument Show only round N (1-indexed); single-ask only Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask results` Show aggregated results (picks, mean ratings, comments, summary) Usage: `ish ask results [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Show only round N (1-indexed; default: all rounds) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask wait` Poll until a round is completed (or errored) Usage: `ish ask wait [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Round number to wait for (1-indexed; default: last round) Max seconds to wait (default 300) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask add-round` Append a new round to an existing ask (max 5 per ask) Usage: `ish ask add-round [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Workspace ID; accepted for consistency (workspace is inferred from the ask) Round prompt Required. Variant flag (repeatable; same syntax as `ask create`) Default: \[]. JSON manifest of variants Each participant picks a favourite variant (compatible with --wants-ratings; can be set together). Each participant rates every variant 1-5 (compatible with --wants-pick; can be set together). If neither is set, participants leave a free-form comment only. Questions as inline JSON, @file, or a JSON file path: \[\{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}] Drill-in subset (Pattern B) - 1-indexed prior round to filter against. Pair with --subset-variant. The new round dispatches only to participants who picked --subset-variant on round N. Drill-in subset (Pattern B) - variant id (UUID) on the prior round whose pickers should inherit. Pair with --subset-round. Read from `aggregates.pick_buckets` or `variants[*].id` on the prior round. Wait until the new round completes Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) ## `ish ask add-questions` Append questionnaire questions to a round. Default: additive re-dispatch (prior picks/comments/ratings preserved; only the new questions are answered). Pass --redispatch-all to fully reset and re-run the round from scratch. Usage: `ish ask add-questions [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Round number (1-indexed) or round id/alias Required. Questions as inline JSON, @file, or a JSON file path: \[\{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}] Required. Clear prior phase-1 outputs (comment, pick, ratings) and re-run the entire round from scratch (legacy behavior). Default is additive - only the new questions are answered. Wait until the round completes (or errors) Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask retry` Re-dispatch only the errored responses on a round (idempotent: zero-errored is a no-op). Usage: `ish ask retry [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Round number (1-indexed) or round id/alias Required. Wait until the retried round completes (or errors) Wait timeout in seconds (default 300) Skip the credit-spend confirmation (required in --json / non-TTY to proceed) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask add-people` Add people to an existing ask (they become participants when the round runs; optionally backfill prior rounds) Usage: `ish ask add-people [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Workspace ID; accepted for consistency (workspace is inferred from the ask) Round to add people to (required) Required. 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) Add every simulatable AI person matching the filters not already included (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`. Backfill prior rounds in order for new people ## `ish ask update` Update an ask's name or description Usage: `ish ask update [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument New name New description Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask archive` Archive an ask (hides it from default list) Usage: `ish ask archive [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask unarchive` Restore an archived ask Usage: `ish ask unarchive [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask delete` Delete an ask and all its rounds, responses, and participants Usage: `ish ask delete [id] [options]` ### Arguments Ask alias or UUID (defaults to active ask) (optional) ### Options Ask ID; alternative to positional argument Skip confirmation prompt (required in --json or non-TTY contexts) Workspace ID; accepted for consistency (inferred from alias / active context) ## `ish ask use` Set the active ask (saved to \~/.ish/config.json) Usage: `ish ask use [id] [options]` ### Arguments Ask alias or UUID (optional) ### Options Remove the active ask from config 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)