runhuman 1.12.0 → 2.1.0

package/README.md

@@ -61,6 +61,68 @@ If a prefix matches multiple resources, you'll be prompted to provide more chara
 
 **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
@@ -169,14 +231,63 @@ runhuman list --limit 20 --offset 40
 
 **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)
-- `--format <type>` - Output format: table, json, compact
+- `-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 permanently.
+Delete a job.
 
 ```bash
 runhuman delete job_abc123 --force
@@ -231,6 +342,44 @@ 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`
@@ -307,7 +456,7 @@ runhuman projects transfer proj_abc123 --to-org org_target123
 
 #### `projects delete <projectId>`
 
-Delete a project permanently. Requires the full project ID.
+Delete a project. Requires the full project ID.
 
 ```bash
 runhuman projects delete proj_abc123 --force
@@ -379,7 +528,6 @@ runhuman keys new "CI/CD Key" --organization org_abc123    # alias
 
 **Options:**
 - `-o, --organization <id>` - Organization ID (required)
-- `--copy` - Copy key to clipboard
 
 #### `keys show <keyId>`
 
@@ -395,7 +543,7 @@ runhuman keys show key_abc123 --show-key
 
 #### `keys delete <keyId>`
 
-Delete an API key permanently. Requires the full key ID.
+Delete an API key. Requires the full key ID.
 
 ```bash
 runhuman keys delete key_abc123 --force
@@ -547,6 +695,53 @@ runhuman github bulk-test -r owner/repo -u https://google.com \
 - `-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`