CLI reference
Every command, argument, and option in the humanish CLI.
Reference for humanish 0.154.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]| Option | Description |
|---|---|
-v, --version | Print the version. |
--json | Print machine-readable JSON responses where supported. |
-h, --help | Show help for this command. |
- humanish init: Set up starter studies and personas in this project.
- humanish doctor: Check what this project and machine need for a run.
- humanish run: Run a study, as a dry run or with live participants.
- humanish watch: Run a study and follow it in the Observer.
- humanish observe: Open a saved run in the Observer.
- humanish verify: Check a run's evidence and share safety.
- humanish review: Show a run's outcome and analysis findings.
- humanish analyze: Analyze a live run into evidence-linked findings.
- humanish notes: List or add reviewer notes on a run.
- humanish feedback: Draft public-safe feedback issues from a run.
- humanish export: Export a run as an Observer page or redacted bundle.
- humanish runs: List this project's runs and which one is latest.
- humanish stats: Show cost, outcomes and durations across runs.
- humanish study: List, show and check studies in humanish/studies/.
- humanish migrate: Convert v2 study files to v3.
- humanish comms: Catch the email an app sends, for email-gated flows.
- humanish runtime: Prepare or inspect the local browser runtime.
- humanish reclaim: Stop or check an interrupted run's sandboxes.
- humanish keys: Check and store your provider keys.
- humanish telemetry: Show or change anonymous usage collection.
- humanish tui: Browse studies and runs in a terminal UI for people.
humanish init
Set up committed humanish/ source files and ignored .humanish/ runtime state.
humanish init [options]| Option | Description |
|---|---|
--dry-run | Print planned changes without writing files. |
--yes | Apply safe generated changes without prompting. |
--local-browser <url> | Set the local-browser starter to this loopback app URL (explicit port above 1023). |
--local-mission <text> | Set the local-browser participant mission. |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish doctor
Explain project readiness and missing humanish setup.
humanish doctor [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--study <study> | Check the study's desktop, participant authentication and separate analysis requirements; no provider calls. |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish run
Run a study, as a dry run or with live participants. This is the everyday command.
humanish run [options] [study]| Argument | Description |
|---|---|
study | Optional study id or .yaml path. |
| Option | Description |
|---|---|
--dry-run | Do a dry run: a synthetic run with no browser, keys or provider spend. |
--open | Open the Observer in the default browser. |
--no-open | Render without opening a browser. |
--detach | Render/open once and exit without an attached watch server. |
--port <port> | Port to listen on at 127.0.0.1. (default: a free port) |
--count <count> | Override the participant count of a preview or computer-use study, or of the synthetic run without a study. |
--rerun-failed-from <run> | Computer-use studies only: start a new run for the failed participants of a prior run. |
--participants <ids> | With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position. |
--scorer <path> | Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only. |
--cwd <path> | Project directory. (default: ".") |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--run-id <id> | Explicit run id for deterministic fixture tests; refused when that run already exists. |
--remote | Require a remote run: the study's own process runs in a sandbox on its participants' provider, so it keeps going when this machine sleeps. A study that can is run this way by default; this refuses one that cannot, with the reason. |
--local | Run the study on this machine even when it could run remotely. It then stops if this machine sleeps. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish watch
Run a study, open its Observer and keep the shell attached.
humanish watch [options] [study]| Argument | Description |
|---|---|
study | Study id or .yaml path to run and observe. |
| Option | Description |
|---|---|
--study <id-or-path> | Study id or .yaml path, in place of the argument. |
--dry-run | Do a dry run: a synthetic run with no browser, keys or provider spend. |
--open | Open the Observer in the default browser. |
--no-open | Render without opening a browser. |
--detach | Render/open once and exit without an attached watch server. |
--port <port> | Port to listen on at 127.0.0.1. (default: a free port) |
--count <count> | Override the participant count of a preview or computer-use study, or of the synthetic run without a study. |
--rerun-failed-from <run> | Computer-use studies only: start a new run for the failed participants of a prior run. |
--participants <ids> | With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position. |
--scorer <path> | Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only. |
--cwd <path> | Project directory. (default: ".") |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--run-id <id> | Explicit run id for deterministic fixture tests; refused when that run already exists. |
--remote | Require a remote run: the study's own process runs in a sandbox on its participants' provider, so it keeps going when this machine sleeps. A study that can is run this way by default; this refuses one that cannot, with the reason. |
--local | Run the study on this machine even when it could run remotely. It then stops if this machine sleeps. |
--json | Print a machine-readable JSON response. |
--expose | Computer-use studies only: share the live run through an authenticated tunnel, to watch from a phone. Requires --oauth or --public-url. |
--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. |
--allow-domain <domain> | Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth. |
--public-url <origin> | Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose. |
--serve | Serve the Observer and stay attached until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the result and an exit. |
-h, --help | Show help for this command. |
humanish observe
Open a saved run in the Observer, served on http://127.0.0.1; without --run, the latest. With --all, serve the run library, opening on --run when given.
humanish observe [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. |
--all | Serve the whole run library, with optional tunnel-edge exposure. |
--port <port> | Port to listen on at 127.0.0.1. (default: a free port) |
--cwd <path> | Project directory. (default: ".") |
--open | Open the Observer in the default browser. |
--no-open | Serve without opening a browser. |
--serve | Serve one run until Ctrl-C even without an interactive terminal; by default an agent's shell or a pipe gets the Observer path and an exit. |
--json | Print a machine-readable JSON response. |
--safe | Serve only runs whose verify shareSafety is share_ready; other runs are not served at all. |
--expose | Share the library beyond this machine. Requires --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. |
--allow-domain <domain> | Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth. |
--public-url <origin> | Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding. |
-h, --help | Show help for this command. |
humanish verify
Check a run's evidence and share safety.
humanish verify [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--verbose | Print every check, passing ones included. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish review
Show a run's review: verdict, summary, gaps and the findings of its analysis, with the evidence each one cites.
humanish review [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish analyze
Analyze retained participant evidence into versioned findings. Selected text and captures go to the chosen remote analyst. Opening Observer never starts analysis.
humanish analyze [options] [command]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--provider <name> | Analyst: openai (default), gemini (sends the evidence and captures to Google), or restricted codex account. No provider fallback. |
--max-cost <usd> | Required for OpenAI and Gemini, also with --dry-run: an analysis is refused before it sends anything if both its worst case and its expected cost plus a 10% margin are over this. It does not limit billing. Unsupported for Codex. |
--model <id> | OpenAI analysis model: gpt-6-astra, gpt-6.1-sol, gpt-6-luna, gpt-5.5, gpt-5.6, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna; gpt-6.1-sol at medium effort when omitted. Gemini analysis model: gemini-3.8-flash; gemini-3.8-flash when omitted. Codex account analysis runs gpt-6-astra at low effort. |
--reasoning-effort <level> | OpenAI reasoning.effort or Gemini thinking level, from none, minimal, low, medium, high, xhigh and max; each model takes only the levels its provider documents for it, and others are refused before any request. When omitted: medium for the default OpenAI analyst, high with --model or --provider gemini. Unsupported for Codex. |
--question <text> | Additional reviewer question; does not change participant instructions. |
--timeout-ms <ms> | Request timeout, at most 600000 ms. (default: "600000") |
--max-output-tokens <n> | OpenAI or Gemini response-token limit including reasoning, 256–32768. Omit for a limit sized to the participants and effort. Unsupported for Codex. |
--dry-run | Capture and validate local input and estimate admission; no request or analysis artifact. |
--rerun | Create a new immutable version even when the same input and configuration were analyzed. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish analyze list
List immutable analysis versions, including failed attempts.
humanish analyze list [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish analyze show
Print a run's analysis findings with the evidence each one cites. --json prints the validated analysis record and its correction history. Defaults to the latest usable version.
humanish analyze show [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--id <id> | Exact analysis version. |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish analyze correct
Append a human review note bound to one exact finding version; original claims remain intact.
humanish analyze correct [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--analysis <id> | Analysis version to review. |
--finding <id> | Finding to review. |
--status <status> | Review disposition. (choices: "confirmed", "dismissed", "amended") |
--reason <text> | Why this disposition is supported. |
--claim <text> | Replacement claim, required only for amended findings. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish notes
List the reviewer notes on a run, or add one at a moment of its recording. A note's time counts from the run's first timed capture, as the Observer's study timeline shows it.
humanish notes [options] <run> [text...]| Argument | Description |
|---|---|
run | Run id, or latest. |
| Option | Description |
|---|---|
--add | Add a note. Its text is the words after the run; --at gives the moment. |
--at <mm:ss> | With --add: the moment, in minutes and seconds, such as 02:31. |
--participant <id> | With --add: the participant's id from the study, or its stream id. Leave it out for a note on the whole run. |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish feedback
Draft public-safe feedback issues from a run. humanish never calls the GitHub API.
humanish feedback [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish feedback list
List recorded feedback candidates and any saved draft.
humanish feedback list [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish feedback draft
Generate a public-safe feedback draft from verified evidence.
humanish feedback draft [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--analysis <id> | Independent analysis version; use with --finding. |
--finding <id> | Finding within --analysis, separate from participant candidates. |
--candidate <id> | Which finding to draft (ids from feedback list); default: the first. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish feedback verify
Verify the feedback draft for public issue eligibility.
humanish feedback verify [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--analysis <id> | Independent analysis version; use with --finding. |
--finding <id> | Finding within --analysis, separate from participant candidates. |
--candidate <id> | Which finding to verify (ids from feedback list); default: the first. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish feedback issue
Print Markdown for a public GitHub issue. Does not mutate GitHub.
humanish feedback issue [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--repo <owner/repo> | Repository slug used in rendered filing instructions. |
--format <format> | Output format. (default: "markdown") |
--analysis <id> | Independent analysis version; use with --finding. |
--finding <id> | Finding within --analysis, separate from participant candidates. |
--candidate <id> | Which finding to file (ids from feedback list); default: the first. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish feedback issue-url
Print a prefilled public issue URL. Does not mutate GitHub.
humanish feedback issue-url [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--cwd <path> | Project directory. (default: ".") |
--repo <owner/repo> | Repository slug used in the generated URL. |
--analysis <id> | Independent analysis version; use with --finding. |
--finding <id> | Finding within --analysis, separate from participant candidates. |
--candidate <id> | Which finding to link (ids from feedback list); default: the first. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish export
Export a run as self-contained Observer HTML, or a separately verified redacted bundle workspace. HTML requires share_ready unless --local-only; bundle format requires --redact-screenshots and preserves the original.
humanish export [options]| Option | Description |
|---|---|
--run <id> | Run id, or latest. (default: "latest") |
--format <format> | Output format; bundle creates a new standalone workspace. (choices: "html", "bundle", default: "html") |
--redact-screenshots | Bundle only: blur PNG screenshots in a verified copy; keep original evidence unchanged. |
--out <path> | HTML file or new bundle workspace. Default: .humanish/exports/<runId>.html or <runId>-redacted/. |
--local-only | Export a bundle that is not share_ready, with a "Local only" banner in the file. |
--max-bytes <n> | Refuse an export larger than this many bytes. (default: 25 MB) |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish runs
List this project's runs and which one is latest.
humanish runs [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish stats
Cost, outcome, and duration roll-ups across run history. Estimates stay labelled; unknown costs count as unknown.
humanish stats [options]| Option | Description |
|---|---|
--study <id> | Only runs of this study id. |
--since <date> | Only runs that started on or after this ISO date or datetime. |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish study
List, show and check studies in humanish/studies/.
humanish study [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish study list
List the studies in this project, committed and local.
humanish study list [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish study show
Show a study's parsed file and its warnings without running it.
humanish study show [options] <study>| Argument | Description |
|---|---|
study | Study id or .yaml path. |
| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish study check
Check the study file and, with --reachability, its named endpoints. humanish doctor --study <study> checks this machine.
humanish study check [options] <study>| Argument | Description |
|---|---|
study | Study id or .yaml path. |
| Option | Description |
|---|---|
--cwd <path> | 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") |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish migrate
Convert humanish.lab.v2 study files to humanish.study.v3. A file under a labs/ directory moves to the matching studies/ directory; any other file is rewritten in place. An original that a failure leaves out of place is kept as <name>.v2.bak. Pass the files to convert; without any, the six study directories are scanned. Every destination, moved key and dropped key is printed before anything is written. A file that changes during the run is kept and listed.
humanish migrate [options] [path...]| Option | Description |
|---|---|
--dry-run | Print what would change and write nothing. |
--cwd <path> | Project directory. (default: ".") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms
Local email capture, real receiving connections, checks and cleanup recovery.
humanish comms [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish comms providers
List installed communication provider capabilities. No network requests.
humanish comms providers [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms connections
Manage project-local non-secret connection profiles. A study explicitly selects its receiving connection.
humanish comms connections [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish comms connections list
Show saved connections and local credential status; does not authenticate with a provider.
humanish comms connections list [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms connections add
Save an AgentMail connection profile. Does not write a key, alter a study or contact the provider.
humanish comms connections add [options] [name]| Argument | Description |
|---|---|
name | Project connection name. (default: "agentmail") |
| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--provider <id> | Installed provider id. (default: "agentmail") |
--api-key-env <name> | The name of an environment variable, never its value. (default: "AGENTMAIL_API_KEY") |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms check
Check connection and credential presence; --online authenticates without creating inboxes.
humanish comms check [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--connection <name> | Saved connection name. (default: "agentmail") |
--study <path> | Check the connection this study selects. |
--online | Make a read-only provider authentication request. |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms configure
Preview or save a local receiving-enabled copy of a supported study. No provider requests.
humanish comms configure [options]| Option | Description |
|---|---|
--study <path> | Source study path or name. Required. |
--cwd <path> | Project directory. (default: ".") |
--connection <name> | Saved connection name. (default: "agentmail") |
--apply | Save the local copy; the source study stays unchanged. |
--plan-token <digest> | Require the source and destination to match a previous preview. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms recover
Inspect interrupted email leases; --apply deletes only privately recorded resources owned by this project and account.
humanish comms recover [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--run <id> | One run to inspect or recover. |
--apply | Recover the selected inactive run and verify mailbox deletion. |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish comms catch
Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your study's comms.email.external.catchBaseUrl at this server.
humanish comms catch [options]| Option | Description |
|---|---|
--port <port> | Port to listen on at 127.0.0.1. (default: "8025") |
--dir <path> | Directory for the deliveries log and rendered inbox. (default: ".humanish/comms-catch") |
--token <value> | Require this bearer token, at least 16 characters, on GET /deliveries (recommended when reachable off-host). |
--smtp-port <port> | Also capture SMTP mail on 127.0.0.1:<port>. Point your app's SMTP transport here. |
--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, --help | Show help for this command. |
humanish runtime
Prepare or inspect the local browser runtime.
humanish runtime [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish runtime status
Check local Docker, virtualization and the cached browser image without downloads, and how many participant desktops fit.
humanish runtime status [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
--media | Prepare or inspect the optional camera and speech runtime. |
-h, --help | Show help for this command. |
humanish runtime setup
Download and install the local browser image. Does not start a study or use model quota.
humanish runtime setup [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
--media | Prepare or inspect the optional camera and speech runtime. |
--memory <GiB> | Mac only: the humanish Lima VM's memory. Resizes an existing VM, which stops it first. |
--cpus <n> | Mac only: the humanish Lima VM's CPUs. Resizes an existing VM, which stops it first. |
-h, --help | Show help for this command. |
humanish reclaim
Kill an interrupted run's sandboxes: the exact ids journaled in its sandbox-receipts.ndjson, and any sandbox the run's provider lists with this run's owner tags (a sandbox whose id never reached a receipt). It lists only sandboxes that match every tag of this run. --check asks the provider whether each still exists and kills nothing. Needs E2B_API_KEY, or MODAL_TOKEN_ID and MODAL_TOKEN_SECRET for a run on Modal, in the environment or in --dotenv.
humanish reclaim [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--run <id> | Run id, or latest. (default: "latest") |
--preflight | Reclaim sandboxes left by interrupted humanish study check probes (journaled in .humanish/preflight) instead of a run's. |
--check | Ask the provider whether each sandbox still exists; kill nothing and write nothing. Exits 0 only when all are gone. |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish keys
Show which provider keys are set and where each comes from, and manage the humanish user key store that provider-key discovery reads.
humanish keys [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish keys status
Show each provider key humanish uses: where it comes from, or the command that adds it. Values are never printed.
humanish keys status [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish keys set
Store one provider key in the user store (0600), prompted with hidden input. With no key named, ask for each missing key in turn.
humanish keys set [options] [vendor-or-name]| Argument | Description |
|---|---|
vendor-or-name | A vendor alias (openai, e2b, modal, anthropic, github, agentmail, gemini) or a raw ENV_NAME. Without one, a terminal asks for each missing key in turn. |
| Option | Description |
|---|---|
--stdin | Read the value from stdin instead of prompting (for agents/pipes). |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish keys unset
Remove one key from the user store.
humanish keys unset [options] <vendor-or-name>| Argument | Description |
|---|---|
vendor-or-name | A vendor alias or raw ENV_NAME to remove from the store. |
| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish keys list
List the key names in the user store. Values are never printed.
humanish keys list [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish telemetry
Show or change anonymous usage collection.
humanish telemetry [options] [command]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish telemetry status
What is collected, and whether it is on.
humanish telemetry status [options]| Option | Description |
|---|---|
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |
humanish telemetry enable
Turn anonymous usage collection on.
humanish telemetry enable [options]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish telemetry disable
Turn anonymous usage collection off.
humanish telemetry disable [options]| Option | Description |
|---|---|
-h, --help | Show help for this command. |
humanish tui
Browse studies and runs in an interactive terminal UI. It refuses detected agent sessions and non-TTY input or output; agents use humanish study list --json, humanish study show <study> --json and humanish runs --json.
humanish tui [options]| Option | Description |
|---|---|
--cwd <path> | Project directory. (default: ".") |
--dotenv <path> | Load unset variables from this dotenv file. Values are never printed or saved. |
--force | Open it anyway in a session that looks like an agent's. |
--json | Print a machine-readable JSON response. |
-h, --help | Show help for this command. |