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
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)
-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.
1
--token <token>
An explicit token passed on the command line.
2
--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.3
ISH_TOKEN env var
The value of
ISH_TOKEN.4
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.5
Legacy saved token
A bare token persisted under
token in the config file (pre-OAuth installs).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.
JSON output is lean by default: UUID-valued fields, nulls, and timestamps are stripped to
keep agent context small.
--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
Exit codes
In
--json mode, errors carry a structured envelope: error, error_code, retryable, and often suggestions, error_kind, and an example invocation that fixes the call.