@alter-ai/cli 0.9.1 → 0.9.2

package/dist/cli.js

@@ -33,7 +33,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.9.1",
+  version: "0.9.2",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -80,7 +80,7 @@ var package_default = {
     esbuild: "0.28.1"
   },
   devDependencies: {
-    "@alter-ai/alter-sdk": "workspace:0.24.2",
+    "@alter-ai/alter-sdk": "workspace:0.25.0",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",
@@ -4743,7 +4743,14 @@ var AmbiguousGrantError = class extends BackendError {
   // scoped to the caller's own accessible set. Retry with the chosen
   // `grantId`.
   candidates;
-  constructor(message, providerId, accountIdentifiers, accountWasProvided, appUserIds, details, grantIds, candidates) {
+  // True when more grants matched than the error body can carry. It bounds
+  // EVERY disambiguator on this error — `candidates`, `accountIdentifiers`,
+  // `appUserIds` and `grantIds` all come from the same capped set — so a
+  // grant, account or user missing from any of them is not proof it does not
+  // exist. Narrow the request or call `listGrants()` for the authoritative
+  // set.
+  candidatesTruncated;
+  constructor(message, providerId, accountIdentifiers, accountWasProvided, appUserIds, details, grantIds, candidates, candidatesTruncated) {
     super(message, details);
     this.name = "AmbiguousGrantError";
     this.providerId = providerId;
@@ -4752,6 +4759,7 @@ var AmbiguousGrantError = class extends BackendError {
     this.appUserIds = appUserIds ?? [];
     this.grantIds = grantIds ?? [];
     this.candidates = candidates ?? [];
+    this.candidatesTruncated = candidatesTruncated ?? false;
   }
 };
 var NoDelegatedGrantError = class extends BackendError {
@@ -5724,6 +5732,14 @@ var ConnectSession = class {
    * Python SDK's scope_constraint_warnings coercion (parity contract).
    */
   scopeConstraintWarnings;
+  /**
+   * True when the session names exactly one provider: the hosted UI shows no
+   * picker, confirmation screen or Alter-branded page, and the browser widget
+   * can open the provider window straight from the application's click when
+   * the value is passed through as `open({ direct })`. False on a malformed
+   * wire value (informational, not load-bearing).
+   */
+  direct;
   constructor(data) {
     _assertString(data.session_token, "session_token", "ConnectSession");
     _assertString(data.connect_url, "connect_url", "ConnectSession");
@@ -5745,10 +5761,12 @@ var ConnectSession = class {
         (w) => typeof w === "string"
       ) : []
     );
+    this.direct = data.direct === true;
     Object.freeze(this);
   }
   toJSON() {
     return {
+      direct: this.direct,
       session_token: this.sessionToken,
       connect_url: this.connectUrl,
       expires_in: this.expiresIn,
@@ -10180,7 +10198,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.24.2";
+var SDK_VERSION = "0.25.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 function pyUnquote(s) {
   if (!s.includes("%")) return s;
@@ -11682,7 +11700,11 @@ ${label}:${value}`;
           appUserIds,
           errorData,
           grantIds,
-          candidates
+          candidates,
+          // Absent on the wire means "complete" — only a real cap emits the
+          // key, so a strict `=== true` keeps a stray falsy value from
+          // reading as truncation.
+          errorData.candidates_truncated === true
         );
       }
       if (errorData.error === "sibling_label_conflict") {
@@ -16755,7 +16777,7 @@ var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
 var DEFAULT_TIMEOUT_MS2 = 3e4;
-var CLI_VERSION = "0.9.1";
+var CLI_VERSION = "0.9.2";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -17740,6 +17762,13 @@ var AgentsNamespace2 = class {
     return expectDict(body, "agents.undeprecate_key", 200);
   }
 };
+function isRedirectUriAliasSpec(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const spec = value;
+  return typeof spec.label === "string" && typeof spec.description === "string";
+}
 function isSharedDevProviderEntry(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -17761,7 +17790,7 @@ function isProviderCatalogEntry(value) {
   const v = value;
   return typeof v.id === "string" && typeof v.name === "string" && typeof v.display_name === "string" && (v.category === null || typeof v.category === "string") && (v.supports_refresh === null || typeof v.supports_refresh === "boolean") && (v.supports_pkce === null || typeof v.supports_pkce === "boolean") && (v.available_environments === void 0 || Array.isArray(v.available_environments) && v.available_environments.every(
     (environment) => environment === "production" || environment === "sandbox"
-  )) && (v.scopes_configured_on_provider === void 0 || typeof v.scopes_configured_on_provider === "boolean") && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
+  )) && (v.scopes_configured_on_provider === void 0 || typeof v.scopes_configured_on_provider === "boolean") && (v.redirect_uri_alias === void 0 || v.redirect_uri_alias === null || isRedirectUriAliasSpec(v.redirect_uri_alias)) && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
     isProviderScopeCatalogEntry
   ) && (v.managed_credentials_available === void 0 || typeof v.managed_credentials_available === "boolean") && (v.managed_approved_scopes === void 0 || v.managed_approved_scopes === null || Array.isArray(v.managed_approved_scopes) && v.managed_approved_scopes.every(
     (scope) => typeof scope === "string"
@@ -17856,7 +17885,8 @@ var ProvidersNamespace = class {
       client_secret: options.client_secret,
       environment: options.environment,
       scopes: options.scopes,
-      redirect_uris: options.redirect_uris
+      redirect_uris: options.redirect_uris,
+      redirect_uri_alias: options.redirect_uri_alias
     });
     const body = await this.#client._call(
       "POST",
@@ -17893,6 +17923,7 @@ var ProvidersNamespace = class {
       environment: options.environment,
       scopes: options.scopes,
       redirect_uris: options.redirect_uris,
+      redirect_uri_alias: options.redirect_uri_alias,
       status: options.status
     });
     const body = await this.#client._call(
@@ -20794,7 +20825,9 @@ function buildAgentsCommand() {
       });
     }
   );
-  agents.command("create").description("Create a managed agent (returns one-shot API key)").option(APP_FLAG, APP_TARGET_DESC).option(
+  agents.command("create").description(
+    "Create a managed agent (returns its first API key ONCE, in the api_key field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).option(
     "--name <name>",
     "Agent name (stable identifier). Required unless --input is supplied."
   ).option("--display-name <name>", "Human-readable display name").option("--type <type>", "Type: agent|service (default: agent)", "agent").option(
@@ -21199,7 +21232,9 @@ function buildAgentsCommand() {
 `);
     });
   });
-  agents.command("mint-key").description("Mint a fresh API key for the agent (plaintext returned ONCE)").option(APP_FLAG, APP_TARGET_DESC).requiredOption(
+  agents.command("mint-key").description(
+    "Mint a fresh API key for the agent (plaintext returned ONCE, in the api_key field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--agent <agent-id>",
     "Agent ID",
     parseUuidArgument("--agent")
@@ -38281,7 +38316,25 @@ import { hostname as hostname3, platform as platform2 } from "os";
 import { spawn } from "child_process";
 var MIN_EPHEMERAL_PORT = 49152;
 var MAX_EPHEMERAL_PORT = 65535;
-var LISTENER_TIMEOUT_MS = 12e4;
+var LISTENER_TIMEOUT_MS = 6e5;
+function describeDeadline(ms) {
+  if (ms >= 6e4 && ms % 6e4 === 0) {
+    const minutes = ms / 6e4;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (ms >= 1e3) {
+    const seconds = Math.round(ms / 1e3);
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${ms} ms`;
+}
+var SELF_INSPECTION_SCOPE = "dashboard_pats:read";
+function withSelfInspectionScope(scopes) {
+  if (scopes.includes(SELF_INSPECTION_SCOPE)) {
+    return { scopes: [...scopes], added: false };
+  }
+  return { scopes: [...scopes, SELF_INSPECTION_SCOPE], added: true };
+}
 var CALLBACK_STATE_PATTERN = /^[0-9a-f]{64}$/;
 var DEFAULT_SCOPES = [
   "dashboard_apps:read",
@@ -38359,7 +38412,9 @@ function pickEphemeralPort() {
 }
 async function runBrowserDance(options) {
   const state = randomBytes2(32).toString("hex");
-  const scopes = options.scopes ?? DEFAULT_SCOPES;
+  const { scopes, added: addedSelfInspectionScope } = withSelfInspectionScope(
+    options.scopes ?? DEFAULT_SCOPES
+  );
   const dashboardUrl = options.dashboardUrl ?? deriveDashboardUrl(options.baseUrl);
   const openBrowser = options.openBrowser ?? defaultOpenBrowser;
   const timeoutMs = options.timeoutMs ?? LISTENER_TIMEOUT_MS;
@@ -38414,7 +38469,7 @@ async function runBrowserDance(options) {
       cleanupListener();
       reject(
         new Error(
-          "browser-dance timed out \u2014 operator did not complete the consent flow within 2 minutes"
+          `browser-dance timed out \u2014 operator did not complete the consent flow within ${describeDeadline(timeoutMs)}`
         )
       );
     }, timeoutMs);
@@ -38572,9 +38627,15 @@ async function runBrowserDance(options) {
     bindQuery = `&bind=cidr&cidr=${encodeURIComponent(options.cidrValue)}`;
   }
   const url2 = `${dashboardUrl}/cli-auth?port=${port}&state=${state}&scopes=${scopeQuery}&hostname=${encodeURIComponent(hostname3())}${bindQuery}`;
+  if (addedSelfInspectionScope) {
+    process.stderr.write(
+      `alter: added ${SELF_INSPECTION_SCOPE} to the requested scopes \u2014 the CLI verifies the sign-in (and \`alter auth status\`) with it.
+`
+    );
+  }
   process.stdout.write(
     `alter: opening browser at ${dashboardUrl}/cli-auth
-       (waiting up to 2 minutes for you to approve)\u2026
+       (waiting up to ${describeDeadline(timeoutMs)} for you to approve)\u2026
 `
   );
   openBrowser(url2);
@@ -39220,7 +39281,7 @@ function buildAuthCommand() {
     "Override the dashboard URL used by the browser-dance flow. Defaults to the backend URL with the leftmost `backend.` subdomain swapped for `portal.`. Use this when the dashboard isn't at the regex-derivable host (e.g. staging / self-hosted setups). Must use https://."
   ).option(
     "--scopes <list>",
-    "Comma-separated scope list to request on the browser-dance consent page (e.g. 'dashboard_apps:read,dashboard_keys:write'). Defaults to the full read+write set across the CLI surface \u2014 enough for every non-destructive day-to-day command. Opt in to admin / delete tiers explicitly: 'dashboard_keys:admin' for runtime-key admin ops, 'dashboard_apps:admin' to archive/unarchive an app, and 'dashboard_apps:delete' for cascade-delete an app (note the Destructive-Action Policy keeps :delete as its own verb, separate from :admin \u2014 :admin does not grant the cascade). Each entry is validated client-side against the dashboard scope catalog \u2014 typos fail fast. Mutually exclusive with --token / --token-file / --token-stdin \u2014 pre-minted PATs have their scope set baked at mint time on the dashboard's Settings page; combining the flags is a usage error."
+    "Comma-separated scope list to request on the browser-dance consent page (e.g. 'dashboard_apps:read,dashboard_keys:write'). Defaults to the full read+write set across the CLI surface \u2014 enough for every non-destructive day-to-day command. Opt in to admin / delete tiers explicitly: 'dashboard_keys:admin' for runtime-key admin ops, 'dashboard_apps:admin' to archive/unarchive an app, and 'dashboard_apps:delete' for cascade-delete an app (note the Destructive-Action Policy keeps :delete as its own verb, separate from :admin \u2014 :admin does not grant the cascade). The list REPLACES the default set, except that dashboard_pats:read is always added: the CLI verifies every sign-in (and `alter auth status`) with it, so a PAT without it cannot complete the login. Each entry is validated client-side against the dashboard scope catalog \u2014 typos fail fast. Mutually exclusive with --token / --token-file / --token-stdin \u2014 pre-minted PATs have their scope set baked at mint time on the dashboard's Settings page; combining the flags is a usage error."
   ).option(
     "--no-bind-ip",
     "Explicit opt-out of IP binding. This is now the DEFAULT for the browser-dance flow, so the flag is a no-op alias retained for scripts that pass it explicitly. The resulting PAT works from any source IP. Browser-dance flow only."
@@ -40965,7 +41026,9 @@ function buildKeysCommand() {
       emit2(format, row);
     });
   });
-  keys.command("mint").description("Mint a new scoped key (plaintext returned ONCE)").option(APP_FLAG, APP_TARGET_DESC).option(
+  keys.command("mint").description(
+    "Mint a new scoped key (plaintext returned ONCE, in the plain_key field \u2014 api_key is the key's metadata; capture it with --output json --fields plain_key or jq -r .plain_key)"
+  ).option(APP_FLAG, APP_TARGET_DESC).option(
     "--name <name>",
     "Display name. Required unless --input is supplied."
   ).option(
@@ -41027,7 +41090,7 @@ function buildKeysCommand() {
         }
         emit2(format, outcome2.result);
         process.stderr.write(
-          "alter: the plaintext key above is shown ONCE and cannot be retrieved later.\n"
+          "alter: the plain_key field above is the secret (api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
         );
         return;
       }
@@ -41120,7 +41183,7 @@ function buildKeysCommand() {
       }
       emit2(format, outcome.result);
       process.stderr.write(
-        "alter: the plaintext key above is shown ONCE and cannot be retrieved later.\n"
+        "alter: the plain_key field above is the secret (api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
       );
     }
   );
@@ -41137,7 +41200,7 @@ function buildKeysCommand() {
     });
   });
   keys.command("rotate").description(
-    "Rotate a key (new plaintext returned ONCE; old key enters grace until revoke). The app-key successor receives the organization's current finite default TTL. Requires dashboard_keys:write scope."
+    "Rotate a key (new plaintext returned ONCE, in the new_plain_key field; old key enters grace until revoke). The app-key successor receives the organization's current finite default TTL. Requires dashboard_keys:write scope."
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption("--key <key-id>", "Key ID", parseUuidArgument("--key")).option(
     "--scopes <list>",
     "Optional new scope set (defaults to the key's current scopes)"
@@ -41162,7 +41225,7 @@ function buildKeysCommand() {
         });
         emit2(format, result);
         process.stderr.write(
-          "alter: the new plaintext key above is shown ONCE and cannot be retrieved later.\n"
+          "alter: the new_plain_key field above is the new secret (new_api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
         );
       });
     }
@@ -41171,7 +41234,7 @@ function buildKeysCommand() {
     "Revoke a key immediately (cascades to derived keys). Requires dashboard_keys:admin scope."
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption("--key <key-id>", "Key ID", parseUuidArgument("--key")).option(
     "--force",
-    "Override the last-active-key guard (revoking an agent's only active key bricks it until a fresh key is minted)"
+    "Override the last-active-key guard (revoking the last active key on an app or an agent leaves whatever authenticates with it broken until a fresh key is minted)"
   ).option("--yes", "Skip the interactive y/N prompt").action(
     async (options) => {
       const resolvedAppId = await resolveAppOrExit(options.app);
@@ -42099,10 +42162,20 @@ var SECRET_COLUMNS = [
   { label: "CREATED", get: (s) => s.created_at },
   { label: "UPDATED", get: (s) => s.updated_at ?? "\u2014" }
 ];
+var DEPTH_COLUMN = {
+  label: "DEPTH",
+  get: (g) => g.depth == null ? "?" : String(g.depth)
+};
+var PARENT_COLUMN = {
+  label: "PARENT",
+  get: (g) => g.parent_grant_id === void 0 ? "?" : g.parent_grant_id ?? "\u2014",
+  maxWidth: 36
+};
 var GRANT_COLUMNS2 = [
   { label: "GRANT_ID", get: (g) => g.grant_id, maxWidth: 36 },
   { label: "PRINCIPAL", get: (g) => g.principal_type },
   { label: "LABEL", get: (g) => g.label ?? "\u2014", maxWidth: 24 },
+  DEPTH_COLUMN,
   { label: "STATUS", get: (g) => g.status },
   { label: "CREATED", get: (g) => g.created_at },
   {
@@ -42114,6 +42187,9 @@ var GRANT_COLUMNS2 = [
     get: (g) => g.grant_expires_at ?? "\u2014"
   }
 ];
+var AGENT_GRANT_COLUMNS = GRANT_COLUMNS2.flatMap(
+  (col) => col === DEPTH_COLUMN ? [col, PARENT_COLUMN] : [col]
+);
 var USER_COLUMNS = [
   { label: "ID", get: (u) => u.id, maxWidth: 36 },
   { label: "EMAIL", get: (u) => u.email ?? "\u2014" },
@@ -42190,7 +42266,9 @@ function buildGrantsSubcommand() {
             label: isOptionalString,
             created_at: isString,
             expires_at: isOptionalString,
-            grant_expires_at: isAbsentOrOptionalString
+            grant_expires_at: isAbsentOrOptionalString,
+            parent_grant_id: isAbsentOrOptionalString,
+            depth: isAbsentOrOptionalNumber
           },
           "managed-secrets.grants.list"
         );
@@ -42238,11 +42316,14 @@ function buildGrantsSubcommand() {
             label: isOptionalString,
             created_at: isString,
             expires_at: isOptionalString,
-            grant_expires_at: isAbsentOrOptionalString
+            grant_expires_at: isAbsentOrOptionalString,
+            // Rendered through ``AGENT_GRANT_COLUMNS`` (adds PARENT).
+            parent_grant_id: isAbsentOrOptionalString,
+            depth: isAbsentOrOptionalNumber
           },
           "managed-secrets.grants.list-for-agent"
         );
-        emit2(format, rows, GRANT_COLUMNS2);
+        emit2(format, rows, AGENT_GRANT_COLUMNS);
       });
     }
   );
@@ -43726,7 +43807,9 @@ function buildIdentityProvidersCommand() {
   const webhook = idp.command("webhook").description(
     "Manage an identity provider's webhook integration (requires dashboard_identity_providers:webhooks)"
   );
-  webhook.command("enable").description("Enable webhook integration (returns the signing secret ONCE)").option(APP_FLAG, APP_TARGET_DESC).requiredOption(
+  webhook.command("enable").description(
+    "Enable webhook integration (returns the signing secret ONCE, in the webhook_secret field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--provider <provider-id>",
     "Identity provider ID",
     parseUuidArgument("--provider")
@@ -43758,7 +43841,7 @@ function buildIdentityProvidersCommand() {
         emit2(format, row);
         if (typeof row["webhook_secret"] === "string") {
           process.stderr.write(
-            "alter: the webhook_secret above is shown ONCE and cannot be retrieved later.\n"
+            "alter: the webhook_secret field above is shown ONCE and cannot be retrieved later.\n"
           );
         }
         return null;
@@ -43878,7 +43961,7 @@ alter: re-run with --force --confirm <issuer-host> to revoke those grants and di
     }
   );
   webhook.command("rotate").description(
-    "Rotate the webhook signing secret (invalidates the previous; returns the new one ONCE)"
+    "Rotate the webhook signing secret (invalidates the previous; returns the new one ONCE, in the webhook_secret field)"
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--provider <provider-id>",
     "Identity provider ID",
@@ -43926,7 +44009,7 @@ alter: re-run with --force --confirm <issuer-host> to revoke those grants and di
         emit2(format, row);
         if (typeof row["webhook_secret"] === "string") {
           process.stderr.write(
-            "alter: the webhook_secret above is shown ONCE and cannot be retrieved later.\n"
+            "alter: the webhook_secret field above is shown ONCE and cannot be retrieved later.\n"
           );
         }
         return null;
@@ -45327,8 +45410,12 @@ function buildPolicyCommand() {
 import { Command as Command20 } from "commander";
 var CREDENTIAL_SOURCES = ["custom", "shared_dev"];
 var PROVIDER_ENVIRONMENTS = ["production", "sandbox"];
-async function providerCatalogError(client, providerId, environment, credentialSource, scopes, scopesRequired = false) {
-  if (environment === void 0 && scopes === void 0 && !scopesRequired) {
+async function providerCatalogError(client, providerId, environment, credentialSource, scopes, options = {}) {
+  const create = options.create === true;
+  const redirectUriAlias = options.redirectUriAlias;
+  const readStoredProvider = options.readStoredProvider;
+  const switchesToCustom = !create && credentialSource === "custom" && readStoredProvider !== void 0;
+  if (environment === void 0 && scopes === void 0 && redirectUriAlias === void 0 && !create && !switchesToCustom) {
     return null;
   }
   if (!providerId) {
@@ -45350,6 +45437,23 @@ async function providerCatalogError(client, providerId, environment, credentialS
   if (environment !== void 0 && credentialSource === "shared_dev" && environment !== "production") {
     return "alter: --credential-source shared_dev only supports --environment production; use custom sandbox credentials\n";
   }
+  const aliasSpec = provider.redirect_uri_alias ?? null;
+  const aliasError = redirectUriAliasError(
+    providerId,
+    aliasSpec,
+    credentialSource,
+    redirectUriAlias,
+    create
+  );
+  if (aliasError !== null) return aliasError;
+  if (switchesToCustom && readStoredProvider !== void 0 && aliasSpec !== null && redirectUriAlias === void 0) {
+    const storedAliasError = await redirectUriAliasStoredStateError(
+      readStoredProvider,
+      providerId,
+      aliasSpec
+    );
+    if (storedAliasError !== null) return storedAliasError;
+  }
   const availableScopes = provider.available_scopes ?? {};
   if (Object.keys(availableScopes).length === 0) {
     if (scopes !== void 0 && scopes.length > 0) {
@@ -45359,7 +45463,7 @@ async function providerCatalogError(client, providerId, environment, credentialS
     }
     return null;
   }
-  if (scopesRequired && scopes === void 0) {
+  if (create && scopes === void 0) {
     return `alter: provider '${providerId}' requires at least one scope (pass --scopes, or "scopes" in --input)
 `;
   }
@@ -45390,6 +45494,41 @@ async function providerCatalogError(client, providerId, environment, credentialS
   }
   return null;
 }
+function redirectUriAliasError(providerId, spec, credentialSource, redirectUriAlias, create) {
+  if (spec === null) {
+    return redirectUriAlias === void 0 ? null : `alter: --redirect-uri-alias is not used by ${providerId}
+`;
+  }
+  if (redirectUriAlias !== void 0 && credentialSource === "shared_dev") {
+    return `alter: --redirect-uri-alias is only accepted with --credential-source custom (Alter-managed credentials carry their own ${spec.label})
+`;
+  }
+  const custom3 = credentialSource === void 0 || credentialSource === "custom";
+  if (create && custom3 && redirectUriAlias === void 0) {
+    return redirectUriAliasRequiredError(providerId, spec);
+  }
+  return null;
+}
+function redirectUriAliasRequiredError(providerId, spec) {
+  return `alter: ${providerId} requires --redirect-uri-alias (${spec.label}): ${spec.description} (pass --redirect-uri-alias, or "redirect_uri_alias" in --input)
+`;
+}
+async function redirectUriAliasStoredStateError(readStoredProvider, providerId, spec) {
+  let current;
+  try {
+    const row = await readStoredProvider();
+    if (row === null || typeof row !== "object") return null;
+    current = row;
+  } catch {
+    return null;
+  }
+  const storedSource = typeof current.credential_source === "string" ? current.credential_source : "custom";
+  const storedAlias = typeof current.redirect_uri_alias === "string" ? current.redirect_uri_alias.trim() : "";
+  if (storedSource === "shared_dev" || storedAlias.length === 0) {
+    return redirectUriAliasRequiredError(providerId, spec);
+  }
+  return null;
+}
 function storedProviderReader(client, appId, providerId) {
   let pending2 = null;
   return () => pending2 ??= client.providers.get(appId, providerId);
@@ -45475,6 +45614,16 @@ var PROVIDER_COLUMNS = [
   // between test money and real money.
   { label: "ENV", get: (p) => p.environment ?? "production" },
   { label: "SCOPES", get: (p) => p.scopes.join(",") || "\u2014", maxWidth: 40 },
+  // The provider-issued redirect name (eBay's RuName). Its provider-side
+  // label is on ``list-catalog``'s REDIRECT ALIAS column. Wide enough for a
+  // real RuName (``<user>-<app>-<title>-<token>``, ~40–60 chars) to print
+  // untruncated — an operator copies this column back into a provider
+  // console, so a clipped value is worse than none.
+  {
+    label: "REDIRECT ALIAS",
+    get: (p) => p.redirect_uri_alias ?? "\u2014",
+    maxWidth: 60
+  },
   { label: "GRANTS", get: (p) => String(p.grants_count) },
   { label: "STATUS", get: (p) => p.status },
   {
@@ -45558,6 +45707,22 @@ function collectRedirectUris(value, previous = []) {
   const next = value.split(",").map((s) => s.trim()).filter(Boolean);
   return [...previous, ...next];
 }
+function validateRedirectUriAliasOrExit(raw, source = "--redirect-uri-alias") {
+  if (raw === void 0) return void 0;
+  const value = raw.trim();
+  if (value.length === 0) {
+    process.stderr.write(`alter: ${source} requires a non-empty value
+`);
+    process.exit(EXIT_USAGE);
+  }
+  if (value.length > 255) {
+    process.stderr.write(`alter: ${source} must be at most 255 characters
+`);
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
+var INPUT_ALIAS_SOURCE = '"redirect_uri_alias" in --input';
 function surfaceProviderResponse(row) {
   if (typeof row !== "object" || row === null) return;
   const r = row;
@@ -45627,6 +45792,7 @@ function buildProvidersCommand() {
           // "production" — defeating the tolerance this line exists for.
           environment: isAbsentOrOptionalString,
           scopes: (v) => Array.isArray(v),
+          redirect_uri_alias: isAbsentOrOptionalString,
           status: isString,
           grants_count: (v) => typeof v === "number"
         },
@@ -45675,6 +45841,13 @@ function buildProvidersCommand() {
           get: (p) => p.managed_approved_scopes === void 0 ? "?" : p.managed_approved_scopes === null ? "\u2014" : p.managed_approved_scopes.join(",") || "(none)",
           maxWidth: 36
         },
+        // Providers that take a provider-issued NAME as redirect_uri
+        // instead of the callback URL show its label (eBay: RuName) —
+        // ``create`` then requires ``--redirect-uri-alias``.
+        {
+          label: "REDIRECT ALIAS",
+          get: (p) => p.redirect_uri_alias?.label ?? "\u2014"
+        },
         { label: "STATUS", get: (p) => p.status }
       ]);
     });
@@ -45703,9 +45876,12 @@ function buildProvidersCommand() {
     "--redirect-uri <uri>",
     "Add a redirect URI. Repeat the flag (``--redirect-uri A --redirect-uri B``) or pass a comma-separated list (``--redirect-uri A,B``); both forms accumulate.",
     collectRedirectUris
+  ).option(
+    "--redirect-uri-alias <name>",
+    "The provider-issued redirect name sent as redirect_uri in place of the callback URL \u2014 required for providers that use one (eBay's RuName); see `alter providers list-catalog`."
   ).option(
     "--input <path>",
-    "JSON wire body from file (@/path/to/body.json) or stdin (-). Mirrors ``gh api --input``. Replaces the per-field flags (``--provider``, ``--credential-source``, ``--client-id``, ``--client-secret``, ``--environment``, ``--scopes``, ``--redirect-uri``); the body is sent to ``POST /apps/<app>/providers`` verbatim. If both --input and per-field flags are supplied, --input wins and the per-field flags are ignored (with a warning)."
+    "JSON wire body from file (@/path/to/body.json) or stdin (-). Mirrors ``gh api --input``. Replaces the per-field flags (``--provider``, ``--credential-source``, ``--client-id``, ``--client-secret``, ``--environment``, ``--scopes``, ``--redirect-uri``, ``--redirect-uri-alias``); the body is sent to ``POST /apps/<app>/providers`` verbatim. If both --input and per-field flags are supplied, --input wins and the per-field flags are ignored (with a warning)."
   ).option(
     "--output <format>",
     "Output format: json|jsonl|table (default: json)",
@@ -45723,7 +45899,8 @@ function buildProvidersCommand() {
           "clientSecret",
           "environment",
           "scopes",
-          "redirectUri"
+          "redirectUri",
+          "redirectUriAlias"
         ].filter((k) => {
           if (k === "credentialSource")
             return options.credentialSource !== "custom";
@@ -45732,6 +45909,10 @@ function buildProvidersCommand() {
           return options[k] !== void 0;
         });
         warnInputOverridesPerFieldFlags(perField.map(optionKeyToFlag));
+        const bodyRedirectUriAlias = validateRedirectUriAliasOrExit(
+          inputBodyString(body, "redirect_uri_alias"),
+          INPUT_ALIAS_SOURCE
+        );
         const inputPreflightError = await withClient(
           async (client) => {
             const bodyEnvironment = inputBodyString(body, "environment");
@@ -45741,7 +45922,7 @@ function buildProvidersCommand() {
               bodyEnvironment,
               inputBodyString(body, "credential_source"),
               inputBodyStringArray(body, "scopes"),
-              true
+              { create: true, redirectUriAlias: bodyRedirectUriAlias }
             );
             if (catalogError !== null) return catalogError;
             const availabilityError = await sharedDevAvailabilityError(
@@ -45810,6 +45991,9 @@ function buildProvidersCommand() {
         validateUrlOrExit("--redirect-uri", uri);
       }
       const redirects = options.redirectUri && options.redirectUri.length > 0 ? options.redirectUri : void 0;
+      const redirectUriAlias = validateRedirectUriAliasOrExit(
+        options.redirectUriAlias
+      );
       const environmentPreflightError = await withClient(
         async (client) => {
           const catalogError = await providerCatalogError(
@@ -45818,7 +46002,7 @@ function buildProvidersCommand() {
             environment,
             credentialSource,
             scopes,
-            true
+            { create: true, redirectUriAlias }
           );
           if (catalogError !== null) return catalogError;
           const availabilityError = await sharedDevAvailabilityError(
@@ -45837,7 +46021,8 @@ function buildProvidersCommand() {
             // Scopeless provider with --scopes omitted: the dashboard's
             // exact wire body for these providers is ``scopes: []``.
             scopes: scopes ?? [],
-            redirect_uris: redirects
+            redirect_uris: redirects,
+            redirect_uri_alias: redirectUriAlias
           });
           surfaceProviderResponse(row);
           emit2(format, row);
@@ -45871,6 +46056,7 @@ function buildProvidersCommand() {
             credential_source: isOptionalString,
             environment: isAbsentOrOptionalString,
             scopes: (v) => Array.isArray(v),
+            redirect_uri_alias: isAbsentOrOptionalString,
             status: isString,
             grants_count: (v) => typeof v === "number"
           },
@@ -45898,6 +46084,9 @@ function buildProvidersCommand() {
     "--redirect-uri <uri>",
     "Replace redirect URIs. Repeat the flag or pass a comma-separated list; both forms accumulate.",
     collectRedirectUris
+  ).option(
+    "--redirect-uri-alias <name>",
+    "Replace the provider-issued redirect name sent as redirect_uri in place of the callback URL (eBay's RuName). Accepted only for providers that use one; see `alter providers list-catalog`."
   ).option(
     "--status <status>",
     "New status: active | disabled (rejected at the CLI if not exactly one of the two values)"
@@ -45927,24 +46116,33 @@ function buildProvidersCommand() {
           "environment",
           "scopes",
           "redirectUri",
+          "redirectUriAlias",
           "status"
         ].filter((k) => options[k] !== void 0);
         warnInputOverridesPerFieldFlags(perField.map(optionKeyToFlag));
+        const bodyRedirectUriAlias = validateRedirectUriAliasOrExit(
+          inputBodyString(body, "redirect_uri_alias"),
+          INPUT_ALIAS_SOURCE
+        );
         const inputPreflightError = await withClient(
           async (client) => {
+            const readStoredProvider = storedProviderReader(
+              client,
+              appId,
+              options.provider
+            );
             const catalogError = await providerCatalogError(
               client,
               options.provider,
               inputBodyString(body, "environment"),
               inputBodyString(body, "credential_source"),
-              inputBodyStringArray(body, "scopes")
+              inputBodyStringArray(body, "scopes"),
+              {
+                redirectUriAlias: bodyRedirectUriAlias,
+                readStoredProvider
+              }
             );
             if (catalogError !== null) return catalogError;
-            const readStoredProvider = storedProviderReader(
-              client,
-              appId,
-              options.provider
-            );
             const storedStateError = await sharedDevStoredStateError(
               readStoredProvider,
               options.provider,
@@ -46006,21 +46204,25 @@ function buildProvidersCommand() {
         validateUrlOrExit("--redirect-uri", uri);
       }
       const redirects = options.redirectUri && options.redirectUri.length > 0 ? options.redirectUri : void 0;
+      const redirectUriAlias = validateRedirectUriAliasOrExit(
+        options.redirectUriAlias
+      );
       const updatePreflightError = await withClient(
         async (client) => {
+          const readStoredProvider = storedProviderReader(
+            client,
+            appId,
+            options.provider
+          );
           const catalogError = await providerCatalogError(
             client,
             options.provider,
             environment,
             credentialSource,
-            scopes
+            scopes,
+            { redirectUriAlias, readStoredProvider }
           );
           if (catalogError !== null) return catalogError;
-          const readStoredProvider = storedProviderReader(
-            client,
-            appId,
-            options.provider
-          );
           const storedStateError = await sharedDevStoredStateError(
             readStoredProvider,
             options.provider,
@@ -46044,6 +46246,7 @@ function buildProvidersCommand() {
             ...options.skipPreflight ? { skip_preflight: true } : {},
             scopes,
             redirect_uris: redirects,
+            redirect_uri_alias: redirectUriAlias,
             status: providerStatus
           });
           surfaceProviderResponse(row);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@alter-ai/cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@alter-ai/cli",
-      "version": "0.9.1",
+      "version": "0.9.2",
       "dependencies": {
         "commander": "12.1.0",
         "posthog-node": "4.18.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Command-line interface for the Alter Vault dev portal — scripted dashboard automation.",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
     "esbuild": "0.28.1"
   },
   "devDependencies": {
-    "@alter-ai/alter-sdk": "workspace:0.24.2",
+    "@alter-ai/alter-sdk": "workspace:0.25.0",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",