ish person list
List people (defaults to AI people in your workspace; pass —visibility platform for the shared pool)
Usage: ish person list [options]
Options
string
Filter by workspace ID
string
Substring match against person name
string
Substring match against person bio
string
Substring match against person occupation (repeatable) Default: [].
string
Person type: ai, human, all (default: ai) Default: “ai”.
string
Filter by gender (repeatable) Default: [].
string
Filter by country code, e.g. US (repeatable) Default: [].
string
Minimum age
string
Maximum age
string
Filter by visibility: workspace (your own people - the DEFAULT) | shared (community-published) | platform (the full shared pool, ~13.6k) (legacy ‘private’/‘public’ accepted as aliases)
string
Max results (default 50) Default: “50”.
string
Offset for pagination Default: “0”.
ish person create
Create a person from an exact JSON spec (no LLM). Accepts inline flags or —file.
Usage: ish person create [options]
Options
string
JSON file with person data (or ’-’ for stdin). Escape hatch for fields not covered by inline flags.
string
Person name (required if —file omitted)
string
Person type: ai | human (default: ai when —file omitted)
string
Person description
string
Person bio
string
Occupation
string
Country code, e.g. US
string
Gender, e.g. female
string
Date of birth
string
Education level. One of: less_than_secondary, secondary, some_post_secondary, vocational_or_associate, bachelor, graduate
string
Household composition (MECE). One of: single, couple_no_kids, couple_with_kids, single_parent, shared_housing, adult_with_parents, multi_generational. A couple raising children is couple_with_kids, not couple_no_kids; “single” means lives alone with no partner, roommates, parents, or children in the household.
string
Self-described neighborhood type. One of: urban, suburban, small_town, rural
string
Self-identified relative socioeconomic position. One of: lower, lower_middle, middle, upper_middle, upper, prefer_not_to_say
string
Primary daytime activity / labor-force status. One of: employed_full_time, employed_part_time, self_employed, unemployed_seeking, student, homemaker, retired, unable_to_work, other
string
AccessibilityProfile v1.0 as an inline JSON string OR a path to a JSON file. Empty object {} is the canonical default. Validated client-side against the spec before submit.
string
Workspace (product) ID; falls back to active workspace
ish person generate
Generate people plus evidence-grounded scenarios from a brief and/or sources
Usage: ish person generate [options]
Options
string
Description / researcher brief (use @path to read from file)
string
Read description from a file
string
Source UUID or local file path; auto-uploads paths (repeatable) Default: [].
string
Per-source researcher note - how the person reacted to THAT file. Paired with —source by index (repeatable). Only applies to local-path sources; for already-uploaded aliases the note is whatever was set at upload time. Default: [].
boolean
Apply speaker diarization to audio sources (silently ignored for text/image)
string
Number of people to generate (1-10). Omit to let the model propose a count
boolean
Print the LLM’s suggested count for a single processed source and exit (no generation)
string
Workspace (product) ID; falls back to active workspace
boolean
Skip fetching the evidence-grounded scenarios for each generated person
boolean
Don’t poll source-processing status. Only relevant when —source is a local path (paths get auto-uploaded and processed).
string
Source-processing poll timeout in seconds. Only relevant when —source is a local path. Default: “300”.
string
Generation-job poll timeout in seconds (default 180; pass a larger value for long-running jobs). The job keeps running server-side past this; re-poll later or re-run with a longer —timeout - don’t re-enqueue, that would duplicate the work. Default: “180”.
ish person get
Get person details (accepts multiple IDs for batched lookup)
Usage: ish person get <ids>... [options]
Arguments
Person ID(s) - one or more aliases/UUIDs (space- or comma-separated) (required, variadic)
Options
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person update
Update a person
Usage: ish person update <id> [options]
Arguments
Person ID (required)
Options
string
JSON file with update data (escape hatch for fields not covered by inline flags)
string
Person name
string
Person description
string
Person bio
string
Occupation
string
Country code, e.g. US
string
Gender, e.g. female
string
Date of birth
string
Education level. One of: less_than_secondary, secondary, some_post_secondary, vocational_or_associate, bachelor, graduate
string
Household composition (MECE). One of: single, couple_no_kids, couple_with_kids, single_parent, shared_housing, adult_with_parents, multi_generational. A couple raising children is couple_with_kids, not couple_no_kids; “single” means lives alone with no partner, roommates, parents, or children in the household.
string
Self-described neighborhood type. One of: urban, suburban, small_town, rural
string
Self-identified relative socioeconomic position. One of: lower, lower_middle, middle, upper_middle, upper, prefer_not_to_say
string
Primary daytime activity / labor-force status. One of: employed_full_time, employed_part_time, self_employed, unemployed_seeking, student, homemaker, retired, unable_to_work, other
string
AccessibilityProfile v1.0 as an inline JSON string OR a path to a JSON file. Empty object {} is the canonical default. Validated client-side against the spec before submit.
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person delete
Delete a person
Usage: ish person delete <id> [options]
Arguments
Person ID (required)
Options
string
Workspace ID; accepted for consistency (workspace is inferred from the person)
boolean
Skip confirmation prompt (required in —json or non-TTY contexts)
ish person suggest-scenarios
Ask the LLM for scenario probes to craft a specific simulated person
Usage: ish person suggest-scenarios [options]
Options
string
Workspace (product) ID; falls back to active workspace
string
What you already know about this participant. Use @path to read from file.
string
Read —context from a file
string
Number of scenarios to return (1-10, default 5)
string
Answers already collected this session. Inline JSON, @/path/to.json, or - for stdin. Array of {type, prompt, answer}; max 40.
string
Prompt labels already shown this session, so the LLM avoids paraphrasing them. Inline JSON, @/path, or -. Array of strings; max 40.
ish person evidence
Manage scenario-answer evidence on a person
Usage: ish person evidence
ish person evidence add
Persist scenario answers as structured evidence on a person
Usage: ish person evidence add <id> [options]
Arguments
Person ID (alias or UUID) (required)
Options
string
Array of {text, source, scenario_prompt?, raw_response?} where source ∈ situation|voice|binary|micro-story. Inline JSON, @/path/to.json, or - for stdin.
string
Read —traces from a JSON file
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person evidence list
List evidence traces persisted on a person (newest first)
Usage: ish person evidence list <id> [options]
Arguments
Person ID (alias or UUID) (required)
Options
string
Workspace ID; accepted for consistency (inferred from alias / active context)
Global flags
Every command accepts the global flags.boolean
output the version number
string
Auth token (or set ISH_TOKEN env var)
string
Read auth token from a file (preferred over —token / ISH_TOKEN)
string
Default workspace ID; per-subcommand —workspace overrides
boolean
Output as JSON (auto-enabled when piped)
string
Extract a single field from the JSON response and print only its value (implies —json internally; supports dotted paths e.g. person.name)
boolean
Force human-readable output even when stdout is piped (overrides JSON-when-piped auto-detection)
string
Comma-separated fields to include in JSON output (e.g. alias,name,status)
boolean
Include full UUIDs and timestamps in JSON output
boolean
Disable colored output (also honored: NO_COLOR env var)
boolean
Suppress progress messages on stderr (no-op for read commands that emit none)