run402 4.18.2 → 4.20.0

package/README.md

@@ -61,6 +61,19 @@ run402 allowance balance   # mainnet + testnet + billing balance
 run402 allowance export    # print {"address":"0x..."} for funding
 ```
 
+### Promo codes
+
+```bash
+run402 redeem R402-K8F3-Q2W9          # any time, before or after `run402 init`
+run402 init --voucher R402-K8F3-Q2W9  # same redemption, folded into setup
+```
+
+A promo code credits the organization with prepaid credit that settles tiers and
+priced calls with no on-chain payment. Case-insensitive, hyphens optional.
+Retrying is safe — a repeat returns the original result and never credits twice.
+A bad code never blocks `init`; it warns and records `voucher_error` in the JSON
+summary.
+
 ### Public Buzz/Nostr identity attribution
 
 Human accounts connect through <https://console.run402.com/identity-links/connect>: a normal browser, fresh passkey, and Buzz approval, with no terminal/event/passkey credential handling. The CLI commands below are the agent EOA ceremony. `identity link list` preserves every active/revoked record and its proof protocol; public identity links and organization memberships are independently revocable.

package/cli.mjs

@@ -23,6 +23,7 @@ Commands:
   init        Set up allowance, funding, and check tier status (x402 default)
   init mpp    Set up with MPP payment rail (Tempo Moderato testnet)
   pay         Call an arbitrary x402-priced URL with a bounded payment
+  redeem      Redeem a promo code for run402 credit
   status      Show full account state (allowance, balance, tier, projects)
   wallets     Manage multiple named wallets (list, new, use, rename, bind, import)
   credentials Manage local credential material (project-keys)
@@ -165,6 +166,11 @@ switch (cmd) {
     await run([sub, ...rest].filter(Boolean));
     break;
   }
+  case "redeem": {
+    const { run } = await import("./lib/redeem.mjs");
+    await run([sub, ...rest].filter(Boolean));
+    break;
+  }
   case "status": {
     const { run } = await import("./lib/status.mjs");
     await run([sub, ...rest].filter(Boolean));

package/lib/command-manifest.mjs

@@ -64,6 +64,7 @@ export const COMMAND_MANIFEST = [
   { path: ["init"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "flat", skipBehavioral: "creates a wallet and polls funding" },
   { path: ["pay"], positionals: [p("url")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["https://example.com/"], runStyle: "flat", skipBehavioral: "calls an external URL and may authorize an x402 payment" },
   { path: ["status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "flat" },
+  { path: ["redeem"], positionals: [p("code")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["R402-K8F3-Q2W9"], runStyle: "flat", skipBehavioral: "credits real money against the live organization" },
 
   // ── wallets ──────────────────────────────────────────────────────────────
   { path: ["wallets", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
@@ -76,6 +77,14 @@ export const COMMAND_MANIFEST = [
   { path: ["wallets", "import"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["gate-import-wallet", "--key", "__FIXTURE_FILE__"] },
   { path: ["wallets", "rm"], positionals: [p("name")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["no-such-wallet", "--yes"] },
 
+  // ── credentials (gateway project credentials) ────────────────────────────
+  { path: ["credentials", "issue"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--kind", "service", "--name", "gate-cred"] },
+  { path: ["credentials", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["credentials", "status"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["credentials", "rotate"], positionals: [p("credential_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["pcr_gate1"] },
+  { path: ["credentials", "revoke"], positionals: [p("credential_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["pcr_gate1"] },
+  { path: ["credentials", "token"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },
+
   // ── credentials (project-keys group) ─────────────────────────────────────
   { path: ["credentials", "project-keys", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["credentials", "project-keys", "status"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [] },

package/lib/credentials.mjs

@@ -8,22 +8,55 @@ import {
   removeProject,
   saveProject,
 } from "./config.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
-import { fail } from "./sdk-errors.mjs";
+import {
+  assertKnownFlags,
+  flagValue,
+  normalizeArgv,
+  positionalArgs,
+  failUnknownSubcommand,
+  requirePositionalCount,
+  resolveProjectSelector,
+} from "./argparse.mjs";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
 
-const HELP = `run402 credentials — Manage local credential material
+const HELP = `run402 credentials — Project credentials, and the local key cache
 
 Usage:
   run402 credentials <subcommand> [args...]
 
-Subcommands:
-  project-keys  Manage the local project-key cache
+Project credentials (on the gateway — named, revocable, rotatable):
+  issue --kind <anon|service> --name <name> [--project <id>] [--expires <iso8601>]
+                                Mint one. The secret is printed ONCE.
+  list [--project <id>] [--include-revoked]
+                                List credentials (metadata only, never secrets)
+  status [--project <id>]       Are you still on the retiring legacy key?
+  rotate <credential_id> [--project <id>]
+                                Replace in one step; new secret printed ONCE
+  revoke <credential_id> [--project <id>] [--reason <text>]
+                                Revoke immediately, freeing the name
+  token [--project <id>] [--kind <anon|service>]
+                                Mint a SHORT-LIVED token. Works with only a
+                                delegate — the unattended recovery path.
+
+Local cache (on this machine):
+  project-keys                  Manage the local project-key cache
+
+Notes:
+  - 'issue', 'rotate' and 'revoke' need owner membership on the project's org
+    plus a fresh step-up, so a scoped agent credential can never escalate
+    itself into a permanent root. Authenticate with a wallet (SIWX) or a
+    control-plane session ('run402 operator login --step-up').
+  - 'token' is the exception: a delegate can mint one with no human present.
+  - Secrets are returned EXACTLY ONCE and are never recoverable. Full JSON goes
+    to stdout so you can pipe it; the warnings go to stderr.
 
 Examples:
+  run402 credentials status --project prj_abc123
+  run402 credentials issue --kind service --name ci-deploy --project prj_abc123
+  run402 credentials issue --kind service --name ci-deploy | jq -r .secret
+  run402 credentials rotate pcr_123 --project prj_abc123
   run402 credentials project-keys list
-  run402 credentials project-keys status --project prj_abc123
-  run402 credentials project-keys import --project prj_abc123 --service-key-stdin
-  run402 credentials project-keys export --project prj_abc123 --reveal
 `;
 
 const PROJECT_KEYS_HELP = `run402 credentials project-keys — Manage local project-key cache entries
@@ -50,6 +83,79 @@ Notes:
     service key, so an anon rotation never puts a service key through a shell.
 `;
 
+const SUB_HELP = {
+  issue: `run402 credentials issue — mint a named project credential
+
+Usage:
+  run402 credentials issue --kind <anon|service> --name <name> [--project <id>]
+                           [--expires <iso8601>]
+
+--kind    "anon" is the tenant-facing key; "service" is the privileged one.
+--name    Unique among this project's LIVE credentials. Re-using a live name
+          returns 409 CREDENTIAL_NAME_TAKEN — that collision is the idempotency
+          story, so a retried create never mints a second credential by accident.
+--expires Optional; must be in the future and within one year.
+
+The secret is printed ONCE, on stdout, inside the JSON. Pipe it:
+  run402 credentials issue --kind service --name ci | jq -r .secret
+
+Requires owner membership on the project's org plus a fresh step-up. A delegate
+can NEVER do this; use 'run402 credentials token' instead.
+`,
+  list: `run402 credentials list — list a project's credentials
+
+Usage:
+  run402 credentials list [--project <id>] [--include-revoked]
+
+Metadata only — never a secret or a secret hash. Only project.read is needed.
+`,
+  status: `run402 credentials status — are you still on the retiring legacy key?
+
+Usage:
+  run402 credentials status [--project <id>]
+
+Returns state "legacy" while the project still depends on the derived
+anon/service keys, or "rotatable" once it holds credentials it can revoke
+individually.
+
+There is deliberately NO deadline: retirement is gated on conditions (every
+tenant migrated, 30 consecutive days of zero legacy-key use, explicit operator
+approval), not a date. Read retirement.gated_on rather than planning against a
+date the platform has not committed to.
+`,
+  rotate: `run402 credentials rotate — replace a credential in one step
+
+Usage:
+  run402 credentials rotate <credential_id> [--project <id>]
+
+Mints a replacement and revokes the old one in a single transaction, keeping
+the name. The NEW secret is printed once.
+
+For a rotation with no downtime window, prefer issuing a SECOND credential,
+deploying it, then revoking the first — several may be live per kind at once,
+and that overlap is the point. Use 'rotate' when the old secret is already
+compromised.
+`,
+  revoke: `run402 credentials revoke — revoke a credential immediately
+
+Usage:
+  run402 credentials revoke <credential_id> [--project <id>] [--reason <text>]
+
+Takes effect for every subsequent request and frees the name for reuse.
+Requires owner membership plus step-up.
+`,
+  token: `run402 credentials token — mint a short-lived project token
+
+Usage:
+  run402 credentials token [--project <id>] [--kind <anon|service>]
+
+The cold-restart recovery path, and the ONE credential call an agent can make
+with no human present: a delegate is accepted here. There is no step-up because
+there is nobody to prompt, and what you get back expires, so it cannot become a
+durable root. Defaults to --kind service.
+`,
+};
+
 function parseProjectKeyFlags(args, extraKnown = [], valueFlagsExtra = []) {
   const parsed = normalizeArgv(args);
   const valueFlags = ["--project", ...valueFlagsExtra];
@@ -273,6 +379,166 @@ async function runProjectKeys(sub, args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Project credentials — the gateway rows, not the local cache.
+//
+// These five routes shipped with no client at all, so the documented way off
+// the legacy derived anon/service keys was to hand-roll a SIWX-signed request.
+// `run402 pay` is NOT that escape hatch (it is the x402 buyer path and 401s
+// here), which is how an agent could read the docs, find the route, and still
+// have no way to call it.
+// ---------------------------------------------------------------------------
+
+/** Full JSON on stdout (pipeable); the one-shot warning on stderr. */
+function emitIssued(res) {
+  console.log(JSON.stringify(res, null, 2));
+  if (res?.secret) {
+    console.error("");
+    console.error("The secret above is shown ONCE and cannot be read back.");
+    console.error("Store it now — 'rotate' is the only way to get a new one.");
+  }
+}
+
+const ISSUE_VALUE_FLAGS = ["--project", "--kind", "--name", "--expires"];
+
+async function issue(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ISSUE_VALUE_FLAGS, "--help", "-h"], ISSUE_VALUE_FLAGS);
+  const kind = flagValue(a, "--kind");
+  const name = flagValue(a, "--name");
+  const expiresAt = flagValue(a, "--expires");
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ISSUE_VALUE_FLAGS });
+  requirePositionalCount(rest, ISSUE_VALUE_FLAGS, {
+    min: 0,
+    max: 0,
+    command: "run402 credentials issue --kind <anon|service> --name <name> [--project <id>]",
+    missing: "",
+  });
+  if (kind !== "anon" && kind !== "service") {
+    fail({
+      message: 'Missing or invalid --kind. Use "anon" (tenant-facing) or "service" (privileged).',
+      code: "BAD_USAGE",
+      hint: "run402 credentials issue --kind service --name ci-deploy",
+    });
+  }
+  if (!name) {
+    fail({
+      message: "Missing --name.",
+      code: "BAD_USAGE",
+      hint: "The name identifies this credential in 'list' and is how you rotate it later, e.g. --name ci-deploy",
+    });
+  }
+  try {
+    emitIssued(await getSdk().credentials.issue(projectId, { kind, name, expiresAt: expiresAt || undefined }));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function listCredentials(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--project", "--include-revoked", "--help", "-h"], ["--project"]);
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
+  requirePositionalCount(rest, ["--project"], {
+    min: 0,
+    max: 0,
+    command: "run402 credentials list [--project <id>]",
+    missing: "",
+  });
+  try {
+    const includeRevoked = a.includes("--include-revoked");
+    console.log(JSON.stringify(await getSdk().credentials.list(projectId, { includeRevoked }), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function credentialStatus(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
+  requirePositionalCount(rest, ["--project"], {
+    min: 0,
+    max: 0,
+    command: "run402 credentials status [--project <id>]",
+    missing: "",
+  });
+  try {
+    const res = await getSdk().credentials.status(projectId);
+    console.log(JSON.stringify(res, null, 2));
+    if (res?.state === "legacy") {
+      console.error("");
+      console.error("This project still depends on the derived anon/service keys, whose signing");
+      console.error("key is being retired. Issue a credential to stop depending on them:");
+      console.error(`  run402 credentials issue --kind service --name primary --project ${projectId}`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function rotate(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
+  const [credentialId] = requirePositionalCount(rest, ["--project"], {
+    min: 1,
+    max: 1,
+    command: "run402 credentials rotate <credential_id> [--project <id>]",
+    missing: "Missing <credential_id>. Find it with: run402 credentials list",
+  });
+  try {
+    emitIssued(await getSdk().credentials.rotate(projectId, credentialId));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function revoke(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--project", "--reason", "--help", "-h"], ["--project", "--reason"]);
+  const reason = flagValue(a, "--reason");
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project", "--reason"] });
+  const [credentialId] = requirePositionalCount(rest, ["--project", "--reason"], {
+    min: 1,
+    max: 1,
+    command: "run402 credentials revoke <credential_id> [--project <id>]",
+    missing: "Missing <credential_id>. Find it with: run402 credentials list",
+  });
+  try {
+    const res = await getSdk().credentials.revoke(projectId, credentialId, reason ? { reason } : {});
+    console.log(JSON.stringify(res, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function token(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--project", "--kind", "--help", "-h"], ["--project", "--kind"]);
+  const kind = flagValue(a, "--kind");
+  const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project", "--kind"] });
+  requirePositionalCount(rest, ["--project", "--kind"], {
+    min: 0,
+    max: 0,
+    command: "run402 credentials token [--project <id>]",
+    missing: "",
+  });
+  if (kind && kind !== "anon" && kind !== "service") {
+    fail({ message: '--kind must be "anon" or "service".', code: "BAD_USAGE" });
+  }
+  try {
+    const res = await getSdk().credentials.mintToken(projectId, kind ? { kind } : {});
+    console.log(JSON.stringify(res, null, 2));
+    if (res?.secret) {
+      console.error("");
+      console.error(`The token above is shown ONCE and expires in ${res.expires_in ?? "?"}s.`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 export async function run(sub, args = []) {
   if (!sub || sub === "--help" || sub === "-h") {
     console.log(HELP);
@@ -283,5 +549,18 @@ export async function run(sub, args = []) {
     await runProjectKeys(projectKeySub, rest);
     return;
   }
-  failUnknownSubcommand("credentials", sub);
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(SUB_HELP[sub] || HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "issue": await issue(args); break;
+    case "list": await listCredentials(args); break;
+    case "status": await credentialStatus(args); break;
+    case "rotate": await rotate(args); break;
+    case "revoke": await revoke(args); break;
+    case "token": await token(args); break;
+    default:
+      failUnknownSubcommand("credentials", sub);
+  }
 }

package/lib/init.mjs

@@ -26,6 +26,11 @@ Usage:
                              silently flipping billing networks.
 
 Options:
+  --voucher <code> Redeem a promo code after setup and credit this
+                  organization. Never blocks setup: if the code is invalid,
+                  expired, already used, or the call fails, init warns and
+                  finishes normally with 'voucher_error' in the summary.
+                  Equivalent to running 'run402 redeem <code>' afterwards.
   --api-base <url> Configure the active profile to use this API base. Use this
                   for a self-hosted Run402 Core Gateway, e.g.
                   http://my-core:4020.
@@ -81,6 +86,43 @@ function parseApiBaseFlag(args) {
   return { value: null, args };
 }
 
+/**
+ * Pull `--voucher <code>` / `--voucher=<code>` out of argv, mirroring
+ * `parseApiBaseFlag`. A MISSING VALUE still fails fast — that is a usage error
+ * the caller can fix, unlike a redemption failure, which must never take init
+ * down with it (see the redemption step at the end of `run`).
+ */
+function parseVoucherFlag(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--voucher") {
+      const value = args[i + 1];
+      if (value === undefined || String(value).startsWith("--")) {
+        fail({
+          code: "BAD_USAGE",
+          message: "--voucher requires a value.",
+          hint: "run402 init --voucher R402-K8F3-Q2W9",
+          details: { flag: "--voucher" },
+        });
+      }
+      return { value, args: [...args.slice(0, i), ...args.slice(i + 2)] };
+    }
+    if (typeof arg === "string" && arg.startsWith("--voucher=")) {
+      const value = arg.slice("--voucher=".length);
+      if (!value) {
+        fail({
+          code: "BAD_USAGE",
+          message: "--voucher requires a non-empty value.",
+          hint: "run402 init --voucher R402-K8F3-Q2W9",
+          details: { flag: "--voucher" },
+        });
+      }
+      return { value, args: [...args.slice(0, i), ...args.slice(i + 1)] };
+    }
+  }
+  return { value: null, args };
+}
+
 function sameOrigin(a, b) {
   try {
     return new URL(a).origin === new URL(b).origin;
@@ -128,6 +170,13 @@ export async function run(args = []) {
 
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
 
+  // Strip --voucher before anything else parses argv, so the rail/positional
+  // logic below never sees it (an unrecognized token there would be read as a
+  // rail name).
+  const parsedVoucher = parseVoucherFlag(args);
+  args = parsedVoucher.args;
+  const voucherCode = parsedVoucher.value;
+
   const parsedApiBase = parseApiBaseFlag(args);
   if (parsedApiBase.value) {
     if (parsedApiBase.args.some((arg) => typeof arg === "string" && !arg.startsWith("--"))) {
@@ -137,6 +186,17 @@ export async function run(args = []) {
         hint: "Run `run402 init --api-base=http://my-core:4020` for Core, or `run402 init` for Run402 Cloud.",
       });
     }
+    // This branch configures a Core/API target and returns without setting up
+    // an allowance — there is no organization here to credit, and promo
+    // vouchers are a Run402 Cloud concept. Say so instead of accepting the
+    // flag and silently dropping it.
+    if (voucherCode) {
+      fail({
+        code: "BAD_USAGE",
+        message: "run402 init --api-base cannot be combined with --voucher.",
+        hint: "Configure the target first (`run402 init --api-base=…`), then redeem against Run402 Cloud with `run402 redeem <code>`.",
+      });
+    }
     const CONFIG_DIR = configDir();
     const detected = await detectTarget(parsedApiBase.value);
     const config = configureApiBase(parsedApiBase.value, {
@@ -199,6 +259,10 @@ export async function run(args = []) {
     rail: null,
     network: null,
     balances: null,
+    // Present (null or an object) only when --voucher was passed, so its
+    // absence means "no code was offered" rather than "a code silently
+    // vanished". `voucher_error` appears alongside a null `voucher`.
+    ...(voucherCode ? { voucher: null } : {}),
     tier: null,
     projects_saved: 0,
     next_actions: [],
@@ -335,6 +399,46 @@ export async function run(args = []) {
     }
   }
 
+  // 3b. Promo code, when one was handed to us.
+  //
+  // This runs BEFORE the balance read below so the credited amount shows up in
+  // `prepaid_credit_usd_micros` without a second round-trip, and AFTER the
+  // wallet exists so the redemption authenticates as this agent.
+  //
+  // NOTHING here may fail init. An advertised gift that dead-ends a build is
+  // worse than no gift at all: the agent was told to run one command, and that
+  // command must still leave it set up and able to work. Every failure — bad
+  // code, expired, already used by someone else, org at its ceiling, network
+  // down, gateway too old to know the route — warns on stderr, records
+  // `voucher_error` in the JSON summary, and lets setup finish.
+  if (voucherCode) {
+    try {
+      const redemption = await getSdk().vouchers.redeem(voucherCode);
+      const credited = (redemption.amount_usd_micros / 1_000_000).toFixed(2);
+      line(
+        "Voucher",
+        redemption.already_redeemed
+          ? `$${credited} already credited (no second credit)`
+          : `$${credited} credited`,
+      );
+      summary.voucher = {
+        voucher_id: redemption.voucher_id,
+        amount_usd_micros: redemption.amount_usd_micros,
+        already_redeemed: redemption.already_redeemed,
+      };
+    } catch (err) {
+      // Faithful: name what failed and keep going. `voucher_error` is a
+      // first-class summary field, not an omission the caller has to infer.
+      const reason = errorMessage(err);
+      line("Voucher", `not applied: ${reason}`);
+      summary.voucher = null;
+      summary.voucher_error = {
+        code: err?.body?.code ?? err?.code ?? "VOUCHER_REDEEM_FAILED",
+        message: reason,
+      };
+    }
+  }
+
   // Balances mirror `run402 status`: the on-chain figure above plus the
   // Run402-held prepaid credit (rail-independent). Prepaid credit is fetched
   // best-effort so a billing read failure never blocks setup.

package/lib/redeem.mjs

@@ -0,0 +1,80 @@
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertKnownFlags, normalizeArgv, positionalArgs } from "./argparse.mjs";
+
+const HELP = `run402 redeem — Redeem a promo code for run402 credit
+
+Usage:
+  run402 redeem <code> [--json]
+
+A promo code credits your organization with run402 prepaid credit. That credit
+spends like any other prepaid balance — a tier purchase settles from it with no
+on-chain payment.
+
+Notes:
+  - Order does not matter. This works as your very first authenticated call
+    (the organization is created on demand) or long after 'run402 init'.
+  - Codes are forgiving: case-insensitive and hyphens are optional, so
+    'R402-K8F3-Q2W9' and 'r402k8f3q2w9' are the same code.
+  - Retrying is safe. A repeat by the same organization returns the original
+    result with "already_redeemed": true and never credits twice.
+  - Being in a grace state does not block you. Redeeming is how an owner funds
+    a renewal, so it is never gated.
+  - One gift per organization: past the lifetime ceiling you get 403
+    PROMO_LIMIT_REACHED with the exact numbers.
+
+To fold this into first-time setup instead, use:
+  run402 init --voucher <code>
+
+Examples:
+  run402 redeem R402-K8F3-Q2W9
+  run402 redeem r402k8f3q2w9
+`;
+
+export async function run(args = []) {
+  const parsedArgs = normalizeArgv(args);
+  if (parsedArgs.includes("--help") || parsedArgs.includes("-h")) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(parsedArgs, ["--help", "-h"], []);
+  const positionals = positionalArgs(parsedArgs, []);
+  if (positionals.length > 1) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for redeem: ${positionals[1]}`,
+      hint: "Use `run402 redeem <code>`.",
+    });
+  }
+  const code = positionals[0];
+  if (!code) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <code>.",
+      hint: "run402 redeem <code>  (e.g. run402 redeem R402-K8F3-Q2W9)",
+    });
+  }
+
+  try {
+    const data = await getSdk().vouchers.redeem(code);
+    // Progress to stderr, JSON to stdout — the pipe contract. The one-liner
+    // exists because the interesting fact (money arrived) is otherwise buried
+    // in a field a human skims past.
+    console.error("");
+    console.error(
+      `  Voucher    ${usd(data.amount_usd_micros)} credited` +
+        `${data.already_redeemed ? " (already redeemed " + data.redeemed_at + " — no second credit)" : ""}`,
+    );
+    console.error(`  Balance    ${usd(data.balance_usd_micros)} available`);
+    const next = Array.isArray(data.next_actions) ? data.next_actions.find((a) => a?.cli) : null;
+    if (next?.cli) console.error(`\n  Next: ${next.cli}`);
+    console.error("");
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function usd(micros) {
+  return `$${(Number(micros ?? 0) / 1_000_000).toFixed(2)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.18.2",
+  "version": "4.20.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/index.d.ts

@@ -22,6 +22,7 @@ import { Ai } from "./namespaces/ai.js";
 import { Auth } from "./namespaces/auth.js";
 import { SenderDomain } from "./namespaces/sender-domain.js";
 import { Billing } from "./namespaces/billing.js";
+import { Vouchers } from "./namespaces/vouchers.js";
 import { Wallets, ScopedWallet } from "./namespaces/wallets.js";
 import { Apps } from "./namespaces/apps.js";
 import { Email } from "./namespaces/email.js";
@@ -86,6 +87,7 @@ export declare class Run402 {
     readonly auth: Auth;
     readonly senderDomain: SenderDomain;
     readonly billing: Billing;
+    readonly vouchers: Vouchers;
     readonly wallets: Wallets;
     readonly apps: Apps;
     readonly email: Email;
@@ -286,6 +288,7 @@ export type * from "./namespaces/assets.types.js";
 export type * from "./namespaces/ci.types.js";
 export type * from "./namespaces/contracts.js";
 export type * from "./namespaces/credentials.js";
+export type * from "./namespaces/credentials.types.js";
 export type * from "./namespaces/deploy.types.js";
 export { Deploy } from "./namespaces/deploy.js";
 export type { ByteReader } from "./namespaces/deploy.js";
@@ -309,6 +312,8 @@ export { Rooms, ScopedRoom } from "./namespaces/rooms.js";
 export type * from "./namespaces/rooms.types.js";
 export { Errors } from "./namespaces/errors.js";
 export type * from "./namespaces/errors.types.js";
+export { Vouchers } from "./namespaces/vouchers.js";
+export type * from "./namespaces/vouchers.js";
 export { Pay, PaymentBuyerError, PaymentPolicyError, DEFAULT_PAYMENT_MAX_USD_MICROS, X402_COMMERCE_RESULT_SCHEMA_VERSION, X402_EVIDENCE_STATUSES, X402_GATEWAY_AVAILABILITY_ERROR_CODE, X402_MUTATION_STATES, X402_PAYMENT_POLICY_ERROR_CODES, X402_RECOVERY_ACTIONS, RUN402_PENDING_CLASSIFIER_VERSION, isPaymentBuyerError, isPaymentPolicyError, isTrustedRun402PaymentUrl, isTrustedRun402PendingResponse, payFetchResultToJson, } from "./namespaces/pay.js";
 export type * from "./namespaces/pay.js";
 export { Archives } from "./namespaces/archives.js";