human(ish)

CLI reference

Every command, argument, and option in the Humanish CLI.

Reference for Humanish 0.83.0. Run npx humanish --version to check your installation, or npx humanish <command> --help for its exact flags.

Start with the quickstart. The examples below use the installed humanish binary; prefix them with npx from your project if it is not on your PATH.

--json returns machine-readable responses where supported. tui requires a human terminal and refuses detected agent sessions, including agents with a TTY. See TUI refusals and read-only JSON alternatives.

humanish

humanish [options] [command]
OptionDescription
-V, --versionoutput the version number
--jsonPrint machine-readable JSON responses where supported.
-h, --helpdisplay help for command

humanish init

Set up committed humanish/ source files and ignored .humanish/ runtime state.

humanish init [options]
OptionDescription
--dry-runPrint planned changes without writing files.
--yesApply safe generated changes without prompting.
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish doctor

Explain project readiness and missing Humanish setup.

humanish doctor [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish tui

Open the interactive terminal surface for browsing labs and runs (humans only).

humanish tui [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--forceOpen it anyway in a session that looks like an agent's.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish telemetry

Show or change anonymous usage collection.

humanish telemetry [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish telemetry status

What is collected, and whether it is on.

humanish telemetry status [options]
OptionDescription
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish telemetry enable

Turn anonymous usage collection on.

humanish telemetry enable [options]
OptionDescription
-h, --helpdisplay help for command

humanish telemetry disable

Turn anonymous usage collection off.

humanish telemetry disable [options]
OptionDescription
-h, --helpdisplay help for command

humanish keys

Manage the humanish user-level key store used by provider-key discovery (#436).

humanish keys [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish keys set

Store one provider key in the user store (0600), prompted with hidden input.

humanish keys set [options] <vendor-or-name>
ArgumentDescription
vendor-or-nameA vendor alias (openai, e2b, anthropic, github) or a raw ENV_NAME.
OptionDescription
--stdinRead the value from stdin instead of prompting (for agents/pipes).
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish keys unset

Remove one key from the user store.

humanish keys unset [options] <vendor-or-name>
ArgumentDescription
vendor-or-nameA vendor alias or raw ENV_NAME to remove from the store.
OptionDescription
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish keys list

List the NAMES stored in the user store. Values are never printed.

humanish keys list [options]
OptionDescription
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish run

Run a lab (or a synthetic dry-run bundle). The everyday command.

humanish run [options] [lab]
ArgumentDescription
labOptional lab id or .yaml path.
OptionDescription
--dry-runGenerate contract proof without browser, keys, or provider spend.
--openOpen the observer in the default browser.
--no-openRender without opening a browser.
--detachRender/open once and exit without an attached watch server.
--port <port>Local observer server port when following. (default: "0")
--app-url <url>Capture live desktop/mobile browser evidence against a running loopback app URL.
--actor <actor>Explicit live actor to run. (choices: "codex-tui", "codex-exec", "codex-app-server")
--sims <count>Simulation count. Codex exec runs requested lanes with bounded concurrency; Codex TUI supports 1.
--timeout-ms <ms>Local actor timeout in milliseconds. (default: "900000")
--cwd <path>Target project directory. (default: ".")
--env-file <path>Load a local env file for this run without persisting values.
--run-id <id>Explicit run id for deterministic fixture tests.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish verify

Validate a run bundle and public-safety gates.

humanish verify [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish cleanup

Inspect recorded resource evidence and write cleanup.json; stored ids do not authorize provider mutation.

humanish cleanup [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish review

Build a review packet from verified run evidence.

humanish review [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish runs

List local Humanish runs and latest pointers.

humanish runs [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish stats

Cost, outcome, and duration roll-ups across run history (#472). Estimates stay labelled; unknown costs count as unknown.

humanish stats [options]
OptionDescription
--lab <id>Only runs from this lab id.
--since <date>Only runs that started on or after this ISO date or datetime.
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish export

Write one self-contained .html of a run's Observer with screenshots inlined (#471). Verify and the share_ready gate run inside; a local_only bundle exports only with --local-only, watermarked.

humanish export [options]
OptionDescription
--run <id>Run id or 'latest'. (default: "latest")
--out <path>Where to write the file. Defaults to .humanish/exports/<runId>.html.
--local-onlyExport a bundle that is not share_ready, with a LOCAL ONLY banner in the file.
--max-bytes <n>Refuse an export larger than this. (default: "26214400")
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish comms

Off-app comms surfaces (email/SMS the app under test sends).

humanish comms [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish comms catch

Run the email catch on THIS host so humanish can study an app it does not provision (#328). Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.

humanish comms catch [options]
OptionDescription
--port <port>Port for capture + inbox (default 8025). (default: "8025")
--dir <path>Directory for the deliveries log and rendered inbox. (default: ".humanish/comms-catch")
--token <value>Require this bearer token on GET /deliveries (recommended when reachable off-host).
--inbox-port <port>Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.
--recipient <address>Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.
-h, --helpdisplay help for command

humanish reclaim

Kill an interrupted run's sandboxes by their journaled exact ids (the #358 salvage path — reads the run's sandbox-receipts.ndjson; never enumerates the E2B account). Needs E2B_API_KEY in the environment.

humanish reclaim [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--run <id>Run id, or 'latest'. (default: "latest")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish watch

Run sims, open the observer, and keep the shell attached.

humanish watch [options] [lab]
ArgumentDescription
labOptional lab id or .yaml path to run and observe.
OptionDescription
--lab <id-or-path>Explicit lab id or .yaml path.
--run <id>Watch an existing run id or latest pointer.
--dry-runLab only: render contract evidence without live provider spend.
--codex-app-serverLab only: use Codex app-server client mode for OSS headed desktops.
--sims <count>Start a fresh synthetic run with this many sims before rendering. Defaults to 4 when --run is omitted.
--count <count>Lab only: override headed desktop lane count.
--limit <count>Lab only: override smoke lab repo limit.
--repo <owner/repo>Lab only: GitHub repo slug. Repeatable. (default: [])
--repos <owner/repo,...>Lab only: comma-separated GitHub repo slugs.
--redact-reposLab only: redact repo labels in durable artifacts.
--no-redact-reposLab only: persist repo labels. Use only for public-safe runs.
--keepLab only: keep disposable clone sandbox for debugging.
--scorer <path>Terminal/computer-use/shared-world labs only: repo-relative adopter scorer module (.mjs). Overrides review.scorer.ref. Executable code — review it as code.
--run-id <id>Explicit run id for deterministic fixture tests.
--cwd <path>Target project directory. (default: ".")
--env-file <path>Load a local env file for this watch without persisting values.
--openOpen the observer in the default browser.
--no-openRender without opening a browser.
--detachRender/open once and exit without attached watch server.
--port <port>Local observer server port when following. (default: "0")
--exposeCUA lab only: expose the live run through an authenticated edge so you can watch from a phone. Requires edge auth.
--tunnel <provider>Spawn the external tunnel binary against the loopback port. (choices: "ngrok")
--tunnel-domain <domain>Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.
--oauth <provider>Turn on ngrok edge OAuth. Requires --tunnel. (choices: "google")
--allow-email <addr>Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth. (default: [])
--allow-domain <domain>Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth. (default: [])
--public-url <origin>Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.
--safeNot applicable to watch: a live run is never share_ready, so --safe (a serve library filter) is rejected here. Restrict viewers with edge auth (--allow-email/--allow-domain).
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish observe

Serve a finished run's Observer over loopback http://127.0.0.1 instead of a file:// path.

humanish observe [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--port <port>Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port. (default: "0")
--cwd <path>Target project directory. (default: ".")
--openOpen the observer in the default browser.
--no-openServe without opening a browser.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish serve

Serve the local run library over loopback http, with optional tunnel-edge authenticated exposure.

humanish serve [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--port <port>Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port. (default: "0")
--run <id>Land on this run id (or latest) instead of the library index.
--safeServe only runs whose verify shareSafety is share_ready; everything else is absent (fail-closed).
--exposeDeclare exposure intent. Requires edge auth (--oauth or --public-url) OR --safe.
--tunnel <provider>Spawn the external tunnel binary against the loopback port. (choices: "ngrok")
--tunnel-domain <domain>Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.
--oauth <provider>Turn on ngrok edge OAuth. Requires --tunnel. (choices: "google")
--allow-email <addr>Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth. (default: [])
--allow-domain <domain>Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth. (default: [])
--public-url <origin>Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.
--openOpen the library in the default browser.
--no-openServe without opening a browser.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish codex

Run Codex-native Humanish integration surfaces.

humanish codex [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish codex app-server

Run a browser-visible Codex app-server actor surface and write redacted protocol artifacts.

humanish codex app-server [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--prompt <text>Prompt to submit to Codex app-server.
--prompt-file <path>Read the Codex app-server prompt from a file.
--run-root <path>Artifact directory for redacted app-server evidence.
--state-file <path>State JSON file for external observers.
--timeout-ms <ms>Actor timeout in milliseconds. (default: "900000")
--port <port>Local browser UI port. (default: "0")
--model <model>Optional Codex model override.
--sandbox <mode>Turn sandbox policy. (choices: "read-only", "workspace-write", "danger-full-access", default: "read-only")
--actor-command <command>Override app-server command. Defaults to codex app-server --listen stdio://.
--keep-openKeep the browser UI process alive after the actor finishes.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab

List, inspect, and run Humanish lab manifests.

humanish lab [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish lab list

List committed and ignored Humanish lab manifests.

humanish lab list [options]
OptionDescription
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab inspect

Inspect a Humanish lab manifest without running it.

humanish lab inspect [options] <lab>
ArgumentDescription
labLab id or .yaml path.
OptionDescription
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab preflight

Check a lab manifest and optional target reachability before actor/model spend.

humanish lab preflight [options] <lab>
ArgumentDescription
labLab id or .yaml path.
OptionDescription
--cwd <path>Target project directory. (default: ".")
--reachability <mode>Reachability mode. (choices: "metadata", "public-preview", "sandbox-loopback", "prepared-host", default: "metadata")
--timeout-ms <ms>Target reachability timeout. (default: "30000")
--env-file <path>Load a local env file for this preflight without persisting values.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab cleanup

Sweep stale provider resources from a crashed prior process, by provider metadata, without printing provider ids. humanish never enumerates an account by default: set HUMANISH_OSS_META_ALLOW_PROVIDER_LIST=1 to opt in for this maintainer-only sweep.

humanish lab cleanup [options] [lab]
ArgumentDescription
labProvider-backed lab to clean up. (default: "oss")
OptionDescription
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab run

Run a Humanish lab manifest. Same as humanish run &lt;lab&gt;, grouped under lab.

humanish lab run [options] <lab>
ArgumentDescription
labLab id or .yaml path.
OptionDescription
--env-file <path>Load a local env file for this lab without persisting values.
--dry-runRender contract evidence without live provider spend. The bundled OSS lab defaults to this mode.
--codex-app-serverMeta only: use Codex app-server client mode for headed desktop actor surfaces.
--openOpen the observer in the default browser.
--no-openRender without opening a browser.
--detachRender/open once and exit without attached watch server.
--port <port>Local observer server port when following. (default: "0")
--sims <count>Override synthetic sims or headed desktop lanes.
--count <count>CUA/meta only: override headed desktop lane count.
--rerun-failed-from <run>CUA fan-out only: create a new run for failed lanes from a prior run.
--lanes <lane-ids>CUA rerun only: comma-separated lane ids to rerun from the source run.
--limit <count>Smoke labs only: override repo limit.
--run-id <id>Explicit lab run id.
--cwd <path>Target project directory. (default: ".")
--repo <owner/repo>Smoke/meta only: GitHub repo slug. Repeatable. (default: [])
--repos <owner/repo,...>Smoke/meta only: comma-separated GitHub repo slugs.
--redact-reposMeta only: redact repo labels in durable lab artifacts.
--no-redact-reposMeta only: persist repo labels in durable lab artifacts. Use only for public-safe runs.
--keepSmoke labs only: keep disposable clone sandbox for debugging.
--scorer <path>Terminal/computer-use/shared-world labs only: repo-relative adopter scorer module (.mjs). Overrides review.scorer.ref. Executable code — review it as code.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab oss

Alias: run the bundled OSS meta-lab dry-run contract.

humanish lab oss [options]
OptionDescription
--env-file <path>Load a local env file for this lab without persisting values.
--repos <owner/repo,...>Comma-separated GitHub repo slugs.
--repo <owner/repo>GitHub repo slug. Repeatable. (default: [])
--count <count>Number of contract lanes to assign. (default: "4")
--sims <count>Alias for --count.
--run-id <id>Explicit lab run id.
--cwd <path>Host directory for ignored .humanish lab report. (default: ".")
--dry-runRender the Observer-of-Observers contract without provider spend or live E2B launch (default).
--openOpen the observer in the default browser.
--no-openRender without opening a browser.
--detachRender/open once and exit without attached watch server.
--redact-reposRedact repo labels in durable lab artifacts.
--no-redact-reposPersist repo labels in durable lab artifacts. Defaults to redacted when a GitHub token is present.
--port <port>Local observer server port when following. (default: "0")
--smokeRun the disposable local clone smoke harness instead of headed meta-sims.
--limit <count>Smoke mode only: number of selected repos to trial. (default: "4")
--keepSmoke mode only: keep disposable clone sandbox for debugging.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish lab oss-smoke

Clone lightweight public OSS repos, try Humanish setup/proof, then discard clones.

humanish lab oss-smoke [options]
OptionDescription
--repos <owner/repo,...>Comma-separated public GitHub repo slugs.
--repo <owner/repo>Public GitHub repo slug. Repeatable. (default: [])
--limit <count>Number of selected repos to trial. (default: "4")
--run-id <id>Explicit lab run id.
--cwd <path>Host directory for ignored .humanish lab report. (default: ".")
--keepKeep disposable clone sandbox for debugging.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish feedback

Create public-safe feedback drafts without GitHub API mutation.

humanish feedback [options] [command]
OptionDescription
-h, --helpdisplay help for command

humanish feedback list

List feedback draft state for a run.

humanish feedback list [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish feedback draft

Generate a public-safe feedback draft from verified evidence.

humanish feedback draft [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--candidate <id>Which finding to draft (ids from feedback list); default: the first.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish feedback verify

Verify the feedback draft for public issue eligibility.

humanish feedback verify [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--candidate <id>Which finding to verify (ids from feedback list); default: the first.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish feedback issue

Print Markdown for a public GitHub issue. Does not mutate GitHub.

humanish feedback issue [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--repo <owner/repo>Repository slug used in rendered filing instructions.
--format <format>Output format. (default: "markdown")
--candidate <id>Which finding to file (ids from feedback list); default: the first.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command

humanish feedback issue-url

Print a prefilled public issue URL. Does not mutate GitHub.

humanish feedback issue-url [options]
OptionDescription
--run <id>Run id or latest pointer. (default: "latest")
--cwd <path>Target project directory. (default: ".")
--repo <owner/repo>Repository slug used in the generated URL.
--candidate <id>Which finding to link (ids from feedback list); default: the first.
--jsonPrint a machine-readable JSON response.
-h, --helpdisplay help for command
Edit this page on GitHub

Observer and terminal

Browse studies as a person, read results through JSON as an agent, or serve the run library.

On this page

humanishhumanish inithumanish doctorhumanish tuihumanish telemetryhumanish telemetry statushumanish telemetry enablehumanish telemetry disablehumanish keyshumanish keys sethumanish keys unsethumanish keys listhumanish runhumanish verifyhumanish cleanuphumanish reviewhumanish runshumanish statshumanish exporthumanish commshumanish comms catchhumanish reclaimhumanish watchhumanish observehumanish servehumanish codexhumanish codex app-serverhumanish labhumanish lab listhumanish lab inspecthumanish lab preflighthumanish lab cleanuphumanish lab runhumanish lab osshumanish lab oss-smokehumanish feedbackhumanish feedback listhumanish feedback drafthumanish feedback verifyhumanish feedback issuehumanish feedback issue-url