ish person context
Add real interactions to a person, review the episodes, and approve them for runs
Usage: ish person context
ish person context add
Add files plus a note; ish reads them into episodes for review
Usage: ish person context add <person-id> [files]... [options]
Arguments
(required)
(optional, variadic)
Options
boolean
Wait until the episodes are ready, a question needs your answer, or reading fails; never approves
string
Maximum wait, 0 < seconds <= 3600 (default 600) Default: “600”.
string
Your account in your own words, or @path to a UTF-8 file
string
UTF-8 note file, or - for stdin
string
Mark a file shown (the person saw it) or record (the file is the log itself); repeatable Default: [].
string
UUID sent as the import’s idempotency key. After a failure, check what was created with status <person-id> <import-id> or list; a re-run uploads the files again
string
Add every supported file directly in a folder, one import per file; a re-run adds nothing it added before
string
Why you can share this about the person: agreed, public, work, own, or remembered (your last answer); asked at a terminal when omitted
boolean
Other people are in the material too
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context status
Read an import, or resume waiting on it with —wait
Usage: ish person context status <person-id> <import-id> [options]
Arguments
(required)
(required)
Options
boolean
Wait until the episodes are ready, a question needs your answer, or reading fails; never approves
string
Maximum wait, 0 < seconds <= 3600 (default 600) Default: “600”.
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context answer
Answer an import’s question (needs_input) and read it again
Usage: ish person context answer <person-id> <import-id> <answer> [options]
Arguments
(required)
(required)
(required)
Options
boolean
Wait until the episodes are ready, a question needs your answer, or reading fails; never approves
string
Maximum wait, 0 < seconds <= 3600 (default 600) Default: “600”.
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context list
List this person’s episodes in this workspace with beat counts
Usage: ish person context list <person-id> [options]
Arguments
(required)
Options
string
pending, approved or withdrawn
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context show
Read one episode: its summary, files, facts and every beat with the person’s own words
Usage: ish person context show <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context approve
Approve the episode version you read; its pending beats go into new runs
Usage: ish person context approve <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
The version you read with show (required unless you confirm at a terminal)
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context leave-out
Stop using an episode (or one —beat) in new runs and in runs already set up; the record is kept as Not in use
Usage: ish person context leave-out <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
The episode version you read (not needed with —beat)
string
Leave out only this beat
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context withdraw
Usage: ish person context withdraw <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
The episode version you read (not needed with —beat)
string
Leave out only this beat
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context use-again
Undo leave-out: use an episode (or one —beat) again; it returns to In use if it was approved
Usage: ish person context use-again <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
Use only this beat again
string
The episode version you read (default: the version use-again reads first)
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context edit
Correct ish’s wording, remove a quote, or name a speaker; an approved episode stays approved
Usage: ish person context edit <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
string
New title
string
New summary: how it started and how it ended
string
What the episode was about, as a stable name (“Onboarding flow”), at most 80 characters; keeps the current version unless —about-version or —clear-about-version
string
Which version of that subject (“v2”, “after the redesign”), at most 40 characters; needs —about
boolean
Remove the version and keep the subject
boolean
Remove what the episode was about, subject and version
string
The beat the following —what-they-did / —what-was-going-on change; repeatable
string
New what-they-did for the —beat before it
string
New what-was-going-on for the —beat before it; "" clears it
string
Remove a quote: the beat id and the 0-based index in its quotes (show —json); repeatable Default: [].
string
Name a speaker: the label as show —json lists it, then the display name; repeatable Default: [].
string
The version you read (default: the version edit reads first)
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context erase
Permanently erase an episode, its beats, files nothing else cites, and copies in runs already set up
Usage: ish person context erase <person-id> <episode-id> [options]
Arguments
(required)
(required)
Options
boolean
Skip confirmation prompt (required in —json or non-TTY contexts)
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context export
Print the whole person as one Markdown file: profile, bio, answered scenarios, then the approved context
Usage: ish person context export <person-id> [options]
Arguments
(required)
Options
string
Write the Markdown to this file instead of stdout, and print its path
string
Workspace ID; accepted for consistency (inferred from alias / active context)
ish person context patterns
Read the person’s patterns, reject or pin a line, accept or dismiss a proposed bio line
Usage: ish person context patterns
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 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 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
Who this person is: fictional, self, or real_third_party (a real person other than you; their context is approved by a human only, and they stay private). Moving off real_third_party asks y/N at a terminal
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 a short-alias <id> must belong to (defaults to the active workspace)
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
Print the projectable field names for the response instead of the data, then exit (also: —fields ?)
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)