trackrev 0.1.0 → 0.3.0

package/README.md

@@ -1,96 +1,1001 @@
 # trackrev
 
-Your [TrackRev](https://trackrev.io) link analytics, in the terminal — performance per channel,
-per link, the raw click stream, and any single visitor's full journey.
+[TrackRev](https://trackrev.io) for Node and the terminal — create and manage tracking links,
+pull performance per channel and per link, walk the raw click stream, replay any visitor's
+journey from first click to paid conversion, and run a referral program end to end.
 
-Zero dependencies. Node 20 or newer.
+One package, two ways in: `import { TrackRev } from "trackrev"` in your app, or the `trackrev`
+command in your shell. Zero dependencies. Node 20 or newer.
 
 ## Install
 
+In your project, for the SDK:
+
 ```bash
-npx trackrev channels
+npm install trackrev
 ```
 
-Or keep it around:
+Globally, for the CLI:
 
 ```bash
 npm install -g trackrev
 ```
 
+Or run the CLI once without installing:
+
+```bash
+npx trackrev channels
+```
+
 ## Authenticate
 
-Create a **secret** key under Settings → Developers, then:
+Create a **secret** key under Settings → Developers, then either save it:
+
+```bash
+trackrev login
+```
+
+It is stored at `~/.config/trackrev/config.json` with mode `0600` and verified against the API
+before it is written, so a typo fails immediately rather than on your next command.
+
+Or set it in the environment, which always wins and is what CI should use:
 
 ```bash
 export TRACKREV_KEY=lk_live_...
 ```
 
-Set `TRACKREV_API_URL` to point at a different API base (self-hosted, staging).
+`TRACKREV_API_URL` points the CLI at a different API base (self-hosted, staging). Use
+`--profile NAME` on `login` to keep several environments side by side.
+
+## Plans
+
+Link and account commands work on **every plan**, including free, and respect the same limits the
+dashboard does (50 links on the free tier). Analytics commands — `channels`, `links perf`,
+`clicks`, `journey` — need a **paid plan**; on a free workspace they exit `3` with an upgrade
+message.
+
+## Node SDK
+
+Everything below, as a client for your own code. Twenty resources, 71 methods, and a
+hand-written `index.d.ts`, so an editor completes `trackrev.links.` and catches a misspelled
+option before the code runs.
+
+```js
+import { TrackRev } from "trackrev";
+
+const trackrev = new TrackRev(process.env.TRACKREV_KEY);
+
+const { channels } = await trackrev.channels.list({ days: 7 });
+
+const launch = await trackrev.links.create("https://acme.com/launch", "Launch", {
+  channels: ["youtube", "newsletter"],
+  maxClicks: 1000,
+});
+```
+
+Required arguments are positional; everything optional goes in a trailing object, named in
+camelCase and sent as the snake_case the API expects.
+
+```
+trackrev.attribution   .get .update
+trackrev.channels      .list
+trackrev.clicks        .list
+trackrev.commissions   .list .create .setStatus
+trackrev.credits       .list .markDelivered
+trackrev.domains       .list .get .add .verify .remove
+trackrev.export        .csv
+trackrev.folders       .list .get .create .update .remove .assign
+trackrev.keys          .list .create .revoke
+trackrev.links         .list .records .get .create .update .remove .createMany .qr
+trackrev.orders        .list
+trackrev.partners      .list .setStatus .setGroup
+trackrev.payouts       .list .settle
+trackrev.programs      .list .get .update .groups
+trackrev.referrals     .enroll .reportSignup .reportPurchase .stats
+                       .setPayoutMethod .setRewardMode
+trackrev.retargeting   .list .set .remove
+trackrev.revenue       .connections .connection .providers .connect
+                       .setWebhookSecret .disconnect .sync
+trackrev.settings      .notifications .setNotification .branding .updateBranding
+trackrev.visitors      .list .get .journey
+trackrev.webhooks      .list .events .get .create .update .remove
+trackrev.me()
+```
+
+### A referral program, end to end
+
+```js
+// Someone opts in. You get back their referral link.
+const { referral_link } = await trackrev.referrals.enroll(user.id, user.email, "paid");
+
+// Someone they invited signs up.
+await trackrev.referrals.reportSignup(newUser.id, { refCode: "abc123" });
+
+// That person pays. Idempotent on your own order id, so a replay never double-credits.
+await trackrev.referrals.reportPurchase(newUser.id, order.id, 49.99, { currency: "usd" });
+```
+
+### Errors
+
+Anything that is not a success rejects with a `TrackRevError` carrying the HTTP `status` and
+the API's own `code`. A request that never got an answer — server unreachable, or timed out —
+rejects with a `TrackRevConnectionError`, which is a `TrackRevError` with `status` 0.
+
+```js
+import { TrackRev, TrackRevError, TrackRevConnectionError } from "trackrev";
+
+try {
+  await trackrev.keys.create({ scope: "secret", label: "CI" });
+} catch (e) {
+  if (e instanceof TrackRevConnectionError) retryLater();
+  else if (e instanceof TrackRevError) console.error(e.status, e.code, e.message);
+  else throw e;
+}
+```
+
+### Retries
+
+A request that is safe to repeat is retried three times on a 429, a 5xx or a connection
+failure, backing off 400ms, 800ms, 1600ms with a little randomness so throttled clients do not
+all return in the same instant. A `Retry-After` header wins over that schedule.
+
+Safe to repeat means every `GET`, plus the three referral writes the API ignores a repeat of:
+`enroll`, `reportSignup` and `reportPurchase`. Every other write — creating a link, minting a
+key, settling a payout — is sent exactly once, because a retry there could do the work twice.
+
+### Options
+
+```js
+new TrackRev(key, {
+  apiUrl: "https://app.trackrev.io/api/v1", // point at staging or self-hosted
+  timeoutMs: 15000,                         // per attempt; 0 means no limit
+  maxRetries: 3,                            // 0 turns retries off
+});
+```
+
+An endpoint the SDK has no method for yet is one call away:
+
+```js
+await trackrev.request("GET", "/some/new/endpoint");
+```
 
 ## Commands
 
-### `channels` — performance per traffic source
+<!-- cli:commands:start -->
+
+_Generated from `apps/cli/src/registry.js` — edit there, then run `pnpm --filter trackrev sync-docs`._
+
+### Analytics
+
+#### `trackrev channels`
+
+performance per traffic source _(paid plan)_
+
+```bash
+trackrev channels --days 7 --ltv
+```
+
+| flag | meaning |
+| --- | --- |
+| `--days N` | last N days (default 30, max 365) |
+| `--from ISO` | explicit start, e.g. 2026-01-01; wins over --days |
+| `--to ISO` | explicit end (defaults to now) |
+| `--ltv` | add all-time lifetime value per channel |
+
+conversions is a decimal on purpose — attribution splits credit, so one sale touched by two channels counts 0.5 on each.
+
+#### `trackrev links perf`
+
+performance per short link (bare `trackrev links` still works) _(paid plan)_
+
+```bash
+trackrev links perf --limit 20
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | rows to return (max 500) |
+| `--days N` | last N days (default 30, max 365) |
+| `--from ISO` | explicit start, e.g. 2026-01-01; wins over --days |
+| `--to ISO` | explicit end (defaults to now) |
+| `--settings` | attach each link's URL, expiry and password flag |
+
+#### `trackrev clicks`
+
+the raw click stream — newest first, bots excluded _(paid plan)_
+
+```bash
+trackrev clicks --all --json
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | page size (default 100, max 500) |
+| `--all` | follow the cursor to the end of the stream |
+| `--link ID` | one link only |
+| `--bots` | include bot traffic |
+
+--all stops after 200 pages and says so on stderr, so a runaway cursor can never loop forever.
+
+#### `trackrev visitors journey <visitor-id>`
+
+one visitor's timeline — every click, identify event and order, in order _(paid plan)_
+
+```bash
+trackrev journey <visitor-id>
+```
+
+The visitor caption goes to stderr, so the rows stay pipe-clean.
+
+### Links
+
+#### `trackrev links list`
+
+the links themselves — newest first, no window
+
+```bash
+trackrev links list --channel youtube
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | page size (default 100, max 500) |
+| `--all` | follow the cursor to the end |
+| `--channel KEY` | one channel only |
+| `--q TEXT` | slug contains this text |
+
+#### `trackrev links create`
+
+create a campaign: one link per channel, or one Smart Link
+
+```bash
+trackrev links create --url https://acme.com/launch --name Launch --channel youtube --channel newsletter
+```
+
+| flag | meaning |
+| --- | --- |
+| `--url URL` | destination (required) |
+| `--name TEXT` | campaign name (required) |
+| `--channel KEY` | a channel; repeat for several |
+| `--smart` | one link that infers its channel per click |
+| `--tag TEXT` | a tag; repeat for several |
+| `--folder ID` | put the campaign in this folder |
+| `--external` | destination is a site you can't put the pixel on |
+| `--slug SLUG` | custom slug (2–64 chars; lowercase, digits, hyphens) |
+| `--campaign TEXT` | utm_campaign (defaults to the name) |
+| `--expires ISO` | expire at this time |
+| `--max-clicks N` | expire after this many clicks |
+| `--expired-url URL` | where to send visitors after expiry |
+| `--password TEXT` | require this password before redirecting |
+| `--mobile-url URL` | device targeting: send mobile here |
+| `--desktop-url URL` | device targeting: send desktop here |
+| `--retarget on\|off` | fire the workspace's ad pixels on click |
+
+Prints one row per link created. Channels: facebook instagram youtube linkedin twitter tiktok newsletter website other.
+
+#### `trackrev links get <id-or-slug>`
+
+one link by id, slug or short code
+
+```bash
+trackrev links get black-friday
+```
+
+#### `trackrev links update <id>`
+
+change a link's slug, UTMs, expiry, password or targeting
+
+```bash
+trackrev links update <id> --expires 2026-12-31T23:59:59Z --max-clicks 1000
+```
+
+| flag | meaning |
+| --- | --- |
+| `--term TEXT` | utm_term |
+| `--content TEXT` | utm_content |
+| `--clear-password` | remove the password |
+| `--clear-expiry` | remove date and click-cap expiry |
+| `--slug SLUG` | custom slug (2–64 chars; lowercase, digits, hyphens) |
+| `--campaign TEXT` | utm_campaign (defaults to the name) |
+| `--expires ISO` | expire at this time |
+| `--max-clicks N` | expire after this many clicks |
+| `--expired-url URL` | where to send visitors after expiry |
+| `--password TEXT` | require this password before redirecting |
+| `--mobile-url URL` | device targeting: send mobile here |
+| `--desktop-url URL` | device targeting: send desktop here |
+| `--retarget on\|off` | fire the workspace's ad pixels on click |
+
+#### `trackrev links delete <id>`
+
+delete one link (its campaign and other channels stay) _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev links delete <id> --yes
+```
+
+#### `trackrev links bulk`
+
+create up to 500 links from a CSV
+
+```bash
+trackrev links bulk --file links.csv
+```
+
+| flag | meaning |
+| --- | --- |
+| `--file PATH` | CSV with url, name, channel columns (- for stdin) |
+
+Optional columns: utm_campaign, utm_term, utm_content, tags, campaign_id. Rows that fail are listed with the reason; the rest are created.
+
+#### `trackrev links qr <id-or-slug>`
+
+the link's QR code as SVG
+
+```bash
+trackrev links qr black-friday --out black-friday.svg
+```
+
+| flag | meaning |
+| --- | --- |
+| `--out PATH` | write here instead of stdout |
+| `--size N` | size in px (default 512, max 2048) |
+
+### Developers
+
+#### `trackrev keys list`
+
+the workspace's API keys (prefixes only)
+
+```bash
+trackrev keys list --revoked
+```
+
+| flag | meaning |
+| --- | --- |
+| `--revoked` | include revoked keys |
+
+#### `trackrev keys create`
+
+mint a key — the plaintext is shown once, never again
+
+```bash
+trackrev keys create --label 'CI deploy'
+```
+
+| flag | meaning |
+| --- | --- |
+| `--scope SCOPE` | secret (servers, CLI) or public (browser) |
+| `--label TEXT` | what this key is for |
+
+The key goes to stdout and everything else to stderr, so `trackrev keys create > key.txt` captures only the key.
+
+#### `trackrev keys revoke <id>`
+
+revoke a key immediately _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev keys revoke <id> --yes
+```
+
+#### `trackrev webhooks list`
+
+outbound endpoints, with their last delivery status
 
 ```bash
-trackrev channels                # last 30 days
-trackrev channels --days 7
-trackrev channels --ltv          # add all-time lifetime value per channel
+trackrev webhooks list
 ```
 
+#### `trackrev webhooks events`
+
+every event an endpoint can subscribe to
+
+```bash
+trackrev webhooks events
 ```
-channel     clicks  visitors  conversions   revenue
-youtube      1,204       980        12.50  2,410.50
-newsletter     310       287         9.00  1,890.00
+
+#### `trackrev webhooks create`
+
+add an endpoint — the signing secret is shown once
+
+```bash
+trackrev webhooks create --url https://acme.com/hook --event sale.created
 ```
 
-`conversions` is a decimal because attribution splits credit — one sale touched by two channels
-counts 0.5 on each.
+| flag | meaning |
+| --- | --- |
+| `--url URL` | https endpoint (required) |
+| `--event NAME` | an event; repeat for several |
+
+https only. Run `trackrev webhooks events` for the valid names.
+
+#### `trackrev webhooks update <id>`
 
-### `links` — performance per short link
+change the URL or events, or pause and resume delivery
 
 ```bash
-trackrev links --limit 20
-trackrev links --from 2026-01-01 --to 2026-02-01
+trackrev webhooks update <id> --pause
 ```
 
-### `clicks` — the raw click stream
+| flag | meaning |
+| --- | --- |
+| `--url URL` | new endpoint URL |
+| `--event NAME` | replace the event list; repeat |
+| `--pause` | stop delivering |
+| `--resume` | start delivering again |
 
-Newest first, bots excluded, cursor-paginated.
+#### `trackrev webhooks delete <id>`
+
+remove an endpoint _(asks to confirm; `--yes` in scripts)_
 
 ```bash
-trackrev clicks                        # most recent 100
-trackrev clicks --limit 500            # one page, max size
-trackrev clicks --all                  # follow the cursor to the end
-trackrev clicks --link <link-id>       # one link only
-trackrev clicks --bots                 # include bot traffic
+trackrev webhooks delete <id> --yes
 ```
 
-`--all` stops after 200 pages and says so on stderr, so a runaway cursor can't loop forever.
+### Setup
+
+#### `trackrev attribution get`
 
-### `journey` — one visitor's timeline
+the model and lookback window this workspace uses
 
 ```bash
-trackrev journey 3f1b8c22-9d4e-4a71-b8c0-2e6f5a91d7e4
+trackrev attribution get --models
 ```
 
-Every click, identify event and order in order. The visitor id is the `visitor_id` column from
-`trackrev clicks`.
+| flag | meaning |
+| --- | --- |
+| `--models` | list the three models and what each credits |
 
-## Window
+#### `trackrev attribution set`
 
-`channels` and `links` accept:
+change the model or the window
+
+```bash
+trackrev attribution set --model linear --window 60
+```
 
 | flag | meaning |
 | --- | --- |
+| `--model NAME` | last_touch, first_touch or linear |
+| `--window N` | lookback in days (1-365) |
+
+Both settings apply retroactively — every past order is re-credited against them.
+
+#### `trackrev folders list`
+
+campaign folders, with how many campaigns each holds
+
+```bash
+trackrev folders list
+```
+
+#### `trackrev folders create`
+
+create a folder to group campaigns under
+
+```bash
+trackrev folders create --name 'Q4 launch' --start 2026-10-01
+```
+
+| flag | meaning |
+| --- | --- |
+| `--name TEXT` | folder name (required) |
+| `--description TEXT` | what it covers |
+| `--start YYYY-MM-DD` | start date |
+| `--end YYYY-MM-DD` | end date |
+
+#### `trackrev folders update <id>`
+
+rename a folder or change its dates
+
+```bash
+trackrev folders update <id> --name 'Q1 launch'
+```
+
+| flag | meaning |
+| --- | --- |
+| `--name TEXT` | new name |
+| `--description TEXT` | new description |
+| `--start YYYY-MM-DD` | start date |
+| `--end YYYY-MM-DD` | end date |
+
+#### `trackrev folders delete <id>`
+
+delete a folder — its campaigns become ungrouped, not deleted _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev folders delete <id> --yes
+```
+
+#### `trackrev folders assign <destination-id>`
+
+file a campaign under a folder, or un-file it
+
+```bash
+trackrev folders assign <destination-id> --folder <folder-id>
+```
+
+| flag | meaning |
+| --- | --- |
+| `--folder ID` | folder to file under; omit to un-file |
+
+The id is a CAMPAIGN (the destination behind a set of links), not a single link.
+
+### Revenue
+
+#### `trackrev revenue list`
+
+connected payment providers and their last sync
+
+```bash
+trackrev revenue list
+```
+
+#### `trackrev revenue providers`
+
+what can be connected, and the credentials each needs
+
+```bash
+trackrev revenue providers
+```
+
+Stripe is absent by design — its restricted key lives on the workspace, not here.
+
+#### `trackrev revenue connect`
+
+connect a provider — credentials are verified before saving
+
+```bash
+trackrev revenue connect --provider polar --field api_key=polar_oat_…
+```
+
+| flag | meaning |
+| --- | --- |
+| `--provider NAME` | polar, lemonsqueezy, paddle, creem or dodo |
+| `--field K=V` | credential as key=value; repeat per field |
+| `--sandbox` | use the provider's sandbox host, where it has one |
+
+#### `trackrev revenue sync`
+
+pull charges now and attribute them _(paid plan)_
+
+```bash
+trackrev revenue sync
+```
+
+| flag | meaning |
+| --- | --- |
+| `--connection ID` | one connection only; omit for all + Stripe |
+
+Reports imported and attributed per provider. A provider that fails does not stop the others.
+
+#### `trackrev revenue disconnect <id>`
+
+disconnect a provider; imported orders are kept _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev revenue disconnect <id> --yes
+```
+
+### Audience
+
+#### `trackrev visitors list`
+
+visitors, most recently seen first _(paid plan)_
+
+```bash
+trackrev visitors list --email @acme.com
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | page size (default 100, max 500) |
+| `--all` | follow the cursor to the end |
+| `--email TEXT` | email contains this text |
+
+#### `trackrev visitors get <id>`
+
+one visitor _(paid plan)_
+
+```bash
+trackrev visitors get <id>
+```
+
+#### `trackrev orders list`
+
+synced purchases, newest first
+
+```bash
+trackrev orders list --status refunded
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | page size (default 100, max 500) |
+| `--all` | follow the cursor to the end |
+| `--status NAME` | paid or refunded |
+| `--email TEXT` | email contains this text |
+
+amount is blank on the free plan, where revenue figures are hidden.
+
+#### `trackrev export`
+
+any dataset as CSV _(paid plan)_
+
+```bash
+trackrev export --kind orders --days 90 --out orders.csv
+```
+
+| flag | meaning |
+| --- | --- |
+| `--kind NAME` | channels, links, orders or visitors |
+| `--out PATH` | write here instead of stdout |
 | `--days N` | last N days (default 30, max 365) |
-| `--from ISO` | explicit start, e.g. `2026-01-01` |
+| `--from ISO` | explicit start, e.g. 2026-01-01; wins over --days |
 | `--to ISO` | explicit end (defaults to now) |
 
-`--from`/`--to` win over `--days`.
+### Domains
+
+#### `trackrev domains list`
+
+branded short-link domains and their DNS status
+
+```bash
+trackrev domains list
+```
+
+#### `trackrev domains add <domain>`
+
+attach a domain — prints the DNS records to add
+
+```bash
+trackrev domains add go.acme.com
+```
+
+#### `trackrev domains verify <domain-or-id>`
+
+re-check DNS now; exits non-zero until it is active
+
+```bash
+trackrev domains verify go.acme.com
+```
+
+Exits 1 while still pending, so a deploy script can poll until it passes.
+
+#### `trackrev domains remove <domain-or-id>`
+
+detach a domain; links keep working on the default host _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev domains remove go.acme.com --yes
+```
+
+#### `trackrev retargeting list`
+
+the ad pixels fired on opted-in link clicks
+
+```bash
+trackrev retargeting list --providers
+```
+
+| flag | meaning |
+| --- | --- |
+| `--providers` | show what can be configured instead |
+
+#### `trackrev retargeting set <provider>`
+
+set a provider's pixel id
+
+```bash
+trackrev retargeting set meta --id 1234567890123456
+```
+
+| flag | meaning |
+| --- | --- |
+| `--id ID` | the pixel/tag id (required) |
+
+The id must match that provider's shape — only validated ids are ever put into a loader snippet.
+
+#### `trackrev retargeting remove <provider>`
+
+remove a provider's pixel _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev retargeting remove meta --yes
+```
+
+### Affiliate
+
+#### `trackrev programs list`
+
+the workspace's affiliate programs and their terms
+
+```bash
+trackrev programs list --archived
+```
+
+| flag | meaning |
+| --- | --- |
+| `--archived` | include archived programs |
+
+#### `trackrev programs get <id>`
+
+one program in full
+
+```bash
+trackrev programs get <id>
+```
+
+#### `trackrev programs update <id>`
+
+change commission terms, or pause and archive _(paid plan)_
+
+```bash
+trackrev programs update <id> --rate 0.25 --status paused
+```
+
+| flag | meaning |
+| --- | --- |
+| `--name TEXT` | program name |
+| `--landing-url URL` | where partner links point |
+| `--type TYPE` | percent or flat |
+| `--rate N` | 0-1 fraction for percent (0.25 = 25%), dollars for flat |
+| `--recurring N` | months a commission keeps paying |
+| `--cookie N` | attribution window in days |
+| `--min-payout N` | minimum balance before a payout |
+| `--auto-approve on\|off` | approve signups instantly |
+| `--status NAME` | active, paused or archived |
+
+Changes apply to NEW conversions; commissions already earned are untouched.
+
+#### `trackrev partners list`
+
+affiliates with their clicks, sales and earnings _(paid plan)_
+
+```bash
+trackrev partners list --status pending
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | one program only |
+| `--status NAME` | pending, approved, rejected, banned or archived |
+
+#### `trackrev partners approve <partner-id>`
+
+approve a pending affiliate _(paid plan)_
+
+```bash
+trackrev partners approve <partner-id> --program <program-id>
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | the program id (required) |
+
+Does NOT send the approval email the dashboard sends — a re-run would mail them again.
+
+#### `trackrev partners reject <partner-id>`
+
+reject an application _(paid plan)_ _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev partners reject <partner-id> --program <program-id> --yes
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | the program id (required) |
+
+#### `trackrev partners ban <partner-id>`
+
+ban an affiliate _(paid plan)_ _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev partners ban <partner-id> --program <program-id> --yes
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | the program id (required) |
+
+#### `trackrev partners group <partner-id>`
+
+move an affiliate into a group, or back to program terms _(paid plan)_
+
+```bash
+trackrev partners group <partner-id> --program <program-id> --group <group-id>
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | the program id (required) |
+| `--group ID` | group to move them to; omit to clear |
+
+#### `trackrev groups list <program-id>`
+
+a program's tiers, showing the terms each one resolves to _(paid plan)_
+
+```bash
+trackrev groups list <program-id>
+```
+
+### Money
+
+#### `trackrev commissions list`
+
+the commission ledger, newest first _(paid plan)_
+
+```bash
+trackrev commissions list --status pending
+```
+
+| flag | meaning |
+| --- | --- |
+| `--limit N` | rows to return (max 500) |
+| `--status NAME` | pending, eligible, paid, refunded, void or fraud |
+| `--partner ID` | one affiliate only |
+
+level 1 is the affiliate who sold; 2+ is an upline earning from their network.
+
+#### `trackrev commissions add`
+
+record an off-platform deal by hand _(paid plan)_
+
+```bash
+trackrev commissions add --program <id> --partner <id> --amount 500 --earnings 100
+```
+
+| flag | meaning |
+| --- | --- |
+| `--program ID` | program id (required) |
+| `--partner ID` | affiliate id (required) |
+| `--amount N` | gross sale value (required) |
+| `--earnings N` | the affiliate's cut (required) |
+| `--currency CODE` | defaults to usd |
+| `--notes TEXT` | why this was entered by hand |
+
+Earnings is not derived — a manual commission exists because the normal rate did not apply. It counts toward your monthly commission cap.
+
+#### `trackrev commissions void <id>`
+
+void a commission entered in error _(paid plan)_ _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev commissions void <id> --yes
+```
+
+| flag | meaning |
+| --- | --- |
+| `--status NAME` | set another status instead of void |
+
+Refused if it is already on a payout batch — cancel the payout first.
+
+#### `trackrev payouts list`
+
+payout batches, with open and all-time totals _(paid plan)_
+
+```bash
+trackrev payouts list --status pending
+```
+
+| flag | meaning |
+| --- | --- |
+| `--status NAME` | pending, processing, paid, failed or canceled |
+| `--limit N` | rows to return (max 500) |
+
+Creating a batch stays in the dashboard: it applies per-group payout floors and platform fees, and a second implementation would eventually pay someone wrong.
+
+#### `trackrev payouts mark-paid <id>`
+
+settle a payout sent off-platform _(paid plan)_ _(asks to confirm; `--yes` in scripts)_
+
+```bash
+trackrev payouts mark-paid <id> --reference PAYPAL-BATCH-123 --yes
+```
+
+| flag | meaning |
+| --- | --- |
+| `--reference TEXT` | the rail's own id (PayPal batch, Wise transfer) |
+
+Does NOT email the affiliate — the dashboard sends that, and a re-run would send it twice.
+
+### Settings
+
+#### `trackrev settings notifications`
+
+every transactional email, and whether it is on
+
+```bash
+trackrev settings notifications
+```
+
+default=yes means no override is stored and the catalogue default applies.
+
+#### `trackrev settings notify <key>`
+
+turn one transactional email on or off
+
+```bash
+trackrev settings notify affiliate.approved --off
+```
+
+| flag | meaning |
+| --- | --- |
+| `--on` | enable it |
+| `--off` | disable it |
+
+#### `trackrev settings branding`
+
+the white-label settings affiliates see
+
+```bash
+trackrev settings branding
+```
+
+#### `trackrev settings set-branding`
+
+set the partner-facing logo and accent colour
+
+```bash
+trackrev settings set-branding --color '#e63e2e'
+```
+
+| flag | meaning |
+| --- | --- |
+| `--logo URL` | https logo URL |
+| `--color HEX` | hex accent, e.g. #e63e2e |
+| `--clear-logo` | back to the TrackRev logo |
+| `--clear-color` | back to the TrackRev colour |
+
+The affiliate subdomain is read-only here — claiming one is a namespace reservation and belongs in one place.
+
+### Account
+
+#### `trackrev me`
+
+which workspace, plan, limits and key you're using
+
+```bash
+trackrev me
+```
+
+#### `trackrev login`
+
+save a secret key so you don't need TRACKREV_KEY
+
+```bash
+trackrev login --profile staging --api-url https://staging.example.com/api/v1
+```
+
+| flag | meaning |
+| --- | --- |
+| `--key lk_…` | the key (prompted, hidden, when omitted) |
+| `--api-url URL` | API base for this profile |
+
+Stored at ~/.config/trackrev/config.json with mode 0600. TRACKREV_KEY in the environment always wins, for CI.
+
+#### `trackrev logout`
+
+forget a saved key
+
+```bash
+trackrev logout
+```
+
+### Global flags
+
+| flag | meaning |
+| --- | --- |
+| `--json` | print the API's JSON instead of a table |
+| `--profile NAME` | use a saved login other than the current one |
+| `--yes` | skip the confirmation on destructive commands |
+| `--version` | print the version |
+| `--help` | show help (also: trackrev <command> --help) |
+<!-- cli:commands:end -->
 
 ## Output
 
-The same data comes out three ways, so the command works both as something you read and as
+The same data comes out three ways, so a command works both as something you read and as
 something you pipe:
 
 ```bash
@@ -99,22 +1004,63 @@ trackrev channels > channels.tsv     # tab-separated, raw values (a pipe or file
 trackrev channels --json | jq .      # the API's own JSON body
 ```
 
-Piped output is deliberately unformatted — `2410.5`, not `2,410.50` — so `cut` and `awk` see real
-numbers:
+Piped output is deliberately unformatted — `2410.5`, not `2,410.50`, and `true` rather than
+`yes` — so `cut` and `awk` see real values:
 
 ```bash
 trackrev channels | cut -f1,5
-trackrev links --limit 10 | column -t
+trackrev links list | column -t
 trackrev clicks --all --json | jq '.clicks[] | select(.country == "BD")'
 ```
 
-Warnings, errors and the `journey` caption always go to **stderr**, never into your pipe.
+Warnings, errors, confirmations and the `journey` caption always go to **stderr**, never into
+your pipe.
+
+## Recipes
+
+```bash
+# One link per channel for a launch, then print just the shareable URLs
+trackrev links create --url https://acme.com/launch --name Launch \
+  --channel youtube --channel newsletter --channel twitter | cut -f3
+
+# A link that dies after 1,000 clicks and sends latecomers to the waitlist
+trackrev links create --url https://acme.com/beta --name Beta --channel newsletter \
+  --max-clicks 1000 --expired-url https://acme.com/waitlist
+
+# Import a quarter's worth of links from a spreadsheet export
+trackrev links bulk --file q4-links.csv
+
+# Your five best links by revenue this month
+trackrev links perf --limit 100 | tail -n +2 | sort -t$'\t' -k6,6nr | head -5
+
+# Follow the newest click through to that visitor's whole journey
+trackrev clicks --limit 1 | tail -1 | cut -f6 | xargs trackrev journey
+
+# Nightly export
+trackrev clicks --all --json > "clicks-$(date +%F).json"
+```
 
 ## Exit codes
 
 | code | meaning |
 | --- | --- |
 | `0` | success |
-| `1` | no API key, auth failure, plan gate, network error, API error |
-| `2` | usage error — unknown flag or command, bad `--limit`, missing visitor id |
+| `1` | no API key, auth failure, network error, not found, API error |
+| `2` | usage error — unknown flag or command, bad value, missing argument, refused confirmation |
+| `3` | plan required — the workspace needs a paid plan for this command |
+
+Exit `3` is separate so CI can tell "you are on the wrong plan" apart from "the call broke".
+
+## Development
+
+```bash
+node --test test/*.test.js   # the full suite, against a mock API — no network, no credentials
+pnpm sync-docs       # regenerate the command tables in this file and the docs site
+```
+
+The test glob is pinned: a bare `node --test` also runs every other file under `test/`,
+and `mock-api.mjs` is a server that never exits.
 
+Commands are declared once in [`src/registry.js`](src/registry.js). The help text, the argument
+parser, the tables above, the `/cli` marketing page and the Settings → Developers panel are all
+derived from it — add a command there and a handler in `src/commands/`, then run `pnpm sync-docs`.