trackrev 0.1.0 → 0.2.0

package/src/registry.js

@@ -0,0 +1,840 @@
+// The single source of truth for what the CLI can do.
+//
+// Everything that describes a command lives here and nowhere else: the
+// parseArgs option spec, the help text, the flag table on /cli, the reminder
+// list in Settings → Developers, and the generated blocks in README.md and the
+// docs site are all derived from this array. Add a command by adding an entry
+// and its handler; nothing else needs to learn about it.
+//
+// Plain data + pure functions on purpose — the web app imports this file too,
+// so it must not touch process, fs, or fetch.
+
+/**
+ * Declared here rather than read from package.json at import time.
+ *
+ * This module is imported by the Next app (the /cli page and the developers
+ * panel render their tables from it). Next traces the files a route needs into
+ * its serverless bundle, and apps/cli/package.json sits outside apps/web, so a
+ * `createRequire(import.meta.url)("../package.json")` compiles fine and then
+ * throws at runtime — a 500 on /cli that no build step catches.
+ *
+ * Kept honest by a test that asserts this matches package.json.
+ */
+export const VERSION = "0.2.0";
+
+/** A flag definition. `arg` is the placeholder shown in help ("N", "ISO", "ID"). */
+const flag = (name, type, meaning, extra = {}) => ({ name, type, meaning, ...extra });
+
+export const GLOBAL_FLAGS = [
+  flag("json", "boolean", "print the API's JSON instead of a table"),
+  flag("profile", "string", "use a saved login other than the current one", { arg: "NAME" }),
+  flag("yes", "boolean", "skip the confirmation on destructive commands"),
+  flag("version", "boolean", "print the version"),
+  flag("help", "boolean", "show help (also: trackrev <command> --help)"),
+];
+
+const WINDOW_FLAGS = [
+  flag("days", "string", "last N days (default 30, max 365)", { arg: "N", default: "30" }),
+  flag("from", "string", "explicit start, e.g. 2026-01-01; wins over --days", { arg: "ISO" }),
+  flag("to", "string", "explicit end (defaults to now)", { arg: "ISO" }),
+];
+
+const LIMIT = (meaning) => flag("limit", "string", meaning, { arg: "N" });
+
+// Flags shared by `links create` and `links update`.
+const LINK_SETTING_FLAGS = [
+  flag("slug", "string", "custom slug (2–64 chars; lowercase, digits, hyphens)", { arg: "SLUG" }),
+  flag("campaign", "string", "utm_campaign (defaults to the name)", { arg: "TEXT" }),
+  flag("expires", "string", "expire at this time", { arg: "ISO" }),
+  flag("max-clicks", "string", "expire after this many clicks", { arg: "N" }),
+  flag("expired-url", "string", "where to send visitors after expiry", { arg: "URL" }),
+  flag("password", "string", "require this password before redirecting", { arg: "TEXT" }),
+  flag("mobile-url", "string", "device targeting: send mobile here", { arg: "URL" }),
+  flag("desktop-url", "string", "device targeting: send desktop here", { arg: "URL" }),
+  flag("retarget", "string", "fire the workspace's ad pixels on click", { arg: "on|off" }),
+];
+
+/**
+ * Every command. `verb: null` means the noun alone is the command (kept for
+ * the original analytics commands so existing scripts don't break).
+ *   args         positional placeholders, in order
+ *   module       file under src/commands/ exporting `handler`
+ *   paid         needs a paid plan (the API 402s otherwise)
+ *   destructive  asks for confirmation unless --yes
+ *   aliases      extra top-level words that resolve to this command
+ *   bareNoun     the noun alone also runs this command (`links` → `links perf`)
+ */
+export const COMMANDS = [
+  /* ── Analytics (paid) ─────────────────────────────────────────────────── */
+  {
+    noun: "channels", verb: null, group: "Analytics",
+    summary: "performance per traffic source",
+    example: "trackrev channels --days 7 --ltv",
+    args: [],
+    flags: [...WINDOW_FLAGS, flag("ltv", "boolean", "add all-time lifetime value per channel")],
+    module: "analytics", handler: "channels", paid: true,
+    note: "conversions is a decimal on purpose — attribution splits credit, so one sale touched by two channels counts 0.5 on each.",
+  },
+  {
+    noun: "links", verb: "perf", group: "Analytics",
+    summary: "performance per short link (bare `trackrev links` still works)",
+    example: "trackrev links perf --limit 20",
+    args: [],
+    flags: [
+      LIMIT("rows to return (max 500)"),
+      ...WINDOW_FLAGS,
+      flag("settings", "boolean", "attach each link's URL, expiry and password flag"),
+    ],
+    module: "analytics", handler: "linksPerf", paid: true, bareNoun: true,
+  },
+  {
+    noun: "clicks", verb: null, group: "Analytics",
+    summary: "the raw click stream — newest first, bots excluded",
+    example: "trackrev clicks --all --json",
+    args: [],
+    flags: [
+      LIMIT("page size (default 100, max 500)"),
+      flag("all", "boolean", "follow the cursor to the end of the stream"),
+      flag("link", "string", "one link only", { arg: "ID" }),
+      flag("bots", "boolean", "include bot traffic"),
+    ],
+    module: "analytics", handler: "clicks", paid: true,
+    note: "--all stops after 200 pages and says so on stderr, so a runaway cursor can never loop forever.",
+  },
+  {
+    noun: "visitors", verb: "journey", group: "Analytics",
+    summary: "one visitor's timeline — every click, identify event and order, in order",
+    example: "trackrev journey <visitor-id>",
+    args: ["visitor-id"],
+    flags: [],
+    module: "analytics", handler: "journey", paid: true, aliases: ["journey"],
+    note: "The visitor caption goes to stderr, so the rows stay pipe-clean.",
+  },
+
+  /* ── Links (any plan) ─────────────────────────────────────────────────── */
+  {
+    noun: "links", verb: "list", group: "Links",
+    summary: "the links themselves — newest first, no window",
+    example: "trackrev links list --channel youtube",
+    args: [],
+    flags: [
+      LIMIT("page size (default 100, max 500)"),
+      flag("all", "boolean", "follow the cursor to the end"),
+      flag("channel", "string", "one channel only", { arg: "KEY" }),
+      flag("q", "string", "slug contains this text", { arg: "TEXT" }),
+    ],
+    module: "links", handler: "list", paid: false,
+  },
+  {
+    noun: "links", verb: "create", group: "Links",
+    summary: "create a campaign: one link per channel, or one Smart Link",
+    example: "trackrev links create --url https://acme.com/launch --name Launch --channel youtube --channel newsletter",
+    args: [],
+    flags: [
+      flag("url", "string", "destination (required)", { arg: "URL" }),
+      flag("name", "string", "campaign name (required)", { arg: "TEXT" }),
+      flag("channel", "string", "a channel; repeat for several", { arg: "KEY", multiple: true }),
+      flag("smart", "boolean", "one link that infers its channel per click"),
+      flag("tag", "string", "a tag; repeat for several", { arg: "TEXT", multiple: true }),
+      flag("folder", "string", "put the campaign in this folder", { arg: "ID" }),
+      flag("external", "boolean", "destination is a site you can't put the pixel on"),
+      ...LINK_SETTING_FLAGS,
+    ],
+    module: "links", handler: "create", paid: false,
+    note: "Prints one row per link created. Channels: facebook instagram youtube linkedin twitter tiktok newsletter website other.",
+  },
+  {
+    noun: "links", verb: "get", group: "Links",
+    summary: "one link by id, slug or short code",
+    example: "trackrev links get black-friday",
+    args: ["id-or-slug"],
+    flags: [],
+    module: "links", handler: "get", paid: false,
+  },
+  {
+    noun: "links", verb: "update", group: "Links",
+    summary: "change a link's slug, UTMs, expiry, password or targeting",
+    example: "trackrev links update <id> --expires 2026-12-31T23:59:59Z --max-clicks 1000",
+    args: ["id"],
+    flags: [
+      flag("term", "string", "utm_term", { arg: "TEXT" }),
+      flag("content", "string", "utm_content", { arg: "TEXT" }),
+      flag("clear-password", "boolean", "remove the password"),
+      flag("clear-expiry", "boolean", "remove date and click-cap expiry"),
+      ...LINK_SETTING_FLAGS,
+    ],
+    module: "links", handler: "update", paid: false,
+  },
+  {
+    noun: "links", verb: "delete", group: "Links",
+    summary: "delete one link (its campaign and other channels stay)",
+    example: "trackrev links delete <id> --yes",
+    args: ["id"],
+    flags: [],
+    module: "links", handler: "remove", paid: false, destructive: true,
+  },
+  {
+    noun: "links", verb: "bulk", group: "Links",
+    summary: "create up to 500 links from a CSV",
+    example: "trackrev links bulk --file links.csv",
+    args: [],
+    flags: [flag("file", "string", "CSV with url, name, channel columns (- for stdin)", { arg: "PATH" })],
+    module: "links", handler: "bulk", paid: false,
+    note: "Optional columns: utm_campaign, utm_term, utm_content, tags, campaign_id. Rows that fail are listed with the reason; the rest are created.",
+  },
+  {
+    noun: "links", verb: "qr", group: "Links",
+    summary: "the link's QR code as SVG",
+    example: "trackrev links qr black-friday --out black-friday.svg",
+    args: ["id-or-slug"],
+    flags: [
+      flag("out", "string", "write here instead of stdout", { arg: "PATH" }),
+      flag("size", "string", "size in px (default 512, max 2048)", { arg: "N" }),
+    ],
+    module: "links", handler: "qr", paid: false,
+  },
+
+  /* ── Developers (any plan) ────────────────────────────────────────────── */
+  {
+    noun: "keys", verb: "list", group: "Developers",
+    summary: "the workspace's API keys (prefixes only)",
+    example: "trackrev keys list --revoked",
+    args: [],
+    flags: [flag("revoked", "boolean", "include revoked keys")],
+    module: "keys", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "keys", verb: "create", group: "Developers",
+    summary: "mint a key — the plaintext is shown once, never again",
+    example: "trackrev keys create --label 'CI deploy'",
+    args: [],
+    flags: [
+      flag("scope", "string", "secret (servers, CLI) or public (browser)", { arg: "SCOPE" }),
+      flag("label", "string", "what this key is for", { arg: "TEXT" }),
+    ],
+    module: "keys", handler: "create", paid: false,
+    note: "The key goes to stdout and everything else to stderr, so `trackrev keys create > key.txt` captures only the key.",
+  },
+  {
+    noun: "keys", verb: "revoke", group: "Developers",
+    summary: "revoke a key immediately",
+    example: "trackrev keys revoke <id> --yes",
+    args: ["id"],
+    flags: [],
+    module: "keys", handler: "revoke", paid: false, destructive: true,
+  },
+  {
+    noun: "webhooks", verb: "list", group: "Developers",
+    summary: "outbound endpoints, with their last delivery status",
+    example: "trackrev webhooks list",
+    args: [],
+    flags: [],
+    module: "webhooks", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "webhooks", verb: "events", group: "Developers",
+    summary: "every event an endpoint can subscribe to",
+    example: "trackrev webhooks events",
+    args: [],
+    flags: [],
+    module: "webhooks", handler: "events", paid: false,
+  },
+  {
+    noun: "webhooks", verb: "create", group: "Developers",
+    summary: "add an endpoint — the signing secret is shown once",
+    example: "trackrev webhooks create --url https://acme.com/hook --event sale.created",
+    args: [],
+    flags: [
+      flag("url", "string", "https endpoint (required)", { arg: "URL" }),
+      flag("event", "string", "an event; repeat for several", { arg: "NAME", multiple: true }),
+    ],
+    module: "webhooks", handler: "create", paid: false,
+    note: "https only. Run `trackrev webhooks events` for the valid names.",
+  },
+  {
+    noun: "webhooks", verb: "update", group: "Developers",
+    summary: "change the URL or events, or pause and resume delivery",
+    example: "trackrev webhooks update <id> --pause",
+    args: ["id"],
+    flags: [
+      flag("url", "string", "new endpoint URL", { arg: "URL" }),
+      flag("event", "string", "replace the event list; repeat", { arg: "NAME", multiple: true }),
+      flag("pause", "boolean", "stop delivering"),
+      flag("resume", "boolean", "start delivering again"),
+    ],
+    module: "webhooks", handler: "update", paid: false,
+  },
+  {
+    noun: "webhooks", verb: "delete", group: "Developers",
+    summary: "remove an endpoint",
+    example: "trackrev webhooks delete <id> --yes",
+    args: ["id"],
+    flags: [],
+    module: "webhooks", handler: "remove", paid: false, destructive: true,
+  },
+
+  /* ── Setup (any plan) ─────────────────────────────────────────────────── */
+  {
+    noun: "attribution", verb: "get", group: "Setup",
+    summary: "the model and lookback window this workspace uses",
+    example: "trackrev attribution get --models",
+    args: [],
+    flags: [flag("models", "boolean", "list the three models and what each credits")],
+    module: "attribution", handler: "get", paid: false, bareNoun: true,
+  },
+  {
+    noun: "attribution", verb: "set", group: "Setup",
+    summary: "change the model or the window",
+    example: "trackrev attribution set --model linear --window 60",
+    args: [],
+    flags: [
+      flag("model", "string", "last_touch, first_touch or linear", { arg: "NAME" }),
+      flag("window", "string", "lookback in days (1-365)", { arg: "N" }),
+    ],
+    module: "attribution", handler: "set", paid: false,
+    note: "Both settings apply retroactively — every past order is re-credited against them.",
+  },
+  {
+    noun: "folders", verb: "list", group: "Setup",
+    summary: "campaign folders, with how many campaigns each holds",
+    example: "trackrev folders list",
+    args: [],
+    flags: [],
+    module: "folders", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "folders", verb: "create", group: "Setup",
+    summary: "create a folder to group campaigns under",
+    example: "trackrev folders create --name 'Q4 launch' --start 2026-10-01",
+    args: [],
+    flags: [
+      flag("name", "string", "folder name (required)", { arg: "TEXT" }),
+      flag("description", "string", "what it covers", { arg: "TEXT" }),
+      flag("start", "string", "start date", { arg: "YYYY-MM-DD" }),
+      flag("end", "string", "end date", { arg: "YYYY-MM-DD" }),
+    ],
+    module: "folders", handler: "create", paid: false,
+  },
+  {
+    noun: "folders", verb: "update", group: "Setup",
+    summary: "rename a folder or change its dates",
+    example: "trackrev folders update <id> --name 'Q1 launch'",
+    args: ["id"],
+    flags: [
+      flag("name", "string", "new name", { arg: "TEXT" }),
+      flag("description", "string", "new description", { arg: "TEXT" }),
+      flag("start", "string", "start date", { arg: "YYYY-MM-DD" }),
+      flag("end", "string", "end date", { arg: "YYYY-MM-DD" }),
+    ],
+    module: "folders", handler: "update", paid: false,
+  },
+  {
+    noun: "folders", verb: "delete", group: "Setup",
+    summary: "delete a folder — its campaigns become ungrouped, not deleted",
+    example: "trackrev folders delete <id> --yes",
+    args: ["id"],
+    flags: [],
+    module: "folders", handler: "remove", paid: false, destructive: true,
+  },
+  {
+    noun: "folders", verb: "assign", group: "Setup",
+    summary: "file a campaign under a folder, or un-file it",
+    example: "trackrev folders assign <destination-id> --folder <folder-id>",
+    args: ["destination-id"],
+    flags: [flag("folder", "string", "folder to file under; omit to un-file", { arg: "ID" })],
+    module: "folders", handler: "assign", paid: false,
+    note: "The id is a CAMPAIGN (the destination behind a set of links), not a single link.",
+  },
+
+  /* ── Revenue ──────────────────────────────────────────────────────────── */
+  {
+    noun: "revenue", verb: "list", group: "Revenue",
+    summary: "connected payment providers and their last sync",
+    example: "trackrev revenue list",
+    args: [],
+    flags: [],
+    module: "revenue", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "revenue", verb: "providers", group: "Revenue",
+    summary: "what can be connected, and the credentials each needs",
+    example: "trackrev revenue providers",
+    args: [],
+    flags: [],
+    module: "revenue", handler: "providers", paid: false,
+    note: "Stripe is absent by design — its restricted key lives on the workspace, not here.",
+  },
+  {
+    noun: "revenue", verb: "connect", group: "Revenue",
+    summary: "connect a provider — credentials are verified before saving",
+    example: "trackrev revenue connect --provider polar --field api_key=polar_oat_…",
+    args: [],
+    flags: [
+      flag("provider", "string", "polar, lemonsqueezy, paddle, creem or dodo", { arg: "NAME" }),
+      flag("field", "string", "credential as key=value; repeat per field", { arg: "K=V", multiple: true }),
+      flag("sandbox", "boolean", "use the provider's sandbox host, where it has one"),
+    ],
+    module: "revenue", handler: "connect", paid: false,
+  },
+  {
+    noun: "revenue", verb: "sync", group: "Revenue",
+    summary: "pull charges now and attribute them",
+    example: "trackrev revenue sync",
+    args: [],
+    flags: [flag("connection", "string", "one connection only; omit for all + Stripe", { arg: "ID" })],
+    module: "revenue", handler: "sync", paid: true,
+    note: "Reports imported and attributed per provider. A provider that fails does not stop the others.",
+  },
+  {
+    noun: "revenue", verb: "disconnect", group: "Revenue",
+    summary: "disconnect a provider; imported orders are kept",
+    example: "trackrev revenue disconnect <id> --yes",
+    args: ["id"],
+    flags: [],
+    module: "revenue", handler: "disconnect", paid: false, destructive: true,
+  },
+
+  /* ── Audience ─────────────────────────────────────────────────────────── */
+  {
+    noun: "visitors", verb: "list", group: "Audience",
+    summary: "visitors, most recently seen first",
+    example: "trackrev visitors list --email @acme.com",
+    args: [],
+    flags: [
+      LIMIT("page size (default 100, max 500)"),
+      flag("all", "boolean", "follow the cursor to the end"),
+      flag("email", "string", "email contains this text", { arg: "TEXT" }),
+    ],
+    module: "people", handler: "visitors", paid: true, bareNoun: true,
+  },
+  {
+    noun: "visitors", verb: "get", group: "Audience",
+    summary: "one visitor",
+    example: "trackrev visitors get <id>",
+    args: ["id"],
+    flags: [],
+    module: "people", handler: "visitor", paid: true,
+  },
+  {
+    noun: "orders", verb: "list", group: "Audience",
+    summary: "synced purchases, newest first",
+    example: "trackrev orders list --status refunded",
+    args: [],
+    flags: [
+      LIMIT("page size (default 100, max 500)"),
+      flag("all", "boolean", "follow the cursor to the end"),
+      flag("status", "string", "paid or refunded", { arg: "NAME" }),
+      flag("email", "string", "email contains this text", { arg: "TEXT" }),
+    ],
+    module: "people", handler: "orders", paid: false, bareNoun: true,
+    note: "amount is blank on the free plan, where revenue figures are hidden.",
+  },
+  {
+    noun: "export", verb: null, group: "Audience",
+    summary: "any dataset as CSV",
+    example: "trackrev export --kind orders --days 90 --out orders.csv",
+    args: [],
+    flags: [
+      flag("kind", "string", "channels, links, orders or visitors", { arg: "NAME" }),
+      flag("out", "string", "write here instead of stdout", { arg: "PATH" }),
+      ...WINDOW_FLAGS,
+    ],
+    module: "people", handler: "exportCsv", paid: true,
+  },
+
+  /* ── Domains & pixels ─────────────────────────────────────────────────── */
+  {
+    noun: "domains", verb: "list", group: "Domains",
+    summary: "branded short-link domains and their DNS status",
+    example: "trackrev domains list",
+    args: [],
+    flags: [],
+    module: "domains", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "domains", verb: "add", group: "Domains",
+    summary: "attach a domain — prints the DNS records to add",
+    example: "trackrev domains add go.acme.com",
+    args: ["domain"],
+    flags: [],
+    module: "domains", handler: "add", paid: false,
+  },
+  {
+    noun: "domains", verb: "verify", group: "Domains",
+    summary: "re-check DNS now; exits non-zero until it is active",
+    example: "trackrev domains verify go.acme.com",
+    args: ["domain-or-id"],
+    flags: [],
+    module: "domains", handler: "verify", paid: false,
+    note: "Exits 1 while still pending, so a deploy script can poll until it passes.",
+  },
+  {
+    noun: "domains", verb: "remove", group: "Domains",
+    summary: "detach a domain; links keep working on the default host",
+    example: "trackrev domains remove go.acme.com --yes",
+    args: ["domain-or-id"],
+    flags: [],
+    module: "domains", handler: "remove", paid: false, destructive: true,
+  },
+  {
+    noun: "retargeting", verb: "list", group: "Domains",
+    summary: "the ad pixels fired on opted-in link clicks",
+    example: "trackrev retargeting list --providers",
+    args: [],
+    flags: [flag("providers", "boolean", "show what can be configured instead")],
+    module: "retargeting", handler: "list", paid: false, bareNoun: true,
+  },
+  {
+    noun: "retargeting", verb: "set", group: "Domains",
+    summary: "set a provider's pixel id",
+    example: "trackrev retargeting set meta --id 1234567890123456",
+    args: ["provider"],
+    flags: [flag("id", "string", "the pixel/tag id (required)", { arg: "ID" })],
+    module: "retargeting", handler: "set", paid: false,
+    note: "The id must match that provider's shape — only validated ids are ever put into a loader snippet.",
+  },
+  {
+    noun: "retargeting", verb: "remove", group: "Domains",
+    summary: "remove a provider's pixel",
+    example: "trackrev retargeting remove meta --yes",
+    args: ["provider"],
+    flags: [],
+    module: "retargeting", handler: "remove", paid: false, destructive: true,
+  },
+
+  /* ── Affiliate program ────────────────────────────────────────────────── */
+  {
+    noun: "programs", verb: "list", group: "Affiliate",
+    summary: "the workspace's affiliate programs and their terms",
+    example: "trackrev programs list --archived",
+    args: [],
+    flags: [flag("archived", "boolean", "include archived programs")],
+    module: "affiliates", handler: "programs", paid: false, bareNoun: true,
+  },
+  {
+    noun: "programs", verb: "get", group: "Affiliate",
+    summary: "one program in full",
+    example: "trackrev programs get <id>",
+    args: ["id"],
+    flags: [],
+    module: "affiliates", handler: "program", paid: false,
+  },
+  {
+    noun: "programs", verb: "update", group: "Affiliate",
+    summary: "change commission terms, or pause and archive",
+    example: "trackrev programs update <id> --rate 0.25 --status paused",
+    args: ["id"],
+    flags: [
+      flag("name", "string", "program name", { arg: "TEXT" }),
+      flag("landing-url", "string", "where partner links point", { arg: "URL" }),
+      flag("type", "string", "percent or flat", { arg: "TYPE" }),
+      flag("rate", "string", "0-1 fraction for percent (0.25 = 25%), dollars for flat", { arg: "N" }),
+      flag("recurring", "string", "months a commission keeps paying", { arg: "N" }),
+      flag("cookie", "string", "attribution window in days", { arg: "N" }),
+      flag("min-payout", "string", "minimum balance before a payout", { arg: "N" }),
+      flag("auto-approve", "string", "approve signups instantly", { arg: "on|off" }),
+      flag("status", "string", "active, paused or archived", { arg: "NAME" }),
+    ],
+    module: "affiliates", handler: "updateProgram", paid: true,
+    note: "Changes apply to NEW conversions; commissions already earned are untouched.",
+  },
+  {
+    noun: "partners", verb: "list", group: "Affiliate",
+    summary: "affiliates with their clicks, sales and earnings",
+    example: "trackrev partners list --status pending",
+    args: [],
+    flags: [
+      flag("program", "string", "one program only", { arg: "ID" }),
+      flag("status", "string", "pending, approved, rejected, banned or archived", { arg: "NAME" }),
+    ],
+    module: "affiliates", handler: "partners", paid: true, bareNoun: true,
+  },
+  {
+    noun: "partners", verb: "approve", group: "Affiliate",
+    summary: "approve a pending affiliate",
+    example: "trackrev partners approve <partner-id> --program <program-id>",
+    args: ["partner-id"],
+    flags: [flag("program", "string", "the program id (required)", { arg: "ID" })],
+    module: "affiliates", handler: "approve", paid: true,
+    note: "Does NOT send the approval email the dashboard sends — a re-run would mail them again.",
+  },
+  {
+    noun: "partners", verb: "reject", group: "Affiliate",
+    summary: "reject an application",
+    example: "trackrev partners reject <partner-id> --program <program-id> --yes",
+    args: ["partner-id"],
+    flags: [flag("program", "string", "the program id (required)", { arg: "ID" })],
+    module: "affiliates", handler: "reject", paid: true, destructive: true,
+  },
+  {
+    noun: "partners", verb: "ban", group: "Affiliate",
+    summary: "ban an affiliate",
+    example: "trackrev partners ban <partner-id> --program <program-id> --yes",
+    args: ["partner-id"],
+    flags: [flag("program", "string", "the program id (required)", { arg: "ID" })],
+    module: "affiliates", handler: "ban", paid: true, destructive: true,
+  },
+  {
+    noun: "partners", verb: "group", group: "Affiliate",
+    summary: "move an affiliate into a group, or back to program terms",
+    example: "trackrev partners group <partner-id> --program <program-id> --group <group-id>",
+    args: ["partner-id"],
+    flags: [
+      flag("program", "string", "the program id (required)", { arg: "ID" }),
+      flag("group", "string", "group to move them to; omit to clear", { arg: "ID" }),
+    ],
+    module: "affiliates", handler: "group", paid: true,
+  },
+  {
+    noun: "groups", verb: "list", group: "Affiliate",
+    summary: "a program's tiers, showing the terms each one resolves to",
+    example: "trackrev groups list <program-id>",
+    args: ["program-id"],
+    flags: [],
+    module: "affiliates", handler: "groups", paid: true, bareNoun: true,
+  },
+
+  /* ── Money ────────────────────────────────────────────────────────────── */
+  {
+    noun: "commissions", verb: "list", group: "Money",
+    summary: "the commission ledger, newest first",
+    example: "trackrev commissions list --status pending",
+    args: [],
+    flags: [
+      LIMIT("rows to return (max 500)"),
+      flag("status", "string", "pending, eligible, paid, refunded, void or fraud", { arg: "NAME" }),
+      flag("partner", "string", "one affiliate only", { arg: "ID" }),
+    ],
+    module: "money", handler: "commissions", paid: true, bareNoun: true,
+    note: "level 1 is the affiliate who sold; 2+ is an upline earning from their network.",
+  },
+  {
+    noun: "commissions", verb: "add", group: "Money",
+    summary: "record an off-platform deal by hand",
+    example: "trackrev commissions add --program <id> --partner <id> --amount 500 --earnings 100",
+    args: [],
+    flags: [
+      flag("program", "string", "program id (required)", { arg: "ID" }),
+      flag("partner", "string", "affiliate id (required)", { arg: "ID" }),
+      flag("amount", "string", "gross sale value (required)", { arg: "N" }),
+      flag("earnings", "string", "the affiliate's cut (required)", { arg: "N" }),
+      flag("currency", "string", "defaults to usd", { arg: "CODE" }),
+      flag("notes", "string", "why this was entered by hand", { arg: "TEXT" }),
+    ],
+    module: "money", handler: "addCommission", paid: true,
+    note: "Earnings is not derived — a manual commission exists because the normal rate did not apply. It counts toward your monthly commission cap.",
+  },
+  {
+    noun: "commissions", verb: "void", group: "Money",
+    summary: "void a commission entered in error",
+    example: "trackrev commissions void <id> --yes",
+    args: ["id"],
+    flags: [flag("status", "string", "set another status instead of void", { arg: "NAME" })],
+    module: "money", handler: "voidCommission", paid: true, destructive: true,
+    note: "Refused if it is already on a payout batch — cancel the payout first.",
+  },
+  {
+    noun: "payouts", verb: "list", group: "Money",
+    summary: "payout batches, with open and all-time totals",
+    example: "trackrev payouts list --status pending",
+    args: [],
+    flags: [
+      flag("status", "string", "pending, processing, paid, failed or canceled", { arg: "NAME" }),
+      LIMIT("rows to return (max 500)"),
+    ],
+    module: "money", handler: "payouts", paid: true, bareNoun: true,
+    note: "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.",
+  },
+  {
+    noun: "payouts", verb: "mark-paid", group: "Money",
+    summary: "settle a payout sent off-platform",
+    example: "trackrev payouts mark-paid <id> --reference PAYPAL-BATCH-123 --yes",
+    args: ["id"],
+    flags: [flag("reference", "string", "the rail's own id (PayPal batch, Wise transfer)", { arg: "TEXT" })],
+    module: "money", handler: "markPaid", paid: true, destructive: true,
+    note: "Does NOT email the affiliate — the dashboard sends that, and a re-run would send it twice.",
+  },
+
+  /* ── Settings ─────────────────────────────────────────────────────────── */
+  {
+    noun: "settings", verb: "notifications", group: "Settings",
+    summary: "every transactional email, and whether it is on",
+    example: "trackrev settings notifications",
+    args: [],
+    flags: [],
+    module: "settings", handler: "notifications", paid: false, bareNoun: true,
+    note: "default=yes means no override is stored and the catalogue default applies.",
+  },
+  {
+    noun: "settings", verb: "notify", group: "Settings",
+    summary: "turn one transactional email on or off",
+    example: "trackrev settings notify affiliate.approved --off",
+    args: ["key"],
+    flags: [
+      flag("on", "boolean", "enable it"),
+      flag("off", "boolean", "disable it"),
+    ],
+    module: "settings", handler: "setNotification", paid: false,
+  },
+  {
+    noun: "settings", verb: "branding", group: "Settings",
+    summary: "the white-label settings affiliates see",
+    example: "trackrev settings branding",
+    args: [],
+    flags: [],
+    module: "settings", handler: "branding", paid: false,
+  },
+  {
+    noun: "settings", verb: "set-branding", group: "Settings",
+    summary: "set the partner-facing logo and accent colour",
+    example: "trackrev settings set-branding --color '#e63e2e'",
+    args: [],
+    flags: [
+      flag("logo", "string", "https logo URL", { arg: "URL" }),
+      flag("color", "string", "hex accent, e.g. #e63e2e", { arg: "HEX" }),
+      flag("clear-logo", "boolean", "back to the TrackRev logo"),
+      flag("clear-color", "boolean", "back to the TrackRev colour"),
+    ],
+    module: "settings", handler: "setBranding", paid: false,
+    note: "The affiliate subdomain is read-only here — claiming one is a namespace reservation and belongs in one place.",
+  },
+
+  /* ── Account ──────────────────────────────────────────────────────────── */
+  {
+    noun: "me", verb: null, group: "Account",
+    summary: "which workspace, plan, limits and key you're using",
+    example: "trackrev me",
+    args: [],
+    flags: [],
+    module: "me", handler: "me", paid: false,
+  },
+  {
+    noun: "login", verb: null, group: "Account",
+    summary: "save a secret key so you don't need TRACKREV_KEY",
+    example: "trackrev login --profile staging --api-url https://staging.example.com/api/v1",
+    args: [],
+    flags: [
+      flag("key", "string", "the key (prompted, hidden, when omitted)", { arg: "lk_…" }),
+      flag("api-url", "string", "API base for this profile", { arg: "URL" }),
+    ],
+    module: "auth", handler: "login", paid: false,
+    note: "Stored at ~/.config/trackrev/config.json with mode 0600. TRACKREV_KEY in the environment always wins, for CI.",
+  },
+  {
+    noun: "logout", verb: null, group: "Account",
+    summary: "forget a saved key",
+    example: "trackrev logout",
+    args: [],
+    flags: [],
+    module: "auth", handler: "logout", paid: false,
+  },
+];
+
+/* ── Derivations ─────────────────────────────────────────────────────────── */
+
+/** The words after `trackrev` that invoke a command. */
+export function usageOf(cmd) {
+  return [cmd.noun, cmd.verb].filter(Boolean).join(" ");
+}
+
+/** Help-table label for a flag: "--days N". */
+export function flagLabel(f) {
+  return f.arg ? `--${f.name} ${f.arg}` : `--${f.name}`;
+}
+
+/**
+ * Resolve the typed words to a command. Tries noun+verb, then a bare noun
+ * (`channels`; `links` → `links perf`), then top-level aliases (`journey`).
+ * Returns the command and how many positionals it consumed.
+ */
+export function resolve(noun, verb) {
+  if (!noun) return null;
+  if (verb) {
+    const exact = COMMANDS.find((c) => c.noun === noun && c.verb === verb);
+    if (exact) return { command: exact, consumed: 2 };
+  }
+  const bare = COMMANDS.find((c) => c.noun === noun && (c.verb === null || c.bareNoun));
+  if (bare) return { command: bare, consumed: 1 };
+  const alias = COMMANDS.find((c) => (c.aliases ?? []).includes(noun));
+  if (alias) return { command: alias, consumed: 1 };
+  return null;
+}
+
+/** A parseArgs `options` spec: the command's flags plus the globals. */
+export function optionsFor(cmd) {
+  const spec = {};
+  for (const f of [...(cmd ? cmd.flags : allFlags()), ...GLOBAL_FLAGS]) {
+    spec[f.name] = {
+      type: f.type,
+      ...(f.multiple && { multiple: true }),
+      ...(f.default !== undefined && { default: f.default }),
+    };
+  }
+  return spec;
+}
+
+/** Every flag across every command, one per name — for the first, lenient parse. */
+function allFlags() {
+  const seen = new Map();
+  for (const c of COMMANDS) for (const f of c.flags) if (!seen.has(f.name)) seen.set(f.name, f);
+  return [...seen.values()];
+}
+
+const pad = (s, n) => s.padEnd(n);
+const words = (c) => usageOf(c) + c.args.map((a) => ` <${a}>`).join("");
+
+export function helpText() {
+  const groups = [...new Set(COMMANDS.map((c) => c.group))];
+  const width = Math.max(...COMMANDS.map((c) => words(c).length));
+  const lines = [
+    `trackrev ${VERSION} — TrackRev in the terminal`,
+    "",
+    "Usage",
+    "  trackrev <command> [flags]",
+    "  trackrev <command> --help     flags for one command",
+    "",
+  ];
+  for (const g of groups) {
+    lines.push(g);
+    for (const c of COMMANDS.filter((c) => c.group === g)) {
+      lines.push(`  ${pad(words(c), width)}  ${c.summary}`);
+    }
+    lines.push("");
+  }
+  const gw = Math.max(...GLOBAL_FLAGS.map((f) => flagLabel(f).length));
+  lines.push("Global flags");
+  for (const f of GLOBAL_FLAGS) lines.push(`  ${pad(flagLabel(f), gw)}  ${f.meaning}`);
+  lines.push(
+    "",
+    "Output",
+    "  A table when you are watching, tab-separated when piped or redirected,",
+    "  JSON with --json. Warnings and errors always go to stderr.",
+    "",
+    "Exit codes",
+    "  0 success · 1 failure · 2 usage error · 3 plan required (upgrade)",
+    "",
+    "Environment",
+    "  TRACKREV_KEY       secret key; overrides any saved login",
+    "  TRACKREV_API_URL   API base; overrides the profile's",
+    "",
+    "Analytics commands need a paid plan. Link and account commands work on every plan.",
+  );
+  return lines.join("\n");
+}
+
+export function helpFor(cmd) {
+  const lines = [`trackrev ${words(cmd)} — ${cmd.summary}`, "", `  ${cmd.example}`, ""];
+  const all = [...cmd.flags, ...GLOBAL_FLAGS];
+  const w = Math.max(...all.map((f) => flagLabel(f).length));
+  if (cmd.flags.length) {
+    lines.push("Flags");
+    for (const f of cmd.flags) lines.push(`  ${pad(flagLabel(f), w)}  ${f.meaning}`);
+    lines.push("");
+  }
+  lines.push("Global");
+  for (const f of GLOBAL_FLAGS) lines.push(`  ${pad(flagLabel(f), w)}  ${f.meaning}`);
+  if (cmd.note) lines.push("", cmd.note);
+  if (cmd.paid) lines.push("", "Needs a paid plan.");
+  if (cmd.destructive) lines.push("", "Asks for confirmation. Pass --yes in scripts.");
+  return lines.join("\n");
+}