CLI overview

The ish CLI (@ishlabs/cli, binary ish) drives ish from a terminal or a local coding agent. It is the local surface for ish: it runs on your machine, so it is the choice for local development and the only way to test a web, iOS, or Android app running on your own machine (the hosted MCP server can’t reach your machine). If you’d rather drive ish from an agent without local access, use the MCP server instead — you don’t need both. See the CLI and the MCP server for the full comparison. It ships as a single standalone binary (from the install script or Homebrew) or as a global npm package. Both expose the same commands. Install it with one line:

curl -fsSL https://ishlabs.io/install.sh | sh

Then sign in, point a study at a URL, and read what one simulated person noticed:

ish login
ish study create --name "Landing page" --modality interactive --url https://example.com \
  --assignment "First look:Decide if you would keep reading" \
  --question "What stood out, and what was confusing?"
ish study run --sample 1 -y --wait
ish study results --summary

The run prints progress on stderr, then the reported journey. Output looks like this (representative):

Representative output

✓ study created  s-b2c  "Landing page"
✓ run dispatched  1 person  ...done
Sentiment   positive
Noticed     The headline framed the value before the form.
Stuck       Pricing was two scrolls down; expected it above the fold.
Next        Would click "See plans" if it were visible sooner.

What you can do from the CLI:

Create studies across modalities (interactive, text, video, audio, image, document, chat) and run them with ish study.
Draw and inspect a simulated audience with ish person.
Compare variants fast with ish ask, without a full study run.
Read back the reported journey and slice it with ish study results.
Expose a localhost build to simulated people with ish connect.
Share a result as a public link and script the whole flow in CI.

For a guided first run, see the quickstart. For the full per-command flag tables, see the command index. Global flags, the auth token resolution order, and exit codes live on the global flags page.

Install

Pick one method. The install script and Homebrew give you a self-contained binary; the install-script binary self-updates with ish upgrade, Homebrew updates with brew upgrade ish. npm gives you the same CLI as a global package managed by npm.

curl -fsSL https://ishlabs.io/install.sh | sh

irm https://ishlabs.io/install.ps1 | iex

brew install ishlabs/tap/ish

npm install -g @ishlabs/cli

Confirm the install:

ish --version

Method comparison

Method	Command	Self-update	Platforms
Install script	`curl -fsSL https://ishlabs.io/install.sh \| sh`	`ish upgrade`	macOS, Linux
PowerShell script	`irm https://ishlabs.io/install.ps1 \| iex`	`ish upgrade`	Windows
Homebrew	`brew install ishlabs/tap/ish`	`brew upgrade ish`	macOS, Linux
npm	`npm install -g @ishlabs/cli`	`npm install -g @ishlabs/cli@latest`	Any with Node 18+

Supported targets

The standalone binary is built per platform and architecture. The install scripts detect your platform and download the matching binary.

Platform	Architectures
macOS (`darwin`)	`arm64`, `x64`
Linux	`arm64`, `x64`
Windows	`x64`

The npm package requires Node 18 or newer (engines.node is >=18.0.0). Homebrew installs node as its only dependency; cloudflared (for ish connect) is fetched by the CLI at runtime, not declared by the formula.

Install location and PATH

The install script writes the binary to ~/.ish/bin/ish and appends a PATH line to your shell profile (.zshrc, .bashrc / .bash_profile, or config.fish). If ish is not found after install, open a new terminal or source your profile.

env var

Override the install directory. Defaults to ~/.ish/bin (%USERPROFILE%\.ish\bin on Windows).

env var

Set to 1 to skip the shell-profile PATH edit (for ephemeral or sandbox installs). You then add the install directory to PATH yourself.

env var

Override where the CLI reads and writes session state (config.json, aliases.json). Defaults to ~/.ish.

cloudflared is not bundled and is not a formula dependency. The first ish connect downloads it for your platform if it is not already on your PATH; if that download fails, install it yourself (brew install cloudflare/cloudflare/cloudflared, winget install Cloudflare.cloudflared).

Upgrade

ish upgrade

ish upgrade downloads the latest standalone binary from https://ishlabs.io/api/releases/ and atomically replaces the running executable (typically ~/.ish/bin/ish). The download is TLS-verified. When you are already on the latest version it is a no-op. Pin a specific release with --release (note: --version is the global flag that prints the CLI version, not an upgrade target):

ish upgrade --release 0.28.2

ish upgrade only updates a standalone binary install (install script or Homebrew). On an npm install it refuses with a usage error (exit code 2) rather than overwriting the node binary. Update those installs with their package manager instead.

Install method	How to update
Install script	`ish upgrade`
Homebrew	`brew upgrade ish`
npm	`npm install -g @ishlabs/cli@latest`

See ish upgrade for the full reference.

Command index

Every command takes the same global flags (--json, --token, --workspace, and more). The command index is the complete table with subcommands; the groups below orient you.

Session and connection

Auth and session

ish login, ish logout, ish status (alias whoami). Sign in, sign out, and show the active session.

Local tunnel

ish connect, ish disconnect. Expose a localhost service so a simulated person can reach it.

Studies and runs

Studies

ish study plus create, run, results, analyze, share, and more. Shape a study and read what people reported back.

Iterations

ish iteration. Manage the run-time configurations of a study (the URL, media, or chatbot endpoint each run uses).

Asks

ish ask. Quick variant comparisons: pose questions to people and read their answers.

Chat studies

ish chat. Author chatbot endpoints and run chat-modality studies.

People and inputs

People

ish person. Manage, generate, and inspect the simulated people in a workspace.

Sources

ish source. Upload and inspect attachments (transcripts, audio, images) used as generation inputs.

Workspaces

ish workspace. Create, list, and switch the workspace your commands act on.

Secrets and configs

ish config and ish secret. Manage simulation configs and workspace secrets.

Setup and agents

Agent skill and MCP

ish init installs the ish agent skill into a project; ish mcp wires the ish MCP server into Cursor, VS Code, Claude Code, Claude Desktop, and Windsurf.

Offline docs

ish docs. The mental model, concept pages, and search, available from the CLI for agents.

Local setup check

ish check and ish setup. Verify and install local-simulation dependencies (Chromium, the iOS runner, adb).

Upgrade and feedback

ish upgrade keeps the CLI current; ish feedback reports a bug or sends a note to the ish team.

Overview

Commands

CLI overview

Install

Method comparison

Supported targets

Install location and PATH

Upgrade

Command index

Session and connection

Auth and session

Local tunnel

Studies and runs

Studies

Iterations

Asks

Chat studies

People and inputs

People

Sources

Workspaces

Secrets and configs

Setup and agents

Agent skill and MCP

Offline docs

Local setup check

Upgrade and feedback

​Install

​Method comparison

​Supported targets

​Install location and PATH

​Upgrade

​Command index

​Session and connection

Auth and session

Local tunnel

​Studies and runs

Studies

Iterations

Asks

Chat studies

​People and inputs

People

Sources

Workspaces

Secrets and configs

​Setup and agents

Agent skill and MCP

Offline docs

Local setup check

Upgrade and feedback

Install

Method comparison

Supported targets

Install location and PATH

Upgrade

Command index

Session and connection

Studies and runs

People and inputs

Setup and agents