ish command. Pass them before or after the subcommand;
Commander merges program-level and subcommand-level options. Per-command flags are
documented on each command page.
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)
-h, --help prints usage for the current command and exits 0. -V, --version
prints the CLI version and exits 0.
Authentication
ish resolves a token from the first source that has one, in this order. The first
match wins; later sources are not consulted.
--token-file <path>
Read the token from a file (the file’s contents, trimmed). Preferred over
--token
and ISH_TOKEN because it keeps the token out of shell history and the process list.
An unreadable or empty file is a usage error.Saved OAuth session
The access and refresh tokens written by
ish login to ~/.ish/config.json.
A near-expiry access token is refreshed automatically; a permanently dead refresh
token is cleared so the next ish login starts clean.ish login, set
ISH_TOKEN, or pass --token / --token-file. See ish login
for the browser flow.
Workspace selection
--workspace <id> sets the default workspace for the run. It accepts a workspace alias
(w-...) or a UUID. A per-subcommand --workspace overrides the program-level one. When
no flag is given, ish resolves the active workspace from ISH_WORKSPACE, then from the
saved active workspace in the config file. See workspace for what a
workspace holds.
Output
ish prints a human-readable table by default and switches to JSON when stdout is not a
TTY (piped or redirected), so ish workspace list | jq works without --json.
| Flag | Effect |
|---|---|
--json | Force JSON output. |
--human | Force the human renderer even when stdout is piped. Overrides the JSON-when-piped auto-flip. |
--get <field> | Print only the value at a dotted path (e.g. --get id, --get items.0.alias). Implies --json internally. Suppresses progress on stderr. |
--fields <a,b,c> | Project JSON output to a comma-separated field set. A name not on the response prints a one-line stderr warning, not a silent drop. |
--verbose | Include full UUIDs and timestamps that lean JSON otherwise strips. |
--no-color | Disable ANSI color. Also honored: the NO_COLOR env var. Color is always off in JSON mode. |
-q, --quiet | Suppress progress messages on stderr. Defaults on under --get and when JSON was auto-selected by piping. |
--verbose returns the full payload; --fields and --get
take precedence over the strip, so a field you name explicitly always survives. Bracket
indexing works in --get paths (items[0].alias).
For the full output contract, see JSON mode.
Environment variables
| Variable | Effect |
|---|---|
ISH_TOKEN | Auth token, used when no --token / --token-file is passed. |
ISH_WORKSPACE | Default workspace, used when no --workspace is passed. |
ISH_HOME | Override the config root (default ~/.ish). Holds config.json, aliases.json, and cached binaries. |
NO_COLOR | Disable color (also honored: FORCE_COLOR). |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | General error (including billing 403: out of credits or usage limit). |
| 2 | Usage or validation error (bad flags, missing arguments). |
| 3 | Authentication failure (no or invalid token). |
| 4 | Not found (the workspace, study, or other entity does not exist). |
| 5 | Transient error, safe to retry. |
--json mode, errors carry a structured envelope: error, error_code, retryable, and often suggestions, error_kind, and an example invocation that fixes the call.