npm - runhuman - Versions diffs - 2.1.0 → 2.2.0 - Mend

runhuman 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,926 +1,947 @@
-# runhuman
-[![npm version](https://img.shields.io/npm/v/runhuman.svg)](https://www.npmjs.com/package/runhuman)
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
-> AI-orchestrated human QA testing from your terminal
-## What is Runhuman?
-Runhuman is an AI-orchestrated human QA testing service. Get real human testing of your web applications on-demand, with structured results extracted automatically.
-**Perfect for:**
-- AI coding agents that need human verification
-- CI/CD pipelines with human QA gates
-- Visual/UX testing requiring real human judgment
-- On-demand QA without hiring/managing teams
-## Installation
-```bash
-# Install globally
-npm install -g runhuman
-# Or use with npx
-npx runhuman --help
-```
-## Quick Start
-```bash
-# 1. Login (opens browser for OAuth)
-runhuman login
-# 2. Create your first test
-runhuman create https://google.com \
-  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
-# 3. Check the status
-runhuman status job_abc123
-# 4. Get results
-runhuman results job_abc123
-```
-## Truncated IDs
-All commands accept truncated ID prefixes, similar to git short hashes. Instead of typing a full ID, you can use just the first few characters:
-```bash
-# Full ID
-runhuman status 712e42ad-8f3b-4a1c-9d5e-1234567890ab
-# Truncated — resolves to the same job
-runhuman status 712e
-# Hyphens are ignored during matching
-runhuman status 712e42ad8f3b
-```
-If a prefix matches multiple resources, you'll be prompted to provide more characters. Matching is case-insensitive and hyphen-insensitive.
-**Destructive operations** (`projects delete`, `keys delete`, `projects transfer --to-org`) require the full ID to prevent accidental mismatches.
-## Global Flags
-Every command accepts the same four global flags:
-- `-j, --json` — emit machine-readable JSON to stdout (otherwise pretty-printed output)
-- `-q, --quiet` — suppress success and info messages (stderr deprecation/error output is preserved)
-- `-y, --yes` — skip confirmation prompts on destructive operations
-- `--no-color` — disable ANSI color codes (also honored from `RUNHUMAN_NO_COLOR=1`)
-**`-f, --force` is reserved for override-a-guard semantics**, not confirmation-skip. Today it only appears on `templates create`, where it means "overwrite an existing template with the same name."
-### Output modes
-`-j, --json` is the single output-mode flag. The CLI does not offer a `-o, --output` / `--format` choice à la kubectl — pretty output for humans and JSON for scripts are the two supported shapes. Any future structured-text formats (YAML, CSV, etc.) would be added as their own flags rather than via a format matrix.
-This also means `-o` remains bound to `--organization` on every command that has one, matching the noun-first mental model the rest of the CLI uses.
-### JSON envelope
-Every command that emits JSON uses the same envelope:
-```jsonc
-// Success
-{
-  "success": true,
-  "data": <payload>,              // see below
-  "pagination": {                 // only on list commands
-    "total": 42,
-    "limit": 20,
-    "offset": 0,
-    "hasMore": true
-  },
-  "warnings": ["..."],            // optional, non-fatal server-side warnings
-  "timestamp": "2026-04-24T12:34:56.789Z"
-}
-// Failure
-{
-  "success": false,
-  "error": {
-    "message": "...",
-    "code": "OPTIONAL_ERROR_CODE",
-    "details": { /* shape varies */ }
-  },
-  "timestamp": "2026-04-24T12:34:56.789Z"
-}
-```
-Payload conventions:
-- **List commands** (`projects list`, `jobs list`, `orgs list`, etc.) put their items under `data.items` and their pagination on the envelope. Never `data.jobs` or `data.projects` — always `data.items`.
-- **Show / create / update commands** put the entity directly as `data` (e.g. `data: { id, name, ... }`).
-- **Delete / archive / cancel commands** return a structured action payload such as `data: { id, deleted: true }`, `data: { id, archived: true }`, `data: { id, cancelled: true }`. The envelope already carries `success: true`; `data` never echoes it.
-A generic script can parse any CLI command's output without inspecting which command was run:
-```bash
-runhuman projects list --json | jq '.data.items[].id'
-runhuman projects show <id> --json | jq '.data.id'
-runhuman projects delete <id> --json | jq '.data.deleted'
-```
-## Commands
-### Jobs
-#### `create [url]`
-Create a new QA test job.
-```bash
-# Basic usage
-runhuman create https://google.com \
-  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
-# With template
-runhuman create https://google.com --template tmpl_abc123
-# Synchronous (wait for result)
-runhuman create https://google.com -d "Test search" --sync
-# With custom schema
-runhuman create https://google.com -d "Test search" --schema ./schema.json
-# With tester pool requirements
-runhuman create https://google.com -d "Test mobile layout" \
-  --required-devices ios,android \
-  --required-languages english
-```
-**Options:**
-- `-d, --description <text>` - Test instructions for the human tester
-- `-t, --template <name>` - Use a pre-defined template
-- `--duration <minutes>` - Target duration (1-60 minutes)
-- `--device-class <class>` - Device class: desktop or mobile
-- `-S, --schema <file>` - Path to JSON schema for structured output
-- `--schema-inline <json>` - Inline JSON schema string
-- `--metadata <json>` - Metadata for tracking (JSON string)
-- `--github-repo <owner/repo>` - GitHub repo for context
-- `--required-devices <devices>` - Required tester devices (comma-separated: ios, android, pc, mac)
-- `--required-languages <languages>` - Required tester languages (comma-separated: english, spanish)
-- `--require-social-videos` - Require tester to create social videos
-- `-s, --sync` - Wait for result before exiting
-- `--wait <seconds>` - Max wait time in sync mode (default: 300)
-- `-p, --project <id>` - Project ID (or use default from config)
-- `-j, --json` - Output as JSON
-- `-q, --quiet` - Minimal output (only job ID)
-#### `status <jobId>`
-Check the status of a test job.
-```bash
-runhuman status job_abc123
-runhuman status 712e    # truncated ID works
-```
-#### `wait <jobId>`
-Wait for a job to complete with live status updates.
-```bash
-runhuman wait job_abc123
-runhuman wait job_abc123 --timeout 300
-```
-**Options:**
-- `--timeout <seconds>` - Maximum wait time (default: 600)
-- `-j, --json` - Output as JSON
-#### `results <jobId>`
-Display detailed test results.
-```bash
-runhuman results job_abc123
-runhuman results job_abc123 --json
-runhuman results job_abc123 --schema-only   # Only extracted schema data
-runhuman results job_abc123 --raw           # Raw tester response
-```
-**Options:**
-- `--schema-only` - Show only extracted schema data
-- `--raw` - Show raw tester response without processing
-- `-j, --json` - Output as JSON
-#### `list [filter]`
-List all your test jobs with optional status filtering.
-```bash
-# List all jobs
-runhuman list
-# Filter by status (positional argument)
-runhuman list completed
-runhuman list pending
-# Filter by project
-runhuman list --project proj_abc123
-# Pagination
-runhuman list --limit 20 --offset 40
-```
-**Arguments:**
-- `[filter]` - Status filter: all, pending, claimed, in_progress, completed, failed, timeout
-**Options:**
-- `-p, --project <id>` - Filter by project
-- `--org <id>` - Scope to all projects in an organization (mutually exclusive with `--project`)
-- `-n, --limit <number>` - Maximum number of jobs (default: 20)
-- `--offset <number>` - Pagination offset (default: 0)
-- `-j, --json` - Output as JSON
-#### `artifact <jobId> <type>`
-Download a raw session artifact. Useful for piping transcripts, console logs, or network data into your own tools.
-```bash
-# Print the transcript
-runhuman job artifact job_abc123 transcript
-# Pipe raw console logs into jq
-runhuman job artifact job_abc123 console-logs --json | jq '.data.consoleMessages[]'
-```
-**Arguments:**
-- `<jobId>` - Job ID
-- `<type>` - One of: `structured-output`, `transcript`, `console-logs`, `network-requests`, `conversation`, `events`, `key-moments`
-**Options:**
-- `-j, --json` - Output as JSON (raw artifact shape wrapped in the standard envelope)
-Rich artifacts are paid-tier gated server-side; ungated requests return a clean "subscription required" error.
-#### `share <jobId>` / `unshare <jobId>`
-Toggle public sharing for a job. `share` enables and prints the public URL; `unshare` disables.
-```bash
-runhuman job share job_abc123
-runhuman job unshare job_abc123
-```
-#### `create-issue <jobId> --index <n>`
-File one extracted finding from a completed job as a GitHub issue. Mirrors the web UI's per-finding "Create Issue" button. Simple form only — the CLI submits the finding unedited; use the web UI or `gh issue edit` if you want to change title/body.
-```bash
-# File the first extracted finding to the job's default GitHub repo
-runhuman job create-issue job_abc123 --index 0
-# Override the target repo
-runhuman job create-issue job_abc123 --index 0 --repo owner/repo
-```
-**Required options:**
-- `--index <n>` - Zero-based index into `job.extractedIssues`
-**Options:**
-- `--repo <owner/repo>` - Override the job's default GitHub repo
-- `-j, --json` - Output as JSON
-#### `delete <jobId>`
-Delete a job.
-```bash
-runhuman delete job_abc123 --force
-```
-**Options:**
-- `-f, --force` - Skip confirmation prompt
-- `-j, --json` - Output as JSON
-### Organizations
-#### `orgs list`
-List all organizations you belong to.
-```bash
-runhuman orgs list
-runhuman orgs ls    # alias
-```
-#### `orgs show <organizationId>`
-Show organization details.
-```bash
-runhuman orgs show org_abc123
-runhuman orgs info org_abc123   # alias
-```
-#### `orgs balance <organizationId>`
-Check billing balance.
-```bash
-runhuman orgs balance org_abc123
-```
-#### `orgs projects <organizationId>`
-List all projects in an organization.
-```bash
-runhuman orgs projects org_abc123
-```
-#### `orgs switch <organizationId>`
-Set the default organization for CLI commands.
-```bash
-runhuman orgs switch org_abc123
-runhuman orgs switch org_abc123 --global   # all directories (default)
-```
-#### `orgs usage [organizationId]`
-Show usage analytics: total jobs, cost, per-project breakdown, over-time series.
-```bash
-# Default: last 30 days
-runhuman orgs usage
-# Preset period
-runhuman orgs usage --period 7d
-runhuman orgs usage --period all
-# Specific month
-runhuman orgs usage --year 2026 --month 4
-# Pipe the full response into your own tool
-runhuman orgs usage --json | jq '.data.byHour'
-```
-Default rendering shows the summary plus the top 5 projects by job count. `--json` returns the full response including `overTime`, `byHour`, and `bySource` arrays for scripting.
-**Options:**
-- `--period <window>` - `7d` | `30d` | `90d` | `all` (mutually exclusive with `--year/--month`)
-- `--year <y>` / `--month <m>` - Specific time window (month requires year)
-- `-j, --json` - Full response JSON
-#### `orgs invitations list|revoke`
-Manage pending invitations sent via `orgs invite`.
-```bash
-# List pending invitations
-runhuman orgs invitations list --organization org_abc123
-# Revoke one
-runhuman orgs invitations revoke inv_xyz789 --organization org_abc123 --yes
-```
-### Projects
-#### `projects list`
-List all your projects.
-```bash
-runhuman projects list
-runhuman projects ls    # alias
-```
-#### `projects create <name>`
-Create a new project in an organization.
-```bash
-runhuman projects create "My App" --organization org_abc123
-runhuman projects create "My App" --organization org_abc123 --set-default
-```
-**Options:**
-- `-o, --organization <id>` - Organization ID (required)
-- `--default-url <url>` - Default URL for tests
-- `--github-repo <owner/repo>` - Link GitHub repository
-- `--set-default` - Set as default project after creation
-#### `projects show <projectId>`
-Show project details including organization and balance.
-```bash
-runhuman projects show proj_abc123
-runhuman projects info proj_abc123    # alias
-runhuman projects get proj_abc123     # alias
-```
-#### `projects update <projectId>`
-Update project settings.
-```bash
-runhuman projects update proj_abc123 --name "New Name"
-runhuman projects update proj_abc123 --default-url https://google.com
-```
-**Options:**
-- `-n, --name <text>` - New project name
-- `-u, --default-url <url>` - New default URL
-- `-g, --github-repo <owner/repo>` - New GitHub repository
-#### `projects switch <projectId>`
-Set the default project for CLI commands.
-```bash
-runhuman projects switch proj_abc123
-runhuman projects use proj_abc123     # alias
-```
-**Options:**
-- `-g, --global` - Set as global default instead of local (default: true)
-#### `projects transfer <projectId>`
-Transfer a project to another organization.
-```bash
-runhuman projects transfer proj_abc123 --to-org org_target123
-```
-**Options:**
-- `--to-org <organizationId>` - Target organization ID (required, full ID required)
-- `-f, --force` - Skip confirmation prompt
-#### `projects delete <projectId>`
-Delete a project. Requires the full project ID.
-```bash
-runhuman projects delete proj_abc123 --force
-```
-**Options:**
-- `-f, --force` - Skip confirmation prompt
-### Transfers
-#### `transfers list`
-List pending and outgoing project transfers.
-```bash
-runhuman transfers list
-runhuman transfers ls    # alias
-```
-#### `transfers accept <transferId>`
-Accept an incoming transfer.
-```bash
-runhuman transfers accept xfer_abc123
-```
-#### `transfers reject <transferId>`
-Reject an incoming transfer.
-```bash
-runhuman transfers reject xfer_abc123
-```
-#### `transfers cancel <transferId>`
-Cancel an outgoing transfer you initiated.
-```bash
-runhuman transfers cancel xfer_abc123
-```
-### API Keys
-#### `keys list`
-List all API keys for an organization.
-```bash
-runhuman keys list --organization org_abc123
-runhuman keys ls --organization org_abc123    # alias
-runhuman keys list --organization org_abc123 --show-keys
-```
-**Options:**
-- `-o, --organization <id>` - Organization ID (required)
-- `--show-keys` - Show full API keys (default: masked)
-- `-j, --json` - Output as JSON
-#### `keys create <name>`
-Create a new API key for an organization.
-```bash
-runhuman keys create "CI/CD Key" --organization org_abc123
-runhuman keys new "CI/CD Key" --organization org_abc123    # alias
-```
-**Options:**
-- `-o, --organization <id>` - Organization ID (required)
-#### `keys show <keyId>`
-Show details of a specific API key.
-```bash
-runhuman keys show key_abc123
-runhuman keys show key_abc123 --show-key
-```
-**Options:**
-- `--show-key` - Show full API key (default: masked)
-#### `keys delete <keyId>`
-Delete an API key. Requires the full key ID.
-```bash
-runhuman keys delete key_abc123 --force
-runhuman keys rm key_abc123 --force       # alias
-runhuman keys revoke key_abc123 --force   # alias
-```
-**Options:**
-- `-f, --force` - Skip confirmation prompt
-### Templates
-#### `templates list`
-List all templates for a project.
-```bash
-runhuman templates list --project proj_abc123
-runhuman templates ls --project proj_abc123    # alias
-```
-**Options:**
-- `-p, --project <id>` - Project ID (required, or use default from config)
-#### `templates create <name>`
-Create a new template.
-```bash
-runhuman templates create "Search Flow Test" --project proj_abc123 \
-  -d "Search for 'recursion' and confirm the joke appears" \
-  --duration 180 \
-  --device-class desktop \
-  --schema ./schema.json
-```
-**Options:**
-- `-p, --project <id>` - Project ID (required, or use default from config)
-- `-d, --description <text>` - Template description
-- `--duration <seconds>` - Target test duration in seconds
-- `--device-class <class>` - Default device class (desktop/mobile)
-- `-S, --schema <path>` - Path to JSON schema file
-#### `templates show <templateId>`
-Show template details.
-```bash
-runhuman templates show tmpl_abc123 --project proj_abc123
-```
-#### `templates update <templateId>`
-Update a template.
-```bash
-runhuman templates update tmpl_abc123 --project proj_abc123 --name "New Name"
-```
-**Options:**
-- `-n, --name <name>` - New template name
-- `-d, --description <text>` - New description
-- `--duration <seconds>` - New target duration
-- `--device-class <class>` - New default device class
-- `-S, --schema <path>` - Path to new JSON schema file
-#### `templates delete <templateId>`
-Delete a template.
-```bash
-runhuman templates delete tmpl_abc123 --project proj_abc123 --force
-```
-**Options:**
-- `-f, --force` - Skip confirmation prompt
-### GitHub Integration
-#### `github link <repo>`
-Link a GitHub repository to your project.
-```bash
-runhuman github link owner/repo --project proj_abc123
-```
-**Options:**
-- `-p, --project <id>` - Project ID (required)
-#### `github repos`
-List GitHub repositories accessible to an organization.
-```bash
-runhuman github repos --organization org_abc123
-runhuman github repos --organization org_abc123 --search "my-app"
-```
-**Options:**
-- `-o, --organization <id>` - Organization ID (required)
-- `-s, --search <query>` - Filter by repository name
-#### `github issues <repo>`
-List GitHub issues for a repository.
-```bash
-runhuman github issues owner/repo
-runhuman github issues owner/repo --state open
-runhuman github issues owner/repo --labels "bug,needs-qa"
-```
-**Options:**
-- `-s, --state <state>` - Filter by state (open/closed/all, default: open)
-- `-l, --labels <labels>` - Filter by comma-separated labels
-#### `github test <issueNumber>`
-Create a QA test job for a GitHub issue.
-```bash
-runhuman github test 123 -r owner/repo -u https://google.com
-runhuman github test 123 -u https://google.com --sync
-```
-**Options:**
-- `-r, --repo <owner/repo>` - Repository (or use default from config)
-- `-u, --url <url>` - URL to test (required)
-- `-t, --template <id>` - Template ID to use
-- `-s, --sync` - Wait for result before exiting
-#### `github bulk-test`
-Create QA test jobs for multiple GitHub issues.
-```bash
-runhuman github bulk-test -r owner/repo -u https://google.com
-runhuman github bulk-test -r owner/repo -u https://google.com \
-  -l "bug,needs-qa" \
-  -n 5
-```
-**Options:**
-- `-r, --repo <owner/repo>` - Repository (or use default from config)
-- `-u, --url <url>` - URL to test (required)
-- `-l, --labels <labels>` - Filter issues by comma-separated labels
-- `-s, --state <state>` - Filter by state (open/closed/all, default: open)
-- `-t, --template <id>` - Template ID to use
-- `-n, --limit <number>` - Maximum number of jobs to create (default: 10)
-#### `github installation refresh`
-Force-refresh a GitHub App installation's repo/permissions list. Use this after granting the app access to new repos if they aren't visible yet.
-```bash
-runhuman github installation refresh --installation 987654321 --organization org_abc123
-```
-**Required options:**
-- `--installation <id>` - GitHub installation ID
-**Options:**
-- `-o, --organization <id>` - Organization ID (defaults to current org context)
-### Billing
-User-scoped reads. Purchase flows and plan changes stay in the web UI — use `billing portal` to get there.
-#### `billing balance`
-Show credit balance for the authenticated user's primary organization (or override with `-o`).
-```bash
-runhuman billing balance
-runhuman billing balance --organization org_abc123
-```
-#### `billing subscription`
-Show the active subscription (tier, billing cycle, renewal date) plus any active add-ons.
-```bash
-runhuman billing subscription
-```
-#### `billing portal [--open]`
-Return a one-time URL to the Polar customer portal (payment method, invoices, cancellation).
-```bash
-# Print the URL
-runhuman billing portal
-# Open it in the browser
-runhuman billing portal --open
-```
-### Authentication
-#### `login`
-Login to Runhuman. Opens your browser for OAuth by default.
-```bash
-runhuman login
-# Login with API key (skip browser)
-runhuman login --token <your-api-key>
-# Print auth URL without opening browser
-runhuman login --no-browser
-```
-#### `logout`
-Clear saved credentials.
-```bash
-runhuman logout
-```
-#### `whoami`
-Display current user info.
-```bash
-runhuman whoami
-```
-### Configuration
-#### `config get <key>`
-Get a configuration value.
-```bash
-runhuman config get apiUrl
-runhuman config get project
-```
-#### `config set <key> <value>`
-Set a configuration value.
-```bash
-runhuman config set project proj_abc123
-runhuman config set color false
-runhuman config set project proj_abc123 --global
-```
-**Options:**
-- `--global` - Save to global config instead of project config
-#### `config list`
-List all configuration values.
-```bash
-runhuman config list
-runhuman config list --show-secrets
-```
-**Options:**
-- `--show-secrets` - Show API keys (default: masked)
-#### `config reset`
-Reset configuration to defaults.
-```bash
-runhuman config reset --project --force
-runhuman config reset --global --force
-runhuman config reset --all --force
-```
-#### `init`
-Initialize a new Runhuman project with interactive prompts.
-```bash
-runhuman init
-runhuman init --name "My App" --url https://google.com --yes
-```
-Creates a `.runhumanrc` file in the current directory.
-## Configuration Hierarchy
-Configuration is loaded from multiple sources with the following priority (highest to lowest):
-1. **CLI flags** - `--api-key`, `--project`, etc.
-2. **Environment variables** - `RUNHUMAN_API_KEY`, `RUNHUMAN_API_URL`, etc.
-3. **Project config** - `.runhumanrc` in current directory
-4. **Global config** - `~/.config/runhuman/config.json`
-5. **Defaults**
-### Environment Variables
-```bash
-RUNHUMAN_API_KEY           # API key for authentication
-RUNHUMAN_API_URL           # API base URL (default: https://runhuman.com)
-RUNHUMAN_PROJECT_ID        # Default project ID
-RUNHUMAN_NO_COLOR=true     # Disable colored output
-```
-## JSON Output
-All commands support `-j, --json` for machine-readable output:
-```bash
-runhuman create https://google.com -d "Test search" --json
-runhuman status job_abc123 --json
-runhuman list --json
-```
-## Exit Codes
-- `0` - Success
-- `1` - General error / ambiguous ID / full ID required
-- `2` - Authentication error
-- `3` - Not found / no match for ID prefix
-- `4` - Validation error
-- `5` - Timeout error
-## Examples
-### Basic Workflow
-```bash
-# 1. Login
-runhuman login
-# 2. Initialize project
-runhuman init
-# 3. Create a test
-runhuman create https://google.com \
-  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
-# 4. Wait for results (truncated ID)
-runhuman wait 712e
-# 5. View detailed results
-runhuman results 712e
-```
-### CI/CD Integration
-```bash
-runhuman create https://staging.google.com \
-  -d "Search for 'recursion' and confirm the joke appears" \
-  --sync \
-  --json > result.json
-```
-## How It Works
-1. **You create a job** - Define test instructions and optional output schema
-2. **Job posted to testers** - Request goes to human tester pool
-3. **Human performs test** - Real person tests with video/screenshot recording
-4. **AI extracts data** - AI processes feedback into structured JSON
-5. **You get results** - Clean, typed data ready for automation
-**Pricing:** Pay-per-second ($0.0085/sec of tester time). No monthly fees, no minimums.
-## Learn More
-- **Website:** [runhuman.com](https://runhuman.com)
-- **Documentation:** [runhuman.com/docs](https://runhuman.com/docs)
-- **GitHub:** [github.com/volter-ai/runhuman](https://github.com/volter-ai/runhuman)
-## Support
-- **Email:** hey@runhuman.com
-- **Issues:** [GitHub Issues](https://github.com/volter-ai/runhuman/issues)
----
-**Built by the [Volter AI](https://volter.ai) team**
+# runhuman
+[![npm version](https://img.shields.io/npm/v/runhuman.svg)](https://www.npmjs.com/package/runhuman)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+> AI-orchestrated human QA testing from your terminal
+## What is Runhuman?
+Runhuman is an AI-orchestrated human QA testing service. Get real human testing of your web applications on-demand, with structured results extracted automatically.
+**Perfect for:**
+- AI coding agents that need human verification
+- CI/CD pipelines with human QA gates
+- Visual/UX testing requiring real human judgment
+- On-demand QA without hiring/managing teams
+## Installation
+```bash
+# Install globally
+npm install -g runhuman
+# Or use with npx
+npx runhuman --help
+```
+## Quick Start
+```bash
+# 1. Login (opens browser for OAuth)
+runhuman login
+# 2. Create your first test
+runhuman job create https://google.com \
+  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
+# 3. Check the status
+runhuman job status job_abc123
+# 4. Get results
+runhuman job results job_abc123
+```
+Job commands live under the `runhuman job` namespace. The flat shims (`runhuman create`, `runhuman status`, `runhuman wait`, `runhuman results`, `runhuman list`, `runhuman watch`) still work but are deprecated and emit a one-line warning on use; new scripts should use the `job` form.
+## Truncated IDs
+All commands accept truncated ID prefixes, similar to git short hashes. Instead of typing a full ID, you can use just the first few characters:
+```bash
+# Full ID
+runhuman job status 712e42ad-8f3b-4a1c-9d5e-1234567890ab
+# Truncated — resolves to the same job
+runhuman job status 712e
+# Hyphens are ignored during matching
+runhuman job status 712e42ad8f3b
+```
+If a prefix matches multiple resources, you'll be prompted to provide more characters. Matching is case-insensitive and hyphen-insensitive.
+**Destructive operations** (`projects delete`, `keys delete`, `projects transfer --to-org`) require the full ID to prevent accidental mismatches.
+## Global Flags
+Every command accepts the same four global flags:
+- `-j, --json` — emit machine-readable JSON to stdout (otherwise pretty-printed output)
+- `-q, --quiet` — suppress success and info messages (stderr deprecation/error output is preserved)
+- `-y, --yes` — skip confirmation prompts on destructive operations
+- `--no-color` — disable ANSI color codes (also honored from `RUNHUMAN_NO_COLOR=1`)
+**`-f, --force` is reserved for override-a-guard semantics**, not confirmation-skip. Today it only appears on `templates create`, where it means "overwrite an existing template with the same name."
+### Output modes
+`-j, --json` is the single output-mode flag. The CLI does not offer a `-o, --output` / `--format` choice à la kubectl — pretty output for humans and JSON for scripts are the two supported shapes. Any future structured-text formats (YAML, CSV, etc.) would be added as their own flags rather than via a format matrix.
+This also means `-o` remains bound to `--organization` on every command that has one, matching the noun-first mental model the rest of the CLI uses.
+### JSON envelope
+Every command that emits JSON uses the same envelope:
+```jsonc
+// Success
+{
+  "success": true,
+  "data": <payload>,              // see below
+  "pagination": {                 // only on list commands
+    "total": 42,
+    "limit": 20,
+    "offset": 0,
+    "hasMore": true
+  },
+  "warnings": ["..."],            // optional, non-fatal server-side warnings
+  "timestamp": "2026-04-24T12:34:56.789Z"
+}
+// Failure
+{
+  "success": false,
+  "error": {
+    "message": "...",
+    "code": "OPTIONAL_ERROR_CODE",
+    "details": { /* shape varies */ }
+  },
+  "timestamp": "2026-04-24T12:34:56.789Z"
+}
+```
+Payload conventions:
+- **List commands** (`projects list`, `jobs list`, `orgs list`, etc.) put their items under `data.items` and their pagination on the envelope. Never `data.jobs` or `data.projects` — always `data.items`.
+- **Show / create / update commands** put the entity directly as `data` (e.g. `data: { id, name, ... }`).
+- **Delete / archive / cancel commands** return a structured action payload such as `data: { id, deleted: true }`, `data: { id, archived: true }`, `data: { id, cancelled: true }`. The envelope already carries `success: true`; `data` never echoes it.
+A generic script can parse any CLI command's output without inspecting which command was run:
+```bash
+runhuman projects list --json | jq '.data.items[].id'
+runhuman projects show <id> --json | jq '.data.id'
+runhuman projects delete <id> --json | jq '.data.deleted'
+```
+## Commands
+### Jobs
+All job commands live under the `runhuman job` namespace. Flat shims (`runhuman create`, `runhuman status`, `runhuman wait`, `runhuman results`, `runhuman list`, `runhuman watch`) still resolve but emit a deprecation warning.
+#### `job create [url]`
+Create a new QA test job.
+```bash
+# Basic usage
+runhuman job create https://google.com \
+  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
+# With template
+runhuman job create https://google.com --template tmpl_abc123
+# Synchronous (wait for result)
+runhuman job create https://google.com -d "Test search" --sync
+# With custom schema
+runhuman job create https://google.com -d "Test search" --schema ./schema.json
+# With tester pool requirements
+runhuman job create https://google.com -d "Test mobile layout" \
+  --required-devices ios,android \
+  --required-languages english
+```
+**Options:**
+- `-d, --description <text>` - Test instructions for the human tester
+- `-t, --template <name>` - Use a pre-defined template
+- `--duration <minutes>` - Target duration (1-60 minutes)
+- `--device-class <class>` - Device class: desktop, mobile, or both (default: both)
+- `-S, --schema <file>` - Path to JSON schema for structured output
+- `--schema-inline <json>` - Inline JSON schema string
+- `--metadata <json>` - Metadata for tracking (JSON string)
+- `--github-repo <owner/repo>` - GitHub repo for context
+- `--required-devices <devices>` - Required tester devices (comma-separated: ios, android, pc, mac)
+- `--required-languages <languages>` - Required tester languages (comma-separated: english, spanish)
+- `--require-social-videos` - Require tester capable of recording social-media-style videos (Max+ tier)
+- `-s, --sync` - Wait for result before exiting
+- `--wait <seconds>` - Max wait time in sync mode (default: 300)
+- `-p, --project <id>` - Project ID (or use default from config)
+- `-j, --json` - Output as JSON
+- `-q, --quiet` - Minimal output (only job ID)
+#### `job status <jobId>`
+Check the status of a test job. Aliases: `show`, `get`, `info`.
+```bash
+runhuman job status job_abc123
+runhuman job status 712e    # truncated ID works
+```
+#### `job wait <jobId>`
+Wait for a job to complete with live status updates.
+```bash
+runhuman job wait job_abc123
+runhuman job wait job_abc123 --timeout 300
+```
+**Options:**
+- `--timeout <seconds>` - Maximum wait time (default: 600)
+- `-j, --json` - Output as JSON
+#### `job results <jobId>`
+Display detailed test results, with optional rich-data sections.
+```bash
+runhuman job results job_abc123
+runhuman job results job_abc123 --json
+runhuman job results job_abc123 --schema-only   # Only extracted schema data
+runhuman job results job_abc123 --raw           # Raw tester response
+runhuman job results job_abc123 --transcript --console-logs
+runhuman job results job_abc123 --all           # Every rich section
+```
+**Options:**
+- `--schema-only` - Show only extracted schema data
+- `--raw` - Show raw tester response without processing
+- `--transcript` - Include the voice transcript
+- `--console-logs` - Include captured console logs
+- `--network` - Include captured network requests
+- `--events` - Include user-interaction events
+- `--key-moments` - Include key-moments timeline
+- `--conversation` - Include the AI ↔ tester conversation
+- `-a, --all` - Include every rich-data section above
+- `-j, --json` - Output as JSON
+Rich-data sections (transcript, logs, network, events, key moments, conversation) are paid-tier gated server-side.
+#### `job list [filter]`
+List all your test jobs with optional status filtering. The `[filter]` matches the chip labels shown on the web Jobs page.
+```bash
+# List all jobs
+runhuman job list
+# Filter by status (positional argument, case-insensitive)
+runhuman job list Completed
+runhuman job list pending
+# Filter by multiple labels at once
+runhuman job list "Pending,Working,Completed"
+# Filter by project, or scope to an entire org
+runhuman job list --project proj_abc123
+runhuman job list --org org_abc123
+# Pagination
+runhuman job list --limit 20 --offset 40
+```
+**Arguments:**
+- `[filter]` - Chip label (comma-separated, case-insensitive): `all`, `Pending`, `Queued`, `Working`, `Completed`, `Cancelled`, `Expired`, `Failed`. Admins may pass fine-grain labels.
+**Options:**
+- `-p, --project <id>` - Filter by project
+- `--org <id>` - Scope to all projects in an organization (mutually exclusive with `--project`)
+- `-n, --limit <number>` - Maximum number of jobs (default: 20)
+- `--offset <number>` - Pagination offset (default: 0)
+- `-j, --json` - Output as JSON
+#### `job artifact <jobId> <type>`
+Download a raw session artifact. Useful for piping transcripts, console logs, or network data into your own tools.
+```bash
+# Print the transcript
+runhuman job artifact job_abc123 transcript
+# Pipe raw console logs into jq
+runhuman job artifact job_abc123 console-logs --json | jq '.data.consoleMessages[]'
+```
+**Arguments:**
+- `<jobId>` - Job ID
+- `<type>` - One of: `structured-output`, `transcript`, `console-logs`, `network-requests`, `conversation`, `events`, `key-moments`
+**Options:**
+- `-j, --json` - Output as JSON (raw artifact shape wrapped in the standard envelope)
+Rich artifacts are paid-tier gated server-side; ungated requests return a clean "subscription required" error.
+#### `job share <jobId>` / `job unshare <jobId>`
+Toggle public sharing for a job. `share` enables and prints the public URL; `unshare` disables.
+```bash
+runhuman job share job_abc123
+runhuman job unshare job_abc123
+```
+#### `job create-issue <jobId> --index <n>`
+File one extracted finding from a completed job as a GitHub issue. Mirrors the web UI's per-finding "Create Issue" button. Simple form only — the CLI submits the finding unedited; use the web UI or `gh issue edit` if you want to change title/body.
+```bash
+# File the first extracted finding to the job's default GitHub repo
+runhuman job create-issue job_abc123 --index 0
+# Override the target repo
+runhuman job create-issue job_abc123 --index 0 --repo owner/repo
+```
+**Required options:**
+- `--index <n>` - Zero-based index into `job.extractedIssues`
+**Options:**
+- `--repo <owner/repo>` - Override the job's default GitHub repo
+- `-j, --json` - Output as JSON
+#### `job delete <jobId>`
+Delete a job (admin-only — customers cannot delete their own jobs; use the dashboard's archive flow to organize your job list).
+```bash
+runhuman job delete job_abc123 --force
+```
+**Options:**
+- `-f, --force` - Skip confirmation prompt
+- `-j, --json` - Output as JSON
+There is no `job cancel` command; once a tester is engaged, jobs run through to a terminal state.
+### Organizations
+#### `orgs list`
+List all organizations you belong to.
+```bash
+runhuman orgs list
+runhuman orgs ls    # alias
+```
+#### `orgs show <organizationId>`
+Show organization details.
+```bash
+runhuman orgs show org_abc123
+runhuman orgs info org_abc123   # alias
+```
+#### `orgs balance <organizationId>`
+Check billing balance.
+```bash
+runhuman orgs balance org_abc123
+```
+#### `orgs projects <organizationId>`
+List all projects in an organization.
+```bash
+runhuman orgs projects org_abc123
+```
+#### `orgs switch <organizationId>`
+Set the default organization for CLI commands.
+```bash
+runhuman orgs switch org_abc123
+runhuman orgs switch org_abc123 --global   # all directories (default)
+```
+#### `orgs usage [organizationId]`
+Show usage analytics: total jobs, cost, per-project breakdown, over-time series.
+```bash
+# Default: last 30 days
+runhuman orgs usage
+# Preset period
+runhuman orgs usage --period 7d
+runhuman orgs usage --period all
+# Specific month
+runhuman orgs usage --year 2026 --month 4
+# Pipe the full response into your own tool
+runhuman orgs usage --json | jq '.data.byHour'
+```
+Default rendering shows the summary plus the top 5 projects by job count. `--json` returns the full response including `overTime`, `byHour`, and `bySource` arrays for scripting.
+**Options:**
+- `--period <window>` - `7d` | `30d` | `90d` | `all` (mutually exclusive with `--year/--month`)
+- `--year <y>` / `--month <m>` - Specific time window (month requires year)
+- `-j, --json` - Full response JSON
+#### `orgs invitations list|revoke`
+Manage pending invitations sent via `orgs invite`.
+```bash
+# List pending invitations
+runhuman orgs invitations list --organization org_abc123
+# Revoke one
+runhuman orgs invitations revoke inv_xyz789 --organization org_abc123 --yes
+```
+### Projects
+#### `projects list`
+List all your projects.
+```bash
+runhuman projects list
+runhuman projects ls    # alias
+```
+#### `projects create <name>`
+Create a new project in an organization.
+```bash
+runhuman projects create "My App" --organization org_abc123
+runhuman projects create "My App" --organization org_abc123 --set-default
+```
+**Options:**
+- `-o, --organization <id>` - Organization ID (required)
+- `--default-url <url>` - Default URL for tests
+- `--github-repo <owner/repo>` - Link GitHub repository
+- `--set-default` - Set as default project after creation
+#### `projects show <projectId>`
+Show project details including organization and balance.
+```bash
+runhuman projects show proj_abc123
+runhuman projects info proj_abc123    # alias
+runhuman projects get proj_abc123     # alias
+```
+#### `projects update <projectId>`
+Update project settings.
+```bash
+runhuman projects update proj_abc123 --name "New Name"
+runhuman projects update proj_abc123 --default-url https://google.com
+```
+**Options:**
+- `-n, --name <text>` - New project name
+- `-u, --default-url <url>` - New default URL
+- `-g, --github-repo <owner/repo>` - New GitHub repository
+#### `projects switch <projectId>`
+Set the default project for CLI commands.
+```bash
+runhuman projects switch proj_abc123
+runhuman projects use proj_abc123     # alias
+```
+**Options:**
+- `-g, --global` - Set as global default instead of local (default: true)
+#### `projects transfer <projectId>`
+Transfer a project to another organization.
+```bash
+runhuman projects transfer proj_abc123 --to-org org_target123
+```
+**Options:**
+- `--to-org <organizationId>` - Target organization ID (required, full ID required)
+- `-f, --force` - Skip confirmation prompt
+#### `projects delete <projectId>`
+Delete a project. Requires the full project ID.
+```bash
+runhuman projects delete proj_abc123 --force
+```
+**Options:**
+- `-f, --force` - Skip confirmation prompt
+### Transfers
+#### `transfers list`
+List pending and outgoing project transfers.
+```bash
+runhuman transfers list
+runhuman transfers ls    # alias
+```
+#### `transfers accept <transferId>`
+Accept an incoming transfer.
+```bash
+runhuman transfers accept xfer_abc123
+```
+#### `transfers reject <transferId>`
+Reject an incoming transfer.
+```bash
+runhuman transfers reject xfer_abc123
+```
+#### `transfers cancel <transferId>`
+Cancel an outgoing transfer you initiated.
+```bash
+runhuman transfers cancel xfer_abc123
+```
+### API Keys
+#### `keys list`
+List all API keys for an organization.
+```bash
+runhuman keys list --organization org_abc123
+runhuman keys ls --organization org_abc123    # alias
+runhuman keys list --organization org_abc123 --show-keys
+```
+**Options:**
+- `-o, --organization <id>` - Organization ID (required)
+- `--show-keys` - Show full API keys (default: masked)
+- `-j, --json` - Output as JSON
+#### `keys create <name>`
+Create a new API key for an organization.
+```bash
+runhuman keys create "CI/CD Key" --organization org_abc123
+runhuman keys new "CI/CD Key" --organization org_abc123    # alias
+```
+**Options:**
+- `-o, --organization <id>` - Organization ID (required)
+#### `keys show <keyId>`
+Show details of a specific API key.
+```bash
+runhuman keys show key_abc123
+runhuman keys show key_abc123 --show-key
+```
+**Options:**
+- `--show-key` - Show full API key (default: masked)
+#### `keys delete <keyId>`
+Delete an API key. Requires the full key ID.
+```bash
+runhuman keys delete key_abc123 --force
+runhuman keys rm key_abc123 --force       # alias
+runhuman keys revoke key_abc123 --force   # alias
+```
+**Options:**
+- `-f, --force` - Skip confirmation prompt
+### Templates
+#### `templates list`
+List all templates for a project.
+```bash
+runhuman templates list --project proj_abc123
+runhuman templates ls --project proj_abc123    # alias
+```
+**Options:**
+- `-p, --project <id>` - Project ID (required, or use default from config)
+#### `templates create <name>`
+Create a new template.
+```bash
+runhuman templates create "Search Flow Test" --project proj_abc123 \
+  -d "Search for 'recursion' and confirm the joke appears" \
+  --duration 180 \
+  --device-class desktop \
+  --schema ./schema.json
+```
+**Options:**
+- `-p, --project <id>` - Project ID (required, or use default from config)
+- `-d, --description <text>` - Template description
+- `--duration <seconds>` - Target test duration in seconds
+- `--device-class <class>` - Default device class (desktop/mobile/both)
+- `-S, --schema <path>` - Path to JSON schema file
+#### `templates show <templateId>`
+Show template details.
+```bash
+runhuman templates show tmpl_abc123 --project proj_abc123
+```
+#### `templates update <templateId>`
+Update a template.
+```bash
+runhuman templates update tmpl_abc123 --project proj_abc123 --name "New Name"
+```
+**Options:**
+- `-n, --name <name>` - New template name
+- `-d, --description <text>` - New description
+- `--duration <seconds>` - New target duration
+- `--device-class <class>` - New default device class
+- `-S, --schema <path>` - Path to new JSON schema file
+#### `templates delete <templateId>`
+Delete a template.
+```bash
+runhuman templates delete tmpl_abc123 --project proj_abc123 --force
+```
+**Options:**
+- `-f, --force` - Skip confirmation prompt
+### GitHub Integration
+#### `github link <repo>`
+Link a GitHub repository to your project.
+```bash
+runhuman github link owner/repo --project proj_abc123
+```
+**Options:**
+- `-p, --project <id>` - Project ID (required)
+#### `github repos`
+List GitHub repositories accessible to an organization.
+```bash
+runhuman github repos --organization org_abc123
+runhuman github repos --organization org_abc123 --search "my-app"
+```
+**Options:**
+- `-o, --organization <id>` - Organization ID (required)
+- `-s, --search <query>` - Filter by repository name
+#### `github issues <repo>`
+List GitHub issues for a repository.
+```bash
+runhuman github issues owner/repo
+runhuman github issues owner/repo --state open
+runhuman github issues owner/repo --labels "bug,needs-qa"
+```
+**Options:**
+- `-s, --state <state>` - Filter by state (open/closed/all, default: open)
+- `-l, --labels <labels>` - Filter by comma-separated labels
+#### `github test <issueNumber>`
+Create a QA test job for a GitHub issue.
+```bash
+runhuman github test 123 -r owner/repo -u https://google.com
+runhuman github test 123 -u https://google.com --sync
+```
+**Options:**
+- `-r, --repo <owner/repo>` - Repository (or use default from config)
+- `-u, --url <url>` - URL to test (required)
+- `-t, --template <id>` - Template ID to use
+- `-s, --sync` - Wait for result before exiting
+#### `github bulk-test`
+Create QA test jobs for multiple GitHub issues.
+```bash
+runhuman github bulk-test -r owner/repo -u https://google.com
+runhuman github bulk-test -r owner/repo -u https://google.com \
+  -l "bug,needs-qa" \
+  -n 5
+```
+**Options:**
+- `-r, --repo <owner/repo>` - Repository (or use default from config)
+- `-u, --url <url>` - URL to test (required)
+- `-l, --labels <labels>` - Filter issues by comma-separated labels
+- `-s, --state <state>` - Filter by state (open/closed/all, default: open)
+- `-t, --template <id>` - Template ID to use
+- `-n, --limit <number>` - Maximum number of jobs to create (default: 10)
+#### `github installation refresh`
+Force-refresh a GitHub App installation's repo/permissions list. Use this after granting the app access to new repos if they aren't visible yet.
+```bash
+runhuman github installation refresh --installation 987654321 --organization org_abc123
+```
+**Required options:**
+- `--installation <id>` - GitHub installation ID
+**Options:**
+- `-o, --organization <id>` - Organization ID (defaults to current org context)
+### Billing
+User-scoped reads. Purchase flows and plan changes stay in the web UI — use `billing portal` to get there.
+#### `billing balance`
+Show credit balance for the authenticated user's primary organization (or override with `-o`).
+```bash
+runhuman billing balance
+runhuman billing balance --organization org_abc123
+```
+#### `billing subscription`
+Show the active subscription (tier, billing cycle, renewal date) plus any active add-ons.
+```bash
+runhuman billing subscription
+```
+#### `billing portal [--open]`
+Return a one-time URL to the Polar customer portal (payment method, invoices, cancellation).
+```bash
+# Print the URL
+runhuman billing portal
+# Open it in the browser
+runhuman billing portal --open
+```
+### Authentication
+#### `login`
+Login to Runhuman. Opens your browser for OAuth by default.
+```bash
+runhuman login
+# Login with API key (skip browser)
+runhuman login --token <your-api-key>
+# Print auth URL without opening browser
+runhuman login --no-browser
+```
+#### `logout`
+Clear saved credentials.
+```bash
+runhuman logout
+```
+#### `whoami`
+Display current user info.
+```bash
+runhuman whoami
+```
+### Configuration
+#### `config get <key>`
+Get a configuration value.
+```bash
+runhuman config get apiUrl
+runhuman config get project
+```
+#### `config set <key> <value>`
+Set a configuration value.
+```bash
+runhuman config set project proj_abc123
+runhuman config set color false
+runhuman config set project proj_abc123 --global
+```
+**Options:**
+- `--global` - Save to global config instead of project config
+#### `config list`
+List all configuration values.
+```bash
+runhuman config list
+runhuman config list --show-secrets
+```
+**Options:**
+- `--show-secrets` - Show API keys (default: masked)
+#### `config reset`
+Reset configuration to defaults.
+```bash
+runhuman config reset --project --force
+runhuman config reset --global --force
+runhuman config reset --all --force
+```
+#### `init`
+Initialize a new Runhuman project with interactive prompts.
+```bash
+runhuman init
+runhuman init --name "My App" --url https://google.com --yes
+```
+Creates a `.runhumanrc` file in the current directory.
+## Configuration Hierarchy
+Configuration is loaded from multiple sources with the following priority (highest to lowest):
+1. **CLI flags** - `--api-key`, `--project`, etc.
+2. **Environment variables** - `RUNHUMAN_API_KEY`, `RUNHUMAN_API_URL`, etc.
+3. **Project config** - `.runhumanrc` in current directory
+4. **Global config** - `~/.config/runhuman/config.json`
+5. **Defaults**
+### Environment Variables
+```bash
+RUNHUMAN_API_KEY           # API key for authentication
+RUNHUMAN_API_URL           # API base URL (default: https://runhuman.com)
+RUNHUMAN_PROJECT_ID        # Default project ID
+RUNHUMAN_NO_COLOR=true     # Disable colored output
+```
+## JSON Output
+All commands support `-j, --json` for machine-readable output:
+```bash
+runhuman job create https://google.com -d "Test search" --json
+runhuman job status job_abc123 --json
+runhuman job list --json
+```
+## Exit Codes
+- `0` - Success
+- `1` - General error / ambiguous ID / full ID required
+- `2` - Authentication error
+- `3` - Not found / no match for ID prefix
+- `4` - Validation error
+- `5` - Timeout error
+## Examples
+### Basic Workflow
+```bash
+# 1. Login
+runhuman login
+# 2. Initialize project
+runhuman init
+# 3. Create a test
+runhuman job create https://google.com \
+  -d "Search for 'recursion' and confirm the tester experiences a joke about recursion"
+# 4. Wait for results (truncated ID)
+runhuman job wait 712e
+# 5. View detailed results
+runhuman job results 712e
+```
+### CI/CD Integration
+```bash
+runhuman job create https://staging.google.com \
+  -d "Search for 'recursion' and confirm the joke appears" \
+  --sync \
+  --json > result.json
+```
+## How It Works
+1. **You create a job** - Define test instructions and optional output schema
+2. **Job posted to testers** - Request goes to human tester pool
+3. **Human performs test** - Real person tests with video/screenshot recording
+4. **AI extracts data** - AI processes feedback into structured JSON
+5. **You get results** - Clean, typed data ready for automation
+**Pricing:** Pay-per-second ($0.0085/sec of tester time). No monthly fees, no minimums.
+## Learn More
+- **Website:** [runhuman.com](https://runhuman.com)
+- **Documentation:** [runhuman.com/docs](https://runhuman.com/docs)
+- **GitHub:** [github.com/volter-ai/runhuman](https://github.com/volter-ai/runhuman)
+## Support
+- **Email:** hey@runhuman.com
+- **Issues:** [GitHub Issues](https://github.com/volter-ai/runhuman/issues)
+---
+**Built by the [Volter AI](https://volter.ai) team**