run402 4.96.0 → 4.97.0

package/README.md

@@ -4,7 +4,7 @@
 
 Command-line interface for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, run Node 22 serverless functions, host content-addressed CDN assets, send email, sign on-chain. Paid autonomously with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning). **Prototype tier is free on testnet.**
 
-The CLI lets an agent act as its own first-class Run402 principal rather than borrowing a human account. Identity records who invoked an action; organization roles, grants, delegates, freshness, and spend policy determine what that principal may do. People remain first-class owners and members without having to run the CLI themselves.
+The CLI lets an agent act as its own first-class Run402 principal rather than borrowing a human account. Identity records who invoked an action; organization roles, grants, grant keys, freshness, and spend policy determine what that principal may do. People remain first-class owners and members without having to run the CLI themselves.
 
 For the full CLI reference (every flag, every subcommand) start at **<https://docs.run402.com/llms-cli.txt>** — the index holds the first-deploy contract and links one fetchable `/llms-cli-<slice>.txt` per topic (deploy, commands, repos, orgs, functions, assets, ops, errors, frontend, platform); <https://docs.run402.com/llms-cli-full.txt> is the whole reference as one document.
 
@@ -121,7 +121,7 @@ This links two separately held public identities through fresh signatures; it ne
 
 ### Buzz community control plane
 
-`run402 buzz status` reports skill installation, human-adoption offers/adoptions, community installation, and this agent's enrollment independently, and safely reports `supported: false` against an older gateway. The canonical ownership workflow is `buzz adopt offer --org … --identity-link …`: it capability-checks before mutation and returns a normal durable HTTPS handoff. Poll with `buzz adopt offer show <buzzhao_id>` and cancel with `buzz adopt offer cancel <buzzhao_id>`. The raw challenge command is explicitly advanced as `buzz adopt direct …`; direct completion/cancellation remain `buzz adopt complete|cancel`. Other goal workflows are `buzz install` and `buzz enroll`; decisions are `buzz install activate|update|revoke` and `buzz approve|deny|revoke`. `buzz install discover --community <buzz:community:host>` lists Run402-owned active descriptors without authentication. MCP intentionally has no signing/passkey mutation and only renders exact HTTPS/CLI handoffs. All commands print JSON to stdout, advice to stderr, have zero spend impact, and never accept Nostr/wallet secrets, session material, service keys, delegates, or payment credentials. Failure JSON preserves the gateway's code-specific `next_actions`, exact repair `field`, and retry safety; never replace it with a generic edit-and-retry. See the [Fizz/Honey examples](../buzz/references/community-control-plane.md).
+`run402 buzz status` reports skill installation, human-adoption offers/adoptions, community installation, and this agent's enrollment independently, and safely reports `supported: false` against an older gateway. The canonical ownership workflow is `buzz adopt offer --org … --identity-link …`: it capability-checks before mutation and returns a normal durable HTTPS handoff. Poll with `buzz adopt offer show <buzzhao_id>` and cancel with `buzz adopt offer cancel <buzzhao_id>`. The raw challenge command is explicitly advanced as `buzz adopt direct …`; direct completion/cancellation remain `buzz adopt complete|cancel`. Other goal workflows are `buzz install` and `buzz enroll`; decisions are `buzz install activate|update|revoke` and `buzz approve|deny|revoke`. `buzz install discover --community <buzz:community:host>` lists Run402-owned active descriptors without authentication. MCP intentionally has no signing/passkey mutation and only renders exact HTTPS/CLI handoffs. All commands print JSON to stdout, advice to stderr, have zero spend impact, and never accept Nostr/wallet secrets, session material, service keys, grant keys, or payment credentials. Failure JSON preserves the gateway's code-specific `next_actions`, exact repair `field`, and retry safety; never replace it with a generic edit-and-retry. See the [Fizz/Honey examples](../buzz/references/community-control-plane.md).
 
 ### Buy from an x402 URL
 

package/cli.mjs

@@ -70,8 +70,7 @@ COORDINATE — work alongside other agents and humans
 
 AUTHORITY — who may act, and with what credential
   credentials Manage local credential material (project-keys)
-  delegates   Scoped deploy credentials for agents (create, list, revoke, rotate)
-  grants      Per-project capability grants for agent/CI principals (create, revoke)
+  grants      Project grants and grant keys for agents (create, list, revoke, revoke-key, rotate-key)
   orgs        Organizations, members, invites & audit (list, get, members, invite, audit)
   identity    Public proof-backed external agent identity links
   auth        Manage project user authentication (magic link, passwords, settings)
@@ -285,11 +284,6 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  case "delegates": {
-    const { run } = await import("./lib/delegates.mjs");
-    await run(sub, rest);
-    break;
-  }
   case "events": {
     const { run } = await import("./lib/events.mjs");
     await run(sub, rest);

package/lib/buzz.mjs

@@ -67,7 +67,7 @@ Advanced recovery reads:
 Security:
   - JSON stdout only; progress and pending-state advice go to stderr.
   - This command never accepts an nsec, private key, mnemonic, seed, service key,
-    delegate token, recovery code, or payment material.
+    grant key, recovery code, or payment material.
   - Buzz signatures are public evidence. Run402 authority still comes only from
     human/agent principals, org membership, and project grants.
   - Every command in this group has zero spend impact.

package/lib/command-manifest.mjs

@@ -235,13 +235,10 @@ export const COMMAND_MANIFEST = [
 
   // ── grants ───────────────────────────────────────────────────────────────
   { path: ["grants", "create"], positionals: [p("wallet")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["0x1111111111111111111111111111111111111111", "--capability", "deploy"] },
+  { path: ["grants", "list"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [] },
   { path: ["grants", "revoke"], positionals: [p("grant_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["grt_gate1"] },
-
-  // ── delegates ────────────────────────────────────────────────────────────
-  { path: ["delegates", "create"], legacyPositionalProject: false, positionals: [], projectScoped: true, minimalArgs: ["--grant", "11111111-1111-1111-1111-111111111111"] },
-  { path: ["delegates", "list"], legacyPositionalProject: false, positionals: [], projectScoped: true, minimalArgs: [] },
-  { path: ["delegates", "revoke"], legacyPositionalProject: false, positionals: [p("delegate_id")], projectScoped: true, minimalArgs: ["dlg_gate1"] },
-  { path: ["delegates", "rotate"], legacyPositionalProject: false, positionals: [p("delegate_id")], projectScoped: true, minimalArgs: ["dlg_gate1"] },
+  { path: ["grants", "revoke-key"], positionals: [p("key_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["key_gate1"] },
+  { path: ["grants", "rotate-key"], positionals: [p("key_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["key_gate1"] },
 
   // ── events / live ────────────────────────────────────────────────────────
   { path: ["events", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },

package/lib/credentials.mjs

@@ -39,7 +39,7 @@ Project credentials (on the gateway — named, revocable, rotatable):
                                 Revoke immediately, freeing the name
   token [--project <project_id>] [--kind <anon|service>]
                                 Mint a SHORT-LIVED token. Works with only a
-                                delegate — the unattended recovery path.
+                                grant key — the unattended recovery path.
 
 Local cache (on this machine):
   project-keys                  Manage the local project-key cache
@@ -49,7 +49,7 @@ Notes:
     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
     sign-in session ('run402 login').
-  - 'token' is the exception: a delegate can mint one with no human present.
+  - 'token' is the exception: a grant key 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.
 
@@ -106,7 +106,7 @@ Usage:
 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
+Requires owner membership on the project's org plus a fresh step-up. A grant key
 can NEVER do this; use 'run402 credentials token' instead.
 `,
   list: `run402 credentials list — list a project's credentials
@@ -157,7 +157,7 @@ Usage:
   run402 credentials token [--project <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
+with no human present: a grant key 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.
 `,

package/lib/deploy-v2.mjs

@@ -44,7 +44,7 @@ import {
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { API, walletAuthHeaders, getActiveProjectId, resolveProjectId, isCoreApiTarget, updateProject } from "./config.mjs";
-import { delegateTokenFromEnv } from "#sdk/node";
+import { grantKeyFromEnv } from "#sdk/node";
 import { flagValue, normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./sign-in.mjs";
@@ -486,10 +486,10 @@ async function rehearseCmd(rawArgs) {
     fail({ code: "BAD_USAGE", message: "--teardown must be one of: on_pass, keep, always", details: { flag: "--teardown", value: teardown } });
   }
   const project = flagValue(args, "--project") ?? undefined;
-  // A delegate is a complete deploy credential and the gateway explicitly
+  // A grant key is a complete deploy credential and the gateway explicitly
   // supports rehearsing with one (the route rejects only CI sessions).
   // Rehearsal is the SAFE path; never make it the harder one.
-  if (!isCoreApiTarget() && !loadLiveControlPlaneSession() && !delegateTokenFromEnv()) {
+  if (!isCoreApiTarget() && !loadLiveControlPlaneSession() && !grantKeyFromEnv()) {
     walletAuthHeaders(`/apply/v1/plans/${givenPlanId ?? "_"}/rehearse`);
   }
   const sdk = getSdk();
@@ -723,9 +723,9 @@ async function promoteCmd(args) {
 
   // Preserve the aggressive early-exit when no local wallet is configured
   // — same as apply.
-  // A delegate holds `deploy` and the gateway accepts it on this route; refusing
+  // A grant key holds `deploy` and the gateway accepts it on this route; refusing
   // locally would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/releases");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/releases");
 
   try {
     // Call the engine directly (matches the pattern used by apply / resume
@@ -1295,20 +1295,20 @@ async function deployCmd(args) {
 
 
   let sdkOpts;
-  const delegateToken = delegateTokenFromEnv();
+  const grantKey = grantKeyFromEnv();
   if (useGithubActionsOidc) {
     sdkOpts = {
       credentials: githubActionsCredentials({ projectId: releaseSpec.project_id, apiBase: API }),
       disablePaidFetch: true,
     };
-  } else if (delegateToken) {
-    // A delegate is a complete, self-contained deploy credential: the owner
+  } else if (grantKey) {
+    // A grant key is a complete, self-contained deploy credential: the owner
     // minted it with their wallet and handed it over, so this process needs no
     // wallet of its own. Skipping the guard is the point — an agent that
     // lost its local state (or never had a wallet) can still deploy. Paid fetch
-    // is disabled for the same reason it is under CI: a delegate authorizes
+    // is disabled for the same reason it is under CI: a grant key authorizes
     // deploys, not spending.
-    sdkOpts = { delegateToken, disablePaidFetch: true };
+    sdkOpts = { grantKey, disablePaidFetch: true };
   } else if (!isCoreApiTarget() && !loadLiveControlPlaneSession()) {
     // Aggressive early exit when no local wallet is configured — unless a
     // wallet-less person is deploying via their sign-in session
@@ -1766,9 +1766,9 @@ async function resumeCmd(args) {
   emitDeployUpdateNotice("resume", args, { quiet: opts.quiet });
   const project = resolveProjectId(opts.project);
 
-  // A delegate holds `deploy` and the gateway accepts it on this route; refusing
+  // A grant key holds `deploy` and the gateway accepts it on this route; refusing
   // locally would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/operations");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/operations");
 
   try {
     const result = await getSdk({ disablePaidFetch: true })._applyEngine.resume(opts.operationId, {
@@ -1794,9 +1794,9 @@ async function statusCmd(args) {
     missing: "Missing <operation_id>.",
   });
   const project = resolveProjectId(parsed.flags["--project"] ?? null);
-  // A delegate holds `deploy` and the gateway accepts it on this route; refusing
+  // A grant key holds `deploy` and the gateway accepts it on this route; refusing
   // locally would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/operations");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/operations");
 
   try {
     const result = await getSdk()._applyEngine.status(operationId, { project });
@@ -1822,24 +1822,24 @@ async function listCmd(args) {
   };
 
   const project = resolveProjectId(opts.project);
-  // NOT ungated for delegates, deliberately: /apply/v1/operations (list) is
+  // NOT ungated for grant keys, deliberately: /apply/v1/operations (list) is
   // `apikeyAuth` only — unlike get/events/resume/promote, which accept a
-  // delegate bearer. Listing every operation on a project is broader than
+  // grant-key bearer. Listing every operation on a project is broader than
   // the per-operation reads a deploy credential is scoped to. If this is
   // ever widened, widen the ROUTE first, then this guard.
   //
   // The refusal is correct; the REMEDY must still be honest. Falling through
-  // to NO_WALLET would tell a delegate holder to run `run402 init`, which
+  // to NO_WALLET would tell a grant-key holder to run `run402 init`, which
   // is wrong for a credential that is wallet-less by design — the same
   // misleading-remedy shape removed from the payment path in 4.11.2.
-  if (delegateTokenFromEnv()) {
+  if (grantKeyFromEnv()) {
     fail({
-      code: "DELEGATE_SCOPE_INSUFFICIENT",
-      message: "Listing deploy operations is not available to a delegate.",
-      hint: "Use `run402 deploy status <operation_id>`, `deploy events <operation_id>` or `deploy verify <operation_id>` for a specific operation, which a delegate CAN read. A full listing needs the project apikey or the owner wallet.",
-      details: { command: "deploy list", credential: "delegate", route: "GET /apply/v1/operations" },
+      code: "GRANT_KEY_SCOPE_INSUFFICIENT",
+      message: "Listing deploy operations is not available to a grant key.",
+      hint: "Use `run402 deploy status <operation_id>`, `deploy events <operation_id>` or `deploy verify <operation_id>` for a specific operation, which a grant key CAN read. A full listing needs the project apikey or the owner wallet.",
+      details: { command: "deploy list", credential: "grant_key", route: "GET /apply/v1/operations" },
       next_actions: [
-        { type: "run_command", command: "run402 deploy status <operation_id>", why: "Per-operation reads are within a delegate's deploy scope." },
+        { type: "run_command", command: "run402 deploy status <operation_id>", why: "Per-operation reads are within a grant key's deploy scope." },
       ],
     });
   }
@@ -1870,9 +1870,9 @@ async function eventsCmd(args) {
   const opts = { operationId, project: parsed.flags["--project"] ?? null };
 
   const project = resolveProjectId(opts.project);
-  // A delegate holds `deploy` and the gateway accepts it on this route; refusing
+  // A grant key holds `deploy` and the gateway accepts it on this route; refusing
   // locally would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/operations");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/operations");
 
   try {
     const result = await getSdk()._applyEngine.events(opts.operationId, { project });
@@ -1916,9 +1916,9 @@ async function verifyCmd(args) {
     ? 60
     : parsePositiveInt(parsed.flags["--timeout"], "--timeout");
 
-  // A delegate holds `deploy` and the gateway accepts it on this route; refusing
+  // A grant key holds `deploy` and the gateway accepts it on this route; refusing
   // locally would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/operations");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/operations");
 
   try {
     let result;

package/lib/errors.mjs

@@ -110,7 +110,7 @@ Exit codes (the promote gate — only when --fail-on-new is set):
 
 Auth:
   The addressed project's own service_key when it is cached locally; otherwise
-  your wallet / session / delegate, which the gateway authorizes with
+  your wallet / session / grant key, which the gateway authorizes with
   project.read — an org member or teammate agent needs no project key. A key
   for project A requesting project B's errors gets 403 (never a 404 that
   leaks existence). Read-only; never lifecycle-gated.

package/lib/events.mjs

@@ -95,7 +95,7 @@ Event shape:
 
 Auth:
   --project: the project's own service_key, your SIWX wallet, a control-plane
-             session, or a scoped delegate with project.read.
+             session, or a grant key with project.read.
   --org:     wallet / control-plane session with an active org membership
              (a project service_key cannot read sibling projects' events).
   The feed is read-only and never lifecycle-gated: a frozen project's feed

package/lib/grants.mjs

@@ -1,5 +1,5 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError, parseFlagJson } from "./sdk-errors.mjs";
+import { reportSdkError, parseFlagJson, fail } from "./sdk-errors.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
@@ -9,114 +9,213 @@ import {
   failUnknownSubcommand,
 } from "./argparse.mjs";
 
-const HELP = `run402 grants — per-project capability grants (agent/CI principals)
+const HELP = `run402 grants — per-project capability grants and their grant keys
 
 Usage:
   run402 grants <subcommand> [args...]
 
 Subcommands:
-  create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]
-                                 Issue a capability grant (owner of the project's org)
+  create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires-at <iso8601>]
+         [--key [--kind <kind>] [--scope <json>] [--spend-cap <json>]]
+                                 Issue a grant; with --key also mint its first
+                                 grant key (the token is printed ONCE)
+  list [--project <project_id>]  List grants with their keys nested (never tokens)
   revoke <grant_id> [--project <project_id>]
-                                 Revoke a capability grant
-
-Legacy (still supported):
-  run402 grants create <project_id> <wallet> <capability> [...]
-  run402 grants revoke <project_id> <grant_id>
+                                 Revoke a grant and every key minted against it
+  revoke-key <key_id> [--project <project_id>]
+                                 Revoke one grant key; the grant stays
+  rotate-key <key_id> [--project <project_id>]
+                                 Replace a lost key; the new token is printed ONCE
 
 Notes:
-  - Grants let a non-member wallet (an agent or CI principal) act on ONE project,
-    without making it a broad org member. Mutations require owner of the project's org.
+  - A grant is the permission row: this wallet may do this capability on this
+    project until this date. An agent with its own wallet needs only the grant.
+  - A grant key is a credential minted against exactly one grant: narrower than
+    it, spend-capped, expiring, revocable on its own, never an owner. Hand it to
+    an agent without a wallet: RUN402_GRANT_KEY=<token> run402 deploy ...
+  - Every subcommand requires owner of the project's org. Minting a key with a
+    sign-in session takes a fresh step-up.
+  - The key token is shown ONCE and cannot be read back. Store it immediately;
+    if you lose it, 'rotate-key' issues a new one.
   - capability examples: deploy, functions:write.
   - JSON in, JSON out.
 
 Examples:
   run402 grants create 0xf39Fd6...92266 --capability deploy --project prj_abc
-  run402 grants create 0xf39Fd6...92266 --capability functions:write --expires 2026-12-31T00:00:00Z
-  run402 grants revoke grt_xyz --project prj_abc
+  run402 grants create 0x90F3eB...F80a --capability deploy --key --project prj_abc
+  run402 grants list --project prj_abc
+  run402 grants revoke-key 5845f17b-... --project prj_abc
+  run402 grants revoke 1d86452e-... --project prj_abc
 `;
 
 const SUB_HELP = {
-  create: `run402 grants create — issue a per-project capability grant
+  create: `run402 grants create — issue a per-project capability grant, optionally with a grant key
 
 Usage:
-  run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]
-
-Legacy (still supported):
-  run402 grants create <project_id> <wallet> <capability> [options]
+  run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires-at <iso8601>]
+                       [--key [--kind <kind>] [--scope <json>] [--spend-cap <json>]]
 
 Arguments:
-  <wallet>       EVM address or named wallet the grant is issued to
+  <wallet>              EVM address or named wallet the grant is issued to
 
 Options:
-  --project <project_id>      Project to grant access to (defaults to the active project)
-  --capability <cap>  e.g. deploy, functions:write (alternative to the legacy positional)
-  --policy <json>     Capability-scoping policy object (gateway-interpreted)
-  --expires <iso8601> Expiry timestamp; omit for a non-expiring grant
+  --project <project_id>  Project to grant access to (defaults to the active project)
+  --capability <cap>      e.g. deploy, functions:write
+  --policy <json>         Capability-scoping policy object (gateway-interpreted)
+  --expires-at <iso8601>  Expiry; omit for a non-expiring grant. With --key the
+                          key takes the same expiry.
+  --key                   Also mint the grant's first grant key in the same
+                          transaction. Its token is printed ONCE.
+  --kind <kind>           Key kind (with --key). Default run402_agent_key, the
+                          only kind that returns a bearer token.
+  --scope <json>          Key scope (with --key), e.g. {"v":1,"capabilities":["deploy"]}.
+                          Defaults to the grant's own capability; never wider.
+  --spend-cap <json>      Key spend cap (with --key), e.g.
+                          {"v":1,"currency":"usd_micros","per_period":5000000,"period":"month"}
 
 Requires you to be an owner of the project's org.
+`,
+  list: `run402 grants list — list a project's grants with their grant keys
+
+Usage:
+  run402 grants list [--project <project_id>]
+
+Each grant carries its keys under "keys" (kind, scope, spend cap, expiry,
+revocation). Never returns a token or secret material.
 `,
   revoke: `run402 grants revoke — revoke a per-project capability grant
 
 Usage:
   run402 grants revoke <grant_id> [--project <project_id>]
 
-Legacy (still supported):
-  run402 grants revoke <project_id> <grant_id>
+Revokes the grant and every grant key minted against it. Requires you to be an
+owner of the project's org.
+`,
+  "revoke-key": `run402 grants revoke-key — revoke one grant key
 
+Usage:
+  run402 grants revoke-key <key_id> [--project <project_id>]
+
+Takes effect for every subsequent request. The grant and its other keys stay.
 Requires you to be an owner of the project's org.
+`,
+  "rotate-key": `run402 grants rotate-key — replace a grant key
+
+Usage:
+  run402 grants rotate-key <key_id> [--project <project_id>]
+
+Revokes the key and mints a fresh one against the same grant with the same
+kind, scope, spend cap and expiry. The NEW token is printed once. Use this when
+a token is lost or possibly exposed.
 `,
 };
 
-const CREATE_VALUE_FLAGS = ["--project", "--capability", "--policy", "--expires"];
+const CREATE_VALUE_FLAGS = ["--project", "--capability", "--policy", "--expires-at", "--kind", "--scope", "--spend-cap"];
+const KEY_ONLY_FLAGS = ["--kind", "--scope", "--spend-cap"];
+
+function warnTokenOnce(key) {
+  if (!key?.token) return;
+  console.error("");
+  console.error("The grant key token above is shown ONCE and cannot be read back.");
+  console.error("Store it now, then use it as: RUN402_GRANT_KEY=<token>");
+}
 
 async function create(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--help", "-h"], CREATE_VALUE_FLAGS);
+  assertKnownFlags(a, [...CREATE_VALUE_FLAGS, "--key", "--help", "-h"], CREATE_VALUE_FLAGS);
   const policyRaw = flagValue(a, "--policy");
-  const expiresAt = flagValue(a, "--expires");
-  const capabilityFlag = flagValue(a, "--capability");
+  const expiresAt = flagValue(a, "--expires-at") || undefined;
+  const capability = flagValue(a, "--capability");
+  const wantsKey = a.includes("--key");
+  const kind = flagValue(a, "--kind") || undefined;
+  const scopeRaw = flagValue(a, "--scope");
+  const spendCapRaw = flagValue(a, "--spend-cap");
   const { projectId, rest } = resolveProjectSelector(a, { valueFlags: CREATE_VALUE_FLAGS });
-  const expected = capabilityFlag ? 1 : 2;
-  const pos = requirePositionalCount(rest, CREATE_VALUE_FLAGS, {
-    min: expected,
-    max: expected,
-    command: "run402 grants create <wallet> --capability <cap> [--project <project_id>] [--policy <json>] [--expires <iso8601>]",
-    missing: capabilityFlag ? "Missing <wallet>." : "Missing <wallet> and/or <capability>.",
+  const [wallet] = requirePositionalCount(rest, CREATE_VALUE_FLAGS, {
+    min: 1,
+    max: 1,
+    command: "run402 grants create <wallet> --capability <cap> [--project <project_id>] [--key]",
+    missing: "Missing <wallet>.",
   });
-  const wallet = pos[0];
-  const capability = capabilityFlag ?? pos[1];
+  if (!capability) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --capability <cap>.",
+      hint: "run402 grants create <wallet> --capability deploy [--project <project_id>]",
+    });
+  }
+  if (!wantsKey) {
+    const stray = KEY_ONLY_FLAGS.filter((f) => a.includes(f));
+    if (stray.length > 0) {
+      fail({
+        code: "BAD_USAGE",
+        message: `${stray.join(", ")} describe a grant key; add --key to mint one.`,
+        hint: "run402 grants create <wallet> --capability <cap> --key [--kind <kind>] [--scope <json>] [--spend-cap <json>]",
+      });
+    }
+  }
   const policy = policyRaw != null ? parseFlagJson("--policy", policyRaw) : undefined;
+  let key;
+  if (wantsKey) {
+    key = {};
+    if (kind) key.kind = kind;
+    if (scopeRaw != null) key.scope = parseFlagJson("--scope", scopeRaw);
+    if (spendCapRaw != null) key.spendCap = parseFlagJson("--spend-cap", spendCapRaw);
+    if (expiresAt) key.expiresAt = expiresAt;
+  }
   try {
     const res = await getSdk().grants.create(projectId, {
       wallet,
       capability,
       policy,
-      expiresAt: expiresAt || undefined,
+      expiresAt,
+      key,
     });
     console.log(JSON.stringify(res, null, 2));
+    warnTokenOnce(res?.key);
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function revoke(args) {
+async function list(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
   const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
-  const [grantId] = requirePositionalCount(rest, ["--project"], {
-    min: 1,
-    max: 1,
-    command: "run402 grants revoke <grant_id> [--project <project_id>]",
-    missing: "Missing <grant_id>.",
+  requirePositionalCount(rest, ["--project"], {
+    min: 0,
+    max: 0,
+    command: "run402 grants list [--project <project_id>]",
+    missing: "",
   });
   try {
-    console.log(JSON.stringify(await getSdk().grants.revoke(projectId, grantId), null, 2));
+    console.log(JSON.stringify(await getSdk().grants.list(projectId), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
+function oneIdCommand({ verb, idName, method }) {
+  return async (args) => {
+    const a = normalizeArgv(args);
+    assertKnownFlags(a, ["--project", "--help", "-h"], ["--project"]);
+    const { projectId, rest } = resolveProjectSelector(a, { valueFlags: ["--project"] });
+    const [id] = requirePositionalCount(rest, ["--project"], {
+      min: 1,
+      max: 1,
+      command: `run402 grants ${verb} <${idName}> [--project <project_id>]`,
+      missing: `Missing <${idName}>.`,
+    });
+    try {
+      const res = await getSdk().grants[method](projectId, id);
+      console.log(JSON.stringify(res, null, 2));
+      warnTokenOnce(res?.key);
+    } catch (err) {
+      reportSdkError(err);
+    }
+  };
+}
+
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") {
     console.log(HELP);
@@ -128,7 +227,10 @@ export async function run(sub, args) {
   }
   switch (sub) {
     case "create": await create(args); break;
-    case "revoke": await revoke(args); break;
+    case "list": await list(args); break;
+    case "revoke": await oneIdCommand({ verb: "revoke", idName: "grant_id", method: "revoke" })(args); break;
+    case "revoke-key": await oneIdCommand({ verb: "revoke-key", idName: "key_id", method: "revokeKey" })(args); break;
+    case "rotate-key": await oneIdCommand({ verb: "rotate-key", idName: "key_id", method: "rotateKey" })(args); break;
     default:
       failUnknownSubcommand("grants", sub);
   }

package/lib/logs.mjs

@@ -62,7 +62,7 @@ Output:
 
 Auth:
   The project's cached service_key when present; otherwise your wallet /
-  session / delegate, which the gateway authorizes with project.read — an org
+  session / grant key, which the gateway authorizes with project.read — an org
   member or teammate agent following an error fingerprint's drill-down needs
   no project key.
 

package/lib/projects.mjs

@@ -164,7 +164,7 @@ Options:
 
 Notes:
   - Requires project.tenant_payments.read: org developer+ or a read-scoped
-    project grant/delegate.
+    project grant or grant key.
   - Output is the gateway's redacted payment page. Raw X-PAYMENT headers,
     authorization hashes, and internal metadata are never returned.
 `,

package/lib/sites.mjs

@@ -1,7 +1,7 @@
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { dirname, join, resolve } from "path";
-import { fileSetFromDir, delegateTokenFromEnv } from "#sdk/node";
+import { fileSetFromDir, grantKeyFromEnv } from "#sdk/node";
 import { walletAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
 import { resolveFilePathsInManifest } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
@@ -220,9 +220,9 @@ async function deploy(args) {
   if (opts.manifest) resolveFilePathsInManifest(manifest, dirname(resolve(opts.manifest)));
 
   // Preserve the aggressive early exit when no local wallet is configured.
-  // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
+  // A grant key holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   const stage = stageFilesToTempDir(manifest.files || []);
   try {
@@ -289,9 +289,9 @@ async function deployDir(args) {
   if (opts.target !== undefined) failUnsupportedTarget();
 
   // Preserve the aggressive early exit when no local wallet is configured.
-  // A delegate holds `deploy` and /apply/v1/plans accepts it; refusing locally
+  // A grant key holds `deploy` and /apply/v1/plans accepts it; refusing locally
   // would tell a wallet-less holder to run `run402 init` (see 4.11.2).
-  if (!delegateTokenFromEnv()) walletAuthHeaders("/apply/v1/plans");
+  if (!grantKeyFromEnv()) walletAuthHeaders("/apply/v1/plans");
 
   let fileSet;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.96.0",
+  "version": "4.97.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {

package/sdk/dist/errors.d.ts

@@ -120,7 +120,7 @@ export declare class ProjectNotFound extends Run402Error {
  * `NOT_AUTHORIZED`, `STEP_UP_REQUIRED`) — since 402 is reserved for
  * genuine payment challenges, this now also covers non-payment 403 denials
  * such as quota (`QUOTA_EXCEEDED`), lifecycle (`PROJECT_FROZEN` /
- * `PROJECT_DORMANT`), and delegate spend-cap denials. Check `body.code` (or
+ * `PROJECT_DORMANT`), and grant-key spend-cap denials. Check `body.code` (or
  * use `formatCanonicalErrorContext`-style parsing) to distinguish these
  * from a true auth failure.
  */