# ish

> Documentation for the ish CLI and MCP server. Simulate a visit and read the reactions before you ship.

- [ish docs](https://docs.ishlabs.io/index.md): Simulate a visit and read the reactions before you ship.
- [Quickstart: the CLI](https://docs.ishlabs.io/start/cli-quickstart.md): Install the ish CLI, sign in, simulate one visit, and read one reaction in under five minutes.
- [Quickstart: connect an AI agent](https://docs.ishlabs.io/start/connect-an-agent.md): Wire ish into one AI client over MCP, confirm the connection, and read your first reaction.
- [How ish works](https://docs.ishlabs.io/concepts/overview.md): The mental model behind ish: from a workspace down to the reactions a simulated person reports back.
- [Workspaces](https://docs.ishlabs.io/concepts/workspace.md): A workspace is the top-level container that holds your studies, asks, people, and sources, and the unit ish bills and caps against.
- [Studies](https://docs.ishlabs.io/concepts/study.md): The persistent unit in ish: show simulated people something and read their reactions, then change it and run again.
- [Iterations](https://docs.ishlabs.io/concepts/iteration.md): The configured run of a study: the layer that carries the one artifact (a URL, a media file, or a chatbot endpoint) participants actually experience.
- [Modalities](https://docs.ishlabs.io/concepts/modalities.md): The seven modalities ish simulates, the content types that tune each one, and how they map to what a study evaluates.
- [Runs and asks](https://docs.ishlabs.io/concepts/run-vs-ask.md): The two ways ish dispatches simulated people, and when each one fits.
- [People and panels](https://docs.ishlabs.io/concepts/people.md): What a Person is, how a Person differs from a Participant, how the panel for a run gets selected, and where a Person is visible.
- [Sources](https://docs.ishlabs.io/concepts/source.md): The real evidence behind a generated person: transcripts, audio, images, and PDFs that ground a simulated Person in how someone actually reacted.
- [Assignments and questionnaires](https://docs.ishlabs.io/concepts/assignment-questionnaire.md): The two halves of a study definition: what each simulated person is asked to do, and what they answer.
- [Asks and rounds](https://docs.ishlabs.io/concepts/ask-and-round.md): The comparison building blocks in ish: variants, picks, ratings, and follow-up rounds against a fixed panel.
- [Reactions and results](https://docs.ishlabs.io/concepts/reactions-and-results.md): What a run produces: a reported journey per participant, with transcripts, signals, and the reasoning behind them, not a score.
- [Site access](https://docs.ishlabs.io/concepts/site-access.md): How ish reaches a gated URL: each site holds its own public mark, basic auth, session cookie, or login form.
- [Secrets](https://docs.ishlabs.io/concepts/secrets.md): Per-workspace key/value secrets that back {{secret:KEY}} placeholders in chatbot endpoint config.
- [Active context](https://docs.ishlabs.io/concepts/active-context.md): How the ish CLI remembers your workspace, study, and ask so you don't repeat IDs, and why the MCP server works differently.
- [Credits and limits](https://docs.ishlabs.io/concepts/credits-and-limits.md): How credits work as a usage allowance, the per-tier entity caps, and the 20-participant cap on every dispatch.
- [Sharing results](https://docs.ishlabs.io/concepts/sharing.md): How public, no-login links let anyone open a study's results in a browser, and what they see.
- [Benchmarks and reference workspaces](https://docs.ishlabs.io/concepts/benchmarking.md): How a reference workspace and study benchmark let you run the same study head-to-head against competitors or alternative versions.
- [The CLI and the MCP server](https://docs.ishlabs.io/concepts/cli-and-mcp.md): One backend, two developer surfaces. How the ish CLI and the ish MCP server map to the same operations, and what each one is for.
- [Run a study end to end](https://docs.ishlabs.io/guides/first-study.md): Create a study, point it at a URL, simulate visits, and read the reported journey, on the CLI or the MCP server.
- [Slice results](https://docs.ishlabs.io/guides/slicing-results.md): Filter and group ish study results by frame, segment, turn, side, assignment, step, sentiment, actor, iteration, or participant.
- [Build a specific person](https://docs.ishlabs.io/guides/build-a-person.md): Generate a simulated person, or a small cohort, from a written brief and real research artifacts.
- [Probe a chatbot](https://docs.ishlabs.io/guides/chat-studies.md): Stand up an external_chatbot study so simulated people talk to your HTTP chatbot and report back where the conversation breaks.
- [Rehearse a conversation](https://docs.ishlabs.io/guides/chat-pair.md): Stand up a participant-pair study where two simulated people converse so you can pressure-test a pitch, sales call, or one-on-one before it happens.
- [Test against localhost](https://docs.ishlabs.io/guides/local-vs-connect.md): Choose between ish connect (cloud fleet reaches your localhost) and study run --local (the browser runs on your machine).
- [Use ish in CI](https://docs.ishlabs.io/guides/ci-automation.md): Authenticate with a token, parse JSON output, branch on exit codes, and recover from a failed run inside a pipeline.
- [Connect your client](https://docs.ishlabs.io/integrations/index.md): Pick your AI client and wire it to the ish MCP server.
- [Claude Code](https://docs.ishlabs.io/integrations/claude-code.md): Connect Claude Code to the ish MCP server, confirm the tools are live, and read your first reaction.
- [Cursor](https://docs.ishlabs.io/integrations/cursor.md): Connect Cursor to the hosted ish MCP server and run studies without tripping its tool-call cap.
- [Claude Desktop](https://docs.ishlabs.io/integrations/claude-desktop.md): Connect Claude Desktop to the hosted ish MCP server over OAuth, confirm the tools are live, and read your first reaction.
- [ChatGPT](https://docs.ishlabs.io/integrations/chatgpt.md): Add ish to ChatGPT as a connector and work around its resource-blind MCP client.
- [VS Code](https://docs.ishlabs.io/integrations/vscode.md): Connect VS Code to the hosted ish MCP server and sign in over OAuth, even though VS Code binds a fresh loopback port every session.
- [Lovable](https://docs.ishlabs.io/integrations/lovable.md): Connect Lovable's agent to the hosted ish MCP server, and point a study at a Lovable URL ish can actually reach.
- [Replit](https://docs.ishlabs.io/integrations/replit.md): Connect Replit's agent to the hosted ish MCP server, and point a study at a Replit URL ish can actually reach.
- [CLI overview](https://docs.ishlabs.io/cli/overview.md): Install the ish CLI, keep it current, and find the right command.
- [Authentication](https://docs.ishlabs.io/cli/auth.md): How the ish CLI resolves a token, where credentials are stored, and the login, logout, and status commands.
- [Global flags](https://docs.ishlabs.io/cli/global-flags.md): Every flag the ish CLI accepts on any command, with defaults and resolution order.
- [Output and scripting](https://docs.ishlabs.io/cli/output-modes.md): Parse ish CLI output in scripts and CI: lean JSON on a pipe, --get, --fields, --human, and stream separation.
- [Exit codes and errors](https://docs.ishlabs.io/cli/exit-codes.md): The ish CLI exit codes 0 to 5 and the structured error envelope agents and CI branch on.
- [Environment variables](https://docs.ishlabs.io/cli/env-vars.md): Every ISH_* environment variable the ish CLI reads, with defaults and precedence.
- [Aliases](https://docs.ishlabs.io/cli/aliases.md): Short id aliases the ish CLI mints for every entity, the canonical prefix table, and how they resolve.
- [Confirmations and caps](https://docs.ishlabs.io/cli/confirmations.md): How the CLI gates credit-spending and destructive commands, the -y / ISH_ASSUME_YES opt-in, and the 20-participant dispatch cap.
- [Command index](https://docs.ishlabs.io/cli/generated/index.md): Every ish CLI command, with its subcommands.
- [Sessions: login, logout, status](https://docs.ishlabs.io/cli/generated/session.md): Command reference: ish Sessions: login, logout, status.
- [connect, disconnect](https://docs.ishlabs.io/cli/generated/connect.md): Command reference: ish connect, disconnect.
- [workspace](https://docs.ishlabs.io/cli/generated/workspace.md): Command reference: ish workspace.
- [study](https://docs.ishlabs.io/cli/generated/study.md): Command reference: ish study.
- [study create](https://docs.ishlabs.io/cli/generated/study-create.md): Command reference: ish study create.
- [study run](https://docs.ishlabs.io/cli/generated/study-run.md): Command reference: ish study run.
- [study results](https://docs.ishlabs.io/cli/generated/study-results.md): Command reference: ish study results.
- [Study sub-verbs](https://docs.ishlabs.io/cli/generated/study-extras.md): Command reference: ish Study sub-verbs.
- [ask](https://docs.ishlabs.io/cli/generated/ask.md): Command reference: ish ask.
- [person](https://docs.ishlabs.io/cli/generated/person.md): Command reference: ish person.
- [iteration](https://docs.ishlabs.io/cli/generated/iteration.md): Command reference: ish iteration.
- [chat](https://docs.ishlabs.io/cli/generated/chat.md): Command reference: ish chat.
- [mcp, init](https://docs.ishlabs.io/cli/generated/mcp.md): Command reference: ish mcp, init.
- [source](https://docs.ishlabs.io/cli/generated/source.md): Command reference: ish source.
- [secret](https://docs.ishlabs.io/cli/generated/secret.md): Command reference: ish secret.
- [config](https://docs.ishlabs.io/cli/generated/config.md): Command reference: ish config.
- [docs](https://docs.ishlabs.io/cli/generated/docs.md): Command reference: ish docs.
- [check, setup](https://docs.ishlabs.io/cli/generated/check.md): Command reference: ish check, setup.
- [upgrade, feedback](https://docs.ishlabs.io/cli/generated/upgrade-feedback.md): Command reference: ish upgrade, feedback.
- [MCP overview](https://docs.ishlabs.io/mcp/overview.md): The ish MCP server: endpoint, transport, auth, and the shape of its tool and resource surface.
- [Connecting](https://docs.ishlabs.io/mcp/connecting.md): Wire the ish MCP server into your AI client and sign in over OAuth on first connect.
- [Tool conventions](https://docs.ishlabs.io/mcp/tool-conventions.md): The naming, polymorphism, safety-annotation, and id rules every ish MCP tool follows.
- [Authentication](https://docs.ishlabs.io/mcp/auth.md): How the ish MCP server authenticates clients, forwards tokens to the backend, and the OAuthProxy that makes loopback-port clients work.
- [Server instructions](https://docs.ishlabs.io/mcp/server-instructions.md): What the ish MCP server tells a connecting client in its instructions block, and how an agent should read it.
- [Errors](https://docs.ishlabs.io/mcp/errors.md): The bracketed error-code vocabulary every ish MCP tool failure starts with, and how to branch on it.
- [Long-running calls](https://docs.ishlabs.io/mcp/long-running-jobs.md): The wait and timeout contract, the next_action poll hint, and why the server delivers completion in the return value instead of pushing it.
- [Tool index](https://docs.ishlabs.io/mcp/generated/index.md): Every ish MCP tool, grouped by domain, with its annotation tier.
- [study tools](https://docs.ishlabs.io/mcp/generated/tools-study.md): MCP tool reference for the study domain.
- [ask tools](https://docs.ishlabs.io/mcp/generated/tools-ask.md): MCP tool reference for the ask domain.
- [person tools](https://docs.ishlabs.io/mcp/generated/tools-person.md): MCP tool reference for the person domain.
- [workspace tools](https://docs.ishlabs.io/mcp/generated/tools-workspace.md): MCP tool reference for the workspace domain.
- [chatbot tools](https://docs.ishlabs.io/mcp/generated/tools-chatbot.md): MCP tool reference for the chatbot domain.
- [participant tools](https://docs.ishlabs.io/mcp/generated/tools-participant.md): MCP tool reference for the participant domain.
- [site_access tools](https://docs.ishlabs.io/mcp/generated/tools-site-access.md): MCP tool reference for the site_access domain.
- [connect tools](https://docs.ishlabs.io/mcp/generated/tools-connect.md): MCP tool reference for the connect domain.
- [upload tools](https://docs.ishlabs.io/mcp/generated/tools-upload.md): MCP tool reference for the upload domain.
- [reference tools](https://docs.ishlabs.io/mcp/generated/tools-reference.md): MCP tool reference for the reference domain.
- [docs tools](https://docs.ishlabs.io/mcp/generated/tools-docs.md): MCP tool reference for the docs domain.
- [Resources](https://docs.ishlabs.io/mcp/generated/resources.md): Every ish:// MCP resource and URI template.
- [The ish API](https://docs.ishlabs.io/api/overview.md): Put a simulated person in the decision loop of your own environment and read how they react, turn by turn.
- [Quickstart](https://docs.ishlabs.io/api/quickstart.md): Create a session, run one turn of the loop, and read how the participant reacted.
- [Authentication](https://docs.ishlabs.io/api/authentication.md): Mint a workspace API key, send it as a bearer token, and scope and rotate it.
- [Sessions and turns](https://docs.ishlabs.io/api/concepts/sessions-and-turns.md): The server-side session model, the decision trace, pacing, and how a session ends.
- [Observations](https://docs.ishlabs.io/api/concepts/observations.md): Why the participant perceives only human-sensory renders, and why action labels must not leak hidden state.
- [The decide-only loop](https://docs.ishlabs.io/api/concepts/decide-only-loop.md): ish decides, you execute. Why the declared action set is the addressing scheme, and what that buys you.
- [Intent and resolution](https://docs.ishlabs.io/api/concepts/intent-and-resolution.md): The default intent mode, how a resolver maps intent to your actions, and how no_match becomes a finding.
- [People](https://docs.ishlabs.io/api/concepts/people.md): The pool of simulated people you can open a session for, and how ownership decides what you reach.
- [Run the session loop](https://docs.ishlabs.io/api/guides/session-loop.md): The complete integration contract: turn ordering, errors as observations, retries, pagination, and idempotency.
- [Author your environment](https://docs.ishlabs.io/api/guides/environment-authoring.md): Declare actions the participant can pick, write labels that do not leak, guide the resolver, and render frames that decode.
- [Score outcomes](https://docs.ishlabs.io/api/guides/scoring-outcomes.md): The participant's words are perception, not a verdict. Judge task success from your own environment's state.
- [Search people](https://docs.ishlabs.io/api/guides/people-search.md): Build a rule tree over person attributes: the grammar, the boolean semantics, and the limits.
- [API reference](https://docs.ishlabs.io/api/reference/introduction.md): The sessions, environments, versions, and tasks endpoints: base URL, authentication, conventions, and all 21 operations.
- [Errors](https://docs.ishlabs.io/api/errors.md): Every error kind the API returns, what each one means, and what to do about it.
- [Create Session](https://docs.ishlabs.io/api/reference/sessions/create-session.md): Open a session: one of your people, working toward one task, inside your environment.
- [List Sessions](https://docs.ishlabs.io/api/reference/sessions/list-sessions.md): List a workspace's sessions, newest first (keyset-paginated).
- [Submit Turn](https://docs.ishlabs.io/api/reference/sessions/submit-turn.md): Submit one observation + declared action set; get the person's choice.
- [Get Session](https://docs.ishlabs.io/api/reference/sessions/get-session.md): The full session state + a cursor page of the decision trace.
- [Close Session](https://docs.ishlabs.io/api/reference/sessions/close-session.md): Close an open session and return it (idempotent on an already-closed one).
- [Create Environment](https://docs.ishlabs.io/api/reference/environments/create-environment.md): Register an environment: a named target sessions can be opened against.
- [List Environments](https://docs.ishlabs.io/api/reference/environments/list-environments.md): Every LIVE environment registered in this workspace, oldest first.
- [Get Environment](https://docs.ishlabs.io/api/reference/environments/get-environment.md): One registered environment.
- [Update Environment](https://docs.ishlabs.io/api/reference/environments/update-environment.md): Partially update an environment. Omitted fields are untouched.
- [Delete Environment](https://docs.ishlabs.io/api/reference/environments/delete-environment.md): Retire an environment.
- [Create Environment Version](https://docs.ishlabs.io/api/reference/environments/create-environment-version.md): Author a declared variant of this environment.
- [List Environment Versions](https://docs.ishlabs.io/api/reference/environments/list-environment-versions.md): Every declared version of this environment, oldest first.
- [Get Environment Version](https://docs.ishlabs.io/api/reference/environments/get-environment-version.md): One declared variant. Archived versions stay individually readable.
- [Update Environment Version](https://docs.ishlabs.io/api/reference/environments/update-environment-version.md): Partially update a variant. Omitted fields are untouched.
- [Delete Environment Version](https://docs.ishlabs.io/api/reference/environments/delete-environment-version.md): Archive a variant.
- [Set Default Environment Version](https://docs.ishlabs.io/api/reference/environments/set-default-environment-version.md): Point this environment's default at this variant.
- [Create Task](https://docs.ishlabs.io/api/reference/tasks/create-task.md): Register a task: a named intent a session can bind by id.
- [List Tasks](https://docs.ishlabs.io/api/reference/tasks/list-tasks.md): List the workspace's registered tasks, oldest first.
- [Get Task](https://docs.ishlabs.io/api/reference/tasks/get-task.md): Fetch one task by id (archived rows stay readable).
- [Update Task](https://docs.ishlabs.io/api/reference/tasks/update-task.md): Partially update a task. Any applied write bumps `revision`.
- [Delete Task](https://docs.ishlabs.io/api/reference/tasks/delete-task.md): Retire a task.
- [List People](https://docs.ishlabs.io/api/reference/people/list-people.md): List the people you can open a session for, newest first.
- [Search People](https://docs.ishlabs.io/api/reference/people/search-people.md): Find people by their attributes, using a boolean rule tree.
- [Get Person](https://docs.ishlabs.io/api/reference/people/get-person.md): Fetch one person by id.
- [Get People Counts](https://docs.ishlabs.io/api/reference/people/get-people-counts.md): How many people this credential can reach, split by owner.
- [Get People Schema](https://docs.ishlabs.io/api/reference/people/get-people-schema.md): Every attribute a person can carry: its type, its values, how to filter it.
- [Versioning and deprecation](https://docs.ishlabs.io/api/versioning.md): How the API is versioned, what counts as a breaking change, what can change without one, and how a deprecation would be announced.
- [Changelog](https://docs.ishlabs.io/api/changelog.md): Every change to the ish API wire, newest first, with what each one asks you to change.
- [Troubleshooting](https://docs.ishlabs.io/help/troubleshooting.md): Symptom, cause, and fix for the failures you hit most with the ish CLI and MCP server (auth, tunnels, gated previews, and OAuth).
- [Error reference](https://docs.ishlabs.io/help/errors.md): Every error_code the ish CLI and MCP surface, what each means, and whether to retry.
- [Glossary](https://docs.ishlabs.io/help/glossary.md): One-line definitions of every ish term, each linking to the concept page that explains it in full.

## OpenAPI Specs

- [openapi.public](/api/openapi.public.json)

## Optional

- [GitHub](https://github.com/ishlabs)
- [ishlabs.io](https://ishlabs.io)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.