@envpilot/cli 1.17.0 → 1.19.0

package/dist/{chunk-VEZRLJGM.js → chunk-WLHMHDPX.js}

@@ -7,7 +7,7 @@ function initSentry() {
   Sentry.init({
     dsn,
     environment: "cli",
-    release: true ? "1.17.0" : "0.0.0",
+    release: true ? "1.19.0" : "0.0.0",
     // All EnvPilot surfaces report to one Sentry project; the surface tag
     // is how dashboards tell web / cli / extension events apart.
     initialScope: { tags: { surface: "cli" } },
@@ -54,16 +54,12 @@ import Conf from "conf";
 
 // src/lib/roles.ts
 var ROLE_LEVEL = {
-  owner: 4,
-  project_manager: 3,
-  team_lead: 2,
-  developer: 1
-};
-var ORG_ROLE_LABELS = {
-  owner: "Owner",
-  project_manager: "Project Manager",
-  team_lead: "Team Lead",
-  developer: "Developer"
+  owner: 100,
+  project_manager: 80,
+  team_lead: 60,
+  editor: 50,
+  developer: 40,
+  viewer: 20
 };
 function normalizeOrgRole(role) {
   switch (role) {
@@ -71,20 +67,20 @@ function normalizeOrgRole(role) {
       return "owner";
     case "member":
       return "developer";
-    case "owner":
-    case "project_manager":
-    case "team_lead":
-    case "developer":
-      return role;
-    default:
+    case void 0:
+    case null:
+    case "":
       return "developer";
+    default:
+      return role;
   }
 }
 function roleLevel(role) {
-  return ROLE_LEVEL[normalizeOrgRole(role)];
+  return ROLE_LEVEL[normalizeOrgRole(role)] ?? 0;
 }
-function formatRoleLabel(role) {
-  return ORG_ROLE_LABELS[normalizeOrgRole(role)];
+function formatRoleLabel(role, meta) {
+  if (meta?.displayName) return meta.displayName;
+  return normalizeOrgRole(role).split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 function isFileWritable(access) {
   if (access.role === "owner") return true;
@@ -93,7 +89,7 @@ function isFileWritable(access) {
     case "project_manager":
     case "team_lead":
       return true;
-    case "developer":
+    default:
       return access.hasWriteAccess;
   }
 }
@@ -153,7 +149,7 @@ function probeCache(projectId, environment, organizationId, ttlSeconds) {
   const fresh = isFresh(entry, ttlSeconds);
   return { hit: true, fresh, entry };
 }
-function writeCache(projectId, environment, organizationId, variables, serverFingerprint) {
+function writeCache(projectId, environment, organizationId, variables, serverFingerprint, meta) {
   try {
     const cacheDir = getCacheDir();
     mkdirSync(cacheDir, { recursive: true, mode: 448 });
@@ -168,7 +164,9 @@ function writeCache(projectId, environment, organizationId, variables, serverFin
       environment,
       organizationId,
       apiUrl: getApiUrl(),
-      fingerprint: serverFingerprint ?? computeFingerprint(variables)
+      fingerprint: serverFingerprint ?? computeFingerprint(variables),
+      ...meta?.decryptionFailures?.length ? { decryptionFailures: meta.decryptionFailures } : {},
+      ...meta?.scopeRestricted ? { scopeRestricted: true } : {}
     };
     writeFileSync(path, JSON.stringify(entry, null, 2), {
       encoding: "utf-8",
@@ -474,7 +472,7 @@ function isInteractiveTerminal() {
 async function openTUI() {
   const [{ render }, { CLIApp }, { PressAnyKey }] = await Promise.all([
     import("ink"),
-    import("./app-7IL7GWIN.js"),
+    import("./app-VAJPLVBA.js"),
     import("./press-any-key-64XFP4O2.js")
   ]);
   while (true) {
@@ -622,6 +620,8 @@ function formatRole(role) {
       return chalk.blue(label);
     case "developer":
       return chalk.yellow(label);
+    default:
+      return label;
   }
 }
 function roleNotice(role) {
@@ -1084,7 +1084,18 @@ var refs = {
   ),
   pullValues: fnRef("features/variables/values:pullValues"),
   pushBulk: fnRef("features/variables/values:pushBulk"),
-  createVariableRequest: fnRef("features/variables/requests/actions:createWithValue")
+  createVariableRequest: fnRef("features/variables/requests/actions:createWithValue"),
+  reviewRequest: fnRef("features/variables/requests/mutations:review"),
+  approveRequestWithValue: fnRef("features/variables/requests/actions:approveWithValue"),
+  cancelRequest: fnRef(
+    "features/variables/requests/mutations:cancel"
+  ),
+  removeVariable: fnRef(
+    "features/variables/mutations:remove"
+  ),
+  removeVariableFromEnvironment: fnRef("features/variables/mutations:removeFromEnvironment"),
+  resolveProjectRoles: fnRef("features/auth/queries:resolveLegacyRoles"),
+  getVariableRequest: fnRef("features/variables/requests/queries:getById")
 };
 async function convexQuery(ref, ...args) {
   const client = await getConvexClient();
@@ -1227,20 +1238,31 @@ var APIClient = class {
    * Byte-compatible with the fingerprint writeCache stores from a full fetch:
    * both hash `${_id}:${version}:${updatedAt}` over the accessible variables in
    * the requested environment.
+   *
+   * Also reports how the environment filter carved up the accessible set, so
+   * `run` can say "injected 8 of 12 — 4 exist only in staging" instead of
+   * silently dropping variables that live in other environments.
    */
   async checkFingerprint(projectId, environment, _organizationId) {
     const rows = await convexQuery(refs.listVariablesWithAccess, { projectId });
-    const filtered = rows.filter(
-      (row) => row.hasAccess && (!environment || row.environments.includes(environment))
+    const accessible = rows.filter((row) => row.hasAccess);
+    const matching = accessible.filter(
+      (row) => !environment || row.environments.includes(environment)
     );
-    const asVariables = filtered.map(
+    const otherEnvKeys = accessible.filter((row) => environment && !row.environments.includes(environment)).map((row) => ({ key: row.key, environments: row.environments }));
+    const asVariables = matching.map(
       (row) => ({
         _id: row._id,
         version: row.version,
         updatedAt: row.updatedAt
       })
     );
-    return computeFingerprint(asVariables);
+    return {
+      fingerprint: computeFingerprint(asVariables),
+      totalAccessible: accessible.length,
+      matchingCount: matching.length,
+      otherEnvKeys
+    };
   }
   /** List variable requests for a project (Convex). */
   async listVariableRequests(projectId, status) {
@@ -1330,7 +1352,8 @@ var APIClient = class {
       environmentScope: result.meta.environmentScope,
       hasWriteAccess: result.meta.hasWriteAccess,
       scopeRestricted: result.meta.scopeRestricted,
-      decryptionFailures: result.meta.decryptionFailures
+      decryptionFailures: result.meta.decryptionFailures,
+      capabilities: result.meta.capabilities
     };
     return {
       variables,
@@ -1366,6 +1389,125 @@ var APIClient = class {
     }
     return created;
   }
+  /** Approve or reject a request that already carries a value (developer flow). */
+  async reviewRequest(requestId, action, reviewReason) {
+    await convexMutation(refs.reviewRequest, {
+      requestId,
+      action,
+      reviewReason
+    });
+  }
+  /**
+   * Approve a VALUELESS (machine) request by supplying the secret value —
+   * the server encrypts it into the vault at approval time.
+   */
+  async approveRequestWithValue(requestId, value, reviewReason) {
+    await convexAction(refs.approveRequestWithValue, {
+      requestId,
+      value,
+      reviewReason
+    });
+  }
+  /** Cancel a pending request (requester or a reviewer). */
+  async cancelRequest(requestId) {
+    await convexMutation(refs.cancelRequest, { requestId });
+  }
+  /**
+   * Role + capability snapshot for the caller in one project. Used by the
+   * CLI ONLY to route flows (direct write vs request) and phrase denials —
+   * the Convex mutations remain the enforcement boundary.
+   */
+  async resolveProjectRoles(projectId) {
+    return convexQuery(refs.resolveProjectRoles, { projectId });
+  }
+  /**
+   * One request by id — enough to know whether it is pending and whether it
+   * carries a value (machine requests don't; approval must supply one).
+   */
+  async getVariableRequest(requestId) {
+    return convexQuery(refs.getVariableRequest, { requestId });
+  }
+  /** Soft-delete a single variable by id (moves it to trash). */
+  async removeVariable(variableId) {
+    await convexMutation(refs.removeVariable, { variableId });
+  }
+  /**
+   * Set a single variable's value in one environment — upsert via the bulk
+   * vault path with merge semantics (creates if absent, updates if present;
+   * leaves every other variable untouched).
+   *
+   * Throws when the server accepted the call but wrote nothing (the single
+   * entry was skipped/denied by variable-level authorization) — a silent
+   * "success" here would lie to the user.
+   */
+  async setVariable(projectId, environment, key, value, opts) {
+    const result = await convexAction(refs.pushBulk, {
+      projectId,
+      environment,
+      variables: [
+        {
+          key,
+          value,
+          description: opts?.description,
+          isSensitive: opts?.isSensitive
+        }
+      ],
+      mode: "merge"
+    });
+    if (result.deniedKeys?.includes(key)) {
+      throw new APIError(
+        `You do not have write access to ${key}.`,
+        403,
+        "PERMISSION_DENIED"
+      );
+    }
+    return {
+      created: result.created,
+      updated: result.updated,
+      unchanged: result.created === 0 && result.updated === 0
+    };
+  }
+  /**
+   * Metadata for the active variable holding `key` in `environment` (id +
+   * the FULL environments list, so single-env commands can detect that the
+   * variable is shared across environments). Returns null if absent.
+   */
+  async findVariable(projectId, environment, key) {
+    const rows = await convexQuery(refs.listVariablesWithAccess, {
+      projectId,
+      limit: 5e3
+    });
+    const match = rows.find(
+      (row) => row.key === key && row.hasAccess && row.environments.includes(environment)
+    );
+    return match ? { _id: match._id, environments: match.environments } : null;
+  }
+  /**
+   * Metadata-only variable listing for an environment (no vault reads, no
+   * value-access audit entries). Used by `diff` without --values.
+   */
+  async listVariableKeys(projectId, environment) {
+    const limit = 5e3;
+    const rows = await convexQuery(refs.listVariablesWithAccess, {
+      projectId,
+      limit
+    });
+    return {
+      keys: rows.filter((row) => row.environments.includes(environment)).map((row) => row.key),
+      truncated: rows.length >= limit
+    };
+  }
+  /**
+   * Re-scope a shared variable: atomically detach `environment` from it
+   * server-side (the mutation re-reads the row, so a concurrent edit can't
+   * be clobbered by a stale client-side array).
+   */
+  async removeVariableFromEnvironment(variableId, environment) {
+    await convexMutation(refs.removeVariableFromEnvironment, {
+      variableId,
+      environment
+    });
+  }
 };
 function createAPIClient() {
   return new APIClient();
@@ -1566,7 +1708,9 @@ var projectSchema = z2.object({
   // Unified-role fields (optional so legacy server responses still parse)
   unifiedRole: z2.string().nullable().optional(),
   assigned: z2.boolean().optional(),
-  environmentScope: z2.array(z2.string()).nullable().optional()
+  environmentScope: z2.array(z2.string()).nullable().optional(),
+  // Resolved capability map (additive; absent on older deployments).
+  capabilities: z2.record(z2.string(), z2.boolean()).nullable().optional()
 });
 var variableTagSchema = z2.object({
   _id: z2.string(),
@@ -1599,7 +1743,9 @@ var variablesMetaSchema = z2.object({
   grantOnly: z2.boolean().optional(),
   environmentScope: z2.array(z2.string()).nullable().optional(),
   hasWriteAccess: z2.boolean().optional(),
-  scopeRestricted: z2.boolean().optional()
+  scopeRestricted: z2.boolean().optional(),
+  // Resolved capability map (additive; absent on older deployments).
+  capabilities: z2.record(z2.string(), z2.boolean()).optional()
 }).passthrough();
 var environmentSchema = z2.enum([
   "development",
@@ -2950,6 +3096,9 @@ function validateEnvVars(vars) {
   }
   return { valid, invalid };
 }
+function validateEnvironment(env) {
+  return environmentSchema2.safeParse(env).success;
+}
 
 // src/commands/push.ts
 var pushCommand = new Command4("push").description("Upload local .env file to cloud").option(
@@ -3949,8 +4098,8 @@ async function handlePath() {
   ]);
 }
 async function handleReset() {
-  const inquirer7 = await import("inquirer");
-  const { confirm } = await inquirer7.default.prompt([
+  const inquirer9 = await import("inquirer");
+  const { confirm } = await inquirer9.default.prompt([
     {
       type: "confirm",
       name: "confirm",
@@ -4707,7 +4856,7 @@ import { Command as Command14 } from "commander";
 import crossSpawn from "cross-spawn";
 import { constants as osConstants } from "os";
 import chalk15 from "chalk";
-var DEFAULT_TTL = 3600;
+var DEFAULT_TTL = 0;
 var runCommand = new Command14("run").description(
   "Run a command with project secrets injected as environment variables. Secrets are injected into the child process in-memory (no .env file is written), but a decrypted copy is cached locally at ~/.config/envpilot/run-cache (mode 0600, same protection as a .env) to avoid re-fetching on every run. Use --no-cache to skip the cache, or `envpilot logout` to purge it."
 ).argument("[command...]", "Command and arguments to execute").option(
@@ -4730,7 +4879,7 @@ var runCommand = new Command14("run").description(
   'Run the command string through your shell ($SHELL or /bin/sh -c "..."), enabling pipes, &&, and $VAR expansion. Without this flag the command is executed directly with no shell, so arguments are passed through verbatim (safe from shell injection).'
 ).option("-q, --quiet", "Suppress informational messages").option("--no-cache", "Skip cache and always fetch fresh secrets from server").option(
   "--cache-ttl <seconds>",
-  "How long cached secrets stay fresh before a fingerprint check (default: 3600s / 1h; 0 = always fingerprint-check)",
+  "How long cached secrets are served without even a fingerprint check (default: 0 = verify freshness on every run; the check is one cheap metadata query, secrets are only re-decrypted when they changed)",
   String(DEFAULT_TTL)
 ).passThroughOptions().allowExcessArguments().action(async (commandArgs, options) => {
   try {
@@ -4757,7 +4906,12 @@ var runCommand = new Command14("run").description(
       }
       throw notInitialized();
     }
-    const environment = options.env || project.environment;
+    const environment = options.env !== void 0 ? options.env : project.environment;
+    if (options.env !== void 0 && !validateEnvironment(options.env)) {
+      throw invalidInput(
+        `Unknown environment "${options.env}". Valid environments: development, staging, production.`
+      );
+    }
     const organizationId = options.organization || project.organizationId;
     const parsedTtl = Number.parseInt(
       options.cacheTtl ?? String(DEFAULT_TTL),
@@ -4767,14 +4921,35 @@ var runCommand = new Command14("run").description(
     let variables;
     let cacheHit = false;
     let cacheAge = "";
+    let otherEnvKeys = [];
+    let decryptionFailures = [];
+    let scopeRestricted = false;
     if (options.cache === false) {
-      variables = await doFetch(
+      const fetched = await doFetch(
         project,
         environment,
         organizationId,
         options.quiet
       );
-      writeCache(project.projectId, environment, organizationId, variables);
+      variables = fetched.variables;
+      decryptionFailures = fetched.decryptionFailures;
+      scopeRestricted = fetched.scopeRestricted;
+      otherEnvKeys = await fetchOtherEnvKeys(
+        project.projectId,
+        environment,
+        organizationId
+      );
+      writeCache(
+        project.projectId,
+        environment,
+        organizationId,
+        variables,
+        void 0,
+        {
+          decryptionFailures,
+          scopeRestricted
+        }
+      );
     } else {
       const probe = probeCache(
         project.projectId,
@@ -4786,15 +4961,18 @@ var runCommand = new Command14("run").description(
         variables = probe.entry.variables;
         cacheHit = true;
         cacheAge = formatAge(probe.entry.fetchedAt);
-      } else if (probe.hit && !probe.fresh) {
+        decryptionFailures = probe.entry.decryptionFailures ?? [];
+        scopeRestricted = probe.entry.scopeRestricted ?? false;
+      } else {
         try {
           const api = createAPIClient();
-          const serverFingerprint = await api.checkFingerprint(
+          const check = await api.checkFingerprint(
             project.projectId,
             environment,
             organizationId
           );
-          if (serverFingerprint === probe.entry.fingerprint) {
+          otherEnvKeys = check.otherEnvKeys;
+          if (probe.hit && check.fingerprint === probe.entry.fingerprint) {
             extendCacheFreshness(
               project.projectId,
               environment,
@@ -4803,27 +4981,35 @@ var runCommand = new Command14("run").description(
             variables = probe.entry.variables;
             cacheHit = true;
             cacheAge = formatAge(probe.entry.fetchedAt);
+            decryptionFailures = probe.entry.decryptionFailures ?? [];
+            scopeRestricted = probe.entry.scopeRestricted ?? false;
           } else {
-            variables = await doFetch(
+            const fetched = await doFetch(
               project,
               environment,
               organizationId,
               options.quiet,
-              "Secrets updated, refreshing"
+              probe.hit ? "Secrets updated, refreshing" : "Loading"
             );
+            variables = fetched.variables;
+            decryptionFailures = fetched.decryptionFailures;
+            scopeRestricted = fetched.scopeRestricted;
             writeCache(
               project.projectId,
               environment,
               organizationId,
               variables,
-              serverFingerprint
+              decryptionFailures.length > 0 ? void 0 : check.fingerprint,
+              { decryptionFailures, scopeRestricted }
             );
           }
         } catch (err) {
-          if (isConnectivityError(err)) {
+          if (probe.hit && isConnectivityError(err)) {
             variables = probe.entry.variables;
             cacheHit = true;
             cacheAge = formatAge(probe.entry.fetchedAt);
+            decryptionFailures = probe.entry.decryptionFailures ?? [];
+            scopeRestricted = probe.entry.scopeRestricted ?? false;
             if (!options.quiet) {
               warning(
                 `Using offline cache (age ${cacheAge}) \u2014 could not reach the server to verify freshness.`
@@ -4834,14 +5020,6 @@ var runCommand = new Command14("run").description(
             throw err;
           }
         }
-      } else {
-        variables = await doFetch(
-          project,
-          environment,
-          organizationId,
-          options.quiet
-        );
-        writeCache(project.projectId, environment, organizationId, variables);
       }
     }
     if (variables.length === 0) {
@@ -4849,6 +5027,13 @@ var runCommand = new Command14("run").description(
         `No variables found for ${environment}. Running command without injected secrets.`
       );
     }
+    if (!options.quiet && decryptionFailures.length > 0) {
+      for (const key of decryptionFailures) {
+        warning(
+          `Could not decrypt ${chalk15.bold(key)} \u2014 skipped (vault error, check server logs)`
+        );
+      }
+    }
     const secrets = {};
     for (const v of variables) {
       secrets[v.key] = v.value;
@@ -4870,9 +5055,24 @@ var runCommand = new Command14("run").description(
     if (!options.quiet) {
       const injectedCount = Object.keys(secrets).length;
       const cacheTag = cacheHit ? chalk15.dim(` \u26A1 cache (${cacheAge})`) : "";
+      const total = injectedCount + decryptionFailures.length + otherEnvKeys.length;
+      const ofTotal = otherEnvKeys.length > 0 ? chalk15.dim(` of ${total}`) : "";
       info(
-        `Injected ${chalk15.bold(injectedCount)} ${injectedCount === 1 ? "variable" : "variables"} from ${chalk15.bold(`${project.projectName || project.projectId}/${environment}`)}${cacheTag}`
+        `Injected ${chalk15.bold(injectedCount)}${ofTotal} ${injectedCount === 1 ? "variable" : "variables"} from ${chalk15.bold(`${project.projectName || project.projectId}/${environment}`)}${cacheTag}`
       );
+      if (otherEnvKeys.length > 0) {
+        const names = otherEnvKeys.slice(0, 5).map((v) => v.key);
+        const more = otherEnvKeys.length > 5 ? `, +${otherEnvKeys.length - 5} more` : "";
+        warning(
+          `${otherEnvKeys.length} variable${otherEnvKeys.length === 1 ? "" : "s"} not in ${chalk15.bold(environment)}, not injected: ${names.join(", ")}${more}`
+        );
+        info(`Use -e <environment> to load a different environment.`);
+      }
+      if (scopeRestricted) {
+        warning(
+          `Your role restricts which variables you can see \u2014 some may be withheld for ${chalk15.bold(environment)}.`
+        );
+      }
       if (overridden.length > 0) {
         warning(
           `Overriding ${overridden.length} shell var${overridden.length === 1 ? "" : "s"}: ${overridden.slice(0, 3).join(", ")}${overridden.length > 3 ? `, +${overridden.length - 3} more` : ""}`
@@ -4889,18 +5089,28 @@ var runCommand = new Command14("run").description(
 async function doFetch(project, environment, organizationId, quiet, labelPrefix = "Loading") {
   const label = `${labelPrefix} ${chalk15.bold(environment)} secrets for ${chalk15.bold(project.projectName || project.projectId)}...`;
   const api = createAPIClient();
-  const { variables, decryptionFailures } = quiet ? await api.listVariables(project.projectId, environment, organizationId) : await withSpinner(
+  const { variables, meta, decryptionFailures } = quiet ? await api.listVariables(project.projectId, environment, organizationId) : await withSpinner(
     label,
     () => api.listVariables(project.projectId, environment, organizationId)
   );
-  if (decryptionFailures.length > 0) {
-    for (const key of decryptionFailures) {
-      warning(
-        `Could not decrypt ${chalk15.bold(key)} \u2014 skipped (vault error, check server logs)`
-      );
-    }
+  return {
+    variables,
+    decryptionFailures,
+    scopeRestricted: meta?.scopeRestricted ?? false
+  };
+}
+async function fetchOtherEnvKeys(projectId, environment, organizationId) {
+  try {
+    const api = createAPIClient();
+    const check = await api.checkFingerprint(
+      projectId,
+      environment,
+      organizationId
+    );
+    return check.otherEnvKeys;
+  } catch {
+    return [];
   }
-  return variables;
 }
 function printInjectionPreview(secrets, project, environment) {
   const keys = Object.keys(secrets).sort();
@@ -5156,9 +5366,17 @@ function buildCreateVariableRequestBody(input) {
     isSensitive: input.isSensitive ?? false
   };
 }
+function canSubmitRequests(input) {
+  if (input.capabilities) {
+    return input.capabilities["project.requests.submit"] === true;
+  }
+  return normalizeOrgRole(input.role) === "developer";
+}
 function isRequestEligibleProject(project) {
-  const role = normalizeOrgRole(project.unifiedRole ?? project.role);
-  return role === "developer" && project.assigned === true;
+  return canSubmitRequests({
+    capabilities: project.capabilities,
+    role: project.unifiedRole ?? project.role
+  }) && project.assigned === true;
 }
 function buildEligibleRequestTargets(projects, orgNameById) {
   return projects.filter(isRequestEligibleProject).map((p) => ({
@@ -5206,6 +5424,7 @@ function formatRequestsListHeader(input) {
 }
 function formatRequestRow(request) {
   return {
+    id: request._id,
     key: request.key,
     environments: request.environments.join(", "),
     status: request.status,
@@ -5257,8 +5476,11 @@ var requestCommand = new Command17("request").description(
       }
       if (useDefault) {
         const meta = await fetchProjectMeta(api, defaultEntry);
-        const role = normalizeOrgRole(meta?.unifiedRole ?? meta?.role);
-        if (role !== "developer") {
+        const eligible = canSubmitRequests({
+          capabilities: meta?.capabilities,
+          role: meta?.unifiedRole ?? meta?.role
+        });
+        if (!eligible) {
           warning(
             "You have direct write access to this project. Use `envpilot push` or create the variable directly instead of submitting a request."
           );
@@ -5372,10 +5594,6 @@ var requestCommand = new Command17("request").description(
     );
     info(`Status: ${created.status} \xB7 Id: ${created._id}`);
   } catch (err) {
-    if (err instanceof APIError && err.statusCode === 403) {
-      error(err.message);
-      return;
-    }
     await handleError(err);
   }
 });
@@ -5471,66 +5689,608 @@ async function pickRequestTarget(api) {
 
 // src/commands/requests.ts
 import { Command as Command18 } from "commander";
-var requestsCommand = new Command18("requests").description("List variable requests for a project").option(
+import inquirer7 from "inquirer";
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function runList(options) {
+  if (!isAuthenticated()) throw notAuthenticated();
+  const configV2 = readProjectConfigV2();
+  if (!configV2) throw notInitialized();
+  const project = resolveProject(configV2, options.project);
+  if (!project) {
+    error(`Project not found: ${options.project}`);
+    console.log();
+    console.log("Linked projects:");
+    for (const p of configV2.projects) {
+      console.log(`  ${p.projectName || p.projectId} (${p.environment})`);
+    }
+    process.exit(1);
+  }
+  let status;
+  if (options.status) {
+    const parsed = variableRequestStatusSchema.safeParse(options.status);
+    if (!parsed.success) {
+      error(
+        `Invalid status: ${options.status}. Must be one of pending, approved, rejected, canceled.`
+      );
+      process.exit(1);
+    }
+    status = parsed.data;
+  }
+  const api = createAPIClient();
+  const requests = await withSpinner(
+    "Fetching variable requests...",
+    () => api.listVariableRequests(project.projectId, status)
+  );
+  if (options.json) {
+    console.log(JSON.stringify(requests, null, 2));
+    return;
+  }
+  header(
+    formatRequestsListHeader({
+      projectName: project.projectName || project.projectId,
+      organizationName: project.organizationName || project.organizationId
+    })
+  );
+  if (requests.length === 0) {
+    info("No variable requests found.");
+    return;
+  }
+  table(formatRequestRows(requests), [
+    { key: "id", header: "ID" },
+    { key: "key", header: "KEY" },
+    { key: "environments", header: "ENVIRONMENTS" },
+    { key: "status", header: "STATUS" },
+    { key: "requested", header: "REQUESTED" },
+    { key: "reason", header: "REASON" }
+  ]);
+}
+var listSub = new Command18("list").description("List variable requests for a project").option(
   "--project <name-or-id>",
   "List requests for a specific linked project"
+).option("--status <status>", "Filter: pending, approved, rejected, canceled").option("--json", "Output as JSON").action(async (options) => {
+  try {
+    await runList(options);
+  } catch (err) {
+    await handleError(err);
+  }
+});
+var approveSub = new Command18("approve").description("Approve a pending request").argument("<id>", "Request id (from `envpilot requests`)").option(
+  "--value <value>",
+  "Secret value for a machine (valueless) request \u2014 CI only; interactively you are prompted MASKED instead so the value stays out of shell history"
 ).option(
-  "--status <status>",
-  "Filter by status: pending, approved, rejected, canceled"
-).action(async (options) => {
+  "--value-stdin",
+  'Read the secret value from stdin (CI-safe: keeps it out of argv), e.g. printf %s "$SECRET" | envpilot requests approve <id> --value-stdin'
+).option("--reason <text>", "Optional review note").action(
+  async (id, options) => {
+    try {
+      if (!isAuthenticated()) throw notAuthenticated();
+      const api = createAPIClient();
+      const request = await withSpinner(
+        "Loading request...",
+        () => api.getVariableRequest(id)
+      );
+      if (!request) {
+        error("Request not found (or you lack access to it).");
+        process.exit(1);
+      }
+      if (request.status !== "pending") {
+        error(
+          `Only pending requests can be approved (current: ${request.status}).`
+        );
+        process.exit(1);
+      }
+      let value = options.value;
+      if (value !== void 0 && process.stdin.isTTY) {
+        error(
+          "--value is for CI only \u2014 interactively you are prompted masked so the secret stays out of shell history. Re-run without --value."
+        );
+        process.exit(1);
+      }
+      if (options.valueStdin) {
+        value = (await readStdin()).replace(/\r?\n$/, "");
+        if (!value) {
+          error("--value-stdin was passed but stdin was empty.");
+          process.exit(1);
+        }
+      }
+      if (request.vaultRef === void 0 && value === void 0) {
+        if (!process.stdin.isTTY) {
+          error(
+            `Request ${request.key} carries no value \u2014 non-interactive approval needs --value.`
+          );
+          process.exit(1);
+        }
+        warning(
+          `${request.key} is a machine request with no value \u2014 you supply it now (encrypted server-side).`
+        );
+        const answer = await inquirer7.prompt([
+          {
+            type: "password",
+            name: "value",
+            message: `Value for ${request.key}:`,
+            mask: "*",
+            validate: (input) => input.length > 0 || "Value cannot be empty."
+          }
+        ]);
+        value = answer.value;
+      }
+      await withSpinner(
+        "Approving request...",
+        () => request.vaultRef === void 0 && value !== void 0 ? api.approveRequestWithValue(id, value, options.reason) : api.reviewRequest(id, "approve", options.reason)
+      );
+      success(`Request approved: ${request.key}.`);
+    } catch (err) {
+      await handleError(err);
+    }
+  }
+);
+var rejectSub = new Command18("reject").description("Reject a pending request").argument("<id>", "Request id (from `envpilot requests`)").option("--reason <text>", "Optional review note shown to the requester").action(async (id, options) => {
   try {
-    if (!isAuthenticated()) {
-      throw notAuthenticated();
+    if (!isAuthenticated()) throw notAuthenticated();
+    const api = createAPIClient();
+    await withSpinner(
+      "Rejecting request...",
+      () => api.reviewRequest(id, "reject", options.reason)
+    );
+    success("Request rejected.");
+  } catch (err) {
+    await handleError(err);
+  }
+});
+var cancelSub = new Command18("cancel").description("Cancel a pending request (your own, or as a reviewer)").argument("<id>", "Request id (from `envpilot requests`)").action(async (id) => {
+  try {
+    if (!isAuthenticated()) throw notAuthenticated();
+    const api = createAPIClient();
+    await withSpinner("Canceling request...", () => api.cancelRequest(id));
+    success("Request canceled.");
+  } catch (err) {
+    await handleError(err);
+  }
+});
+var requestsCommand = new Command18("requests").description("List and review variable requests").option(
+  "--project <name-or-id>",
+  "List requests for a specific linked project"
+).option("--status <status>", "Filter: pending, approved, rejected, canceled").option("--json", "Output as JSON").action(async (options) => {
+  try {
+    await runList(options);
+  } catch (err) {
+    await handleError(err);
+  }
+}).addCommand(listSub).addCommand(approveSub).addCommand(rejectSub).addCommand(cancelSub);
+
+// src/commands/secrets.ts
+import { Command as Command19 } from "commander";
+import inquirer8 from "inquirer";
+import chalk18 from "chalk";
+var KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+function parseAssignment(assignment) {
+  const eq = assignment.indexOf("=");
+  if (eq < 1) {
+    return {
+      ok: false,
+      error: "Expected KEY=VALUE (e.g. envpilot secrets set API_URL=https://api.example.com)"
+    };
+  }
+  const key = assignment.slice(0, eq);
+  const value = assignment.slice(eq + 1);
+  if (!KEY_PATTERN.test(key) || key.length > 100) {
+    return {
+      ok: false,
+      error: "Variable key must be UPPER_SNAKE_CASE (A-Z, 0-9, _), start with a letter, max 100 chars."
+    };
+  }
+  return { ok: true, key, value };
+}
+function resolveTarget(options) {
+  if (!isAuthenticated()) throw notAuthenticated();
+  const config2 = readProjectConfigV2();
+  if (!config2) throw notInitialized();
+  const project = resolveProject(config2, options.project);
+  if (!project) {
+    error(`Project not found: ${options.project ?? "(active)"}`);
+    console.log();
+    console.log("Linked projects:");
+    for (const p of config2.projects) {
+      console.log(`  ${p.projectName || p.projectId} (${p.environment})`);
     }
-    const configV2 = readProjectConfigV2();
-    if (!configV2) throw notInitialized();
-    const project = resolveProject(configV2, options.project);
-    if (!project) {
-      error(`Project not found: ${options.project}`);
-      console.log();
-      console.log("Linked projects:");
-      for (const p of configV2.projects) {
-        console.log(`  ${p.projectName || p.projectId} (${p.environment})`);
+    process.exit(1);
+  }
+  const environment = options.env !== void 0 ? options.env : project.environment;
+  if (!validateEnvironment(environment)) {
+    throw invalidInput(
+      `Unknown environment "${environment}". Valid environments: development, staging, production.`
+    );
+  }
+  return {
+    projectId: project.projectId,
+    projectName: project.projectName || project.projectId,
+    environment
+  };
+}
+async function resolveWriteRoute(projectId) {
+  const api = createAPIClient();
+  const roles = await api.resolveProjectRoles(projectId);
+  const assigned = roles.assigned;
+  return {
+    role: roles.role,
+    canWrite: assigned && (roles.capabilities["project.variables.create"] === true || roles.capabilities["project.variables.update"] === true),
+    canRequest: assigned && roles.capabilities["project.requests.submit"] === true,
+    environmentScope: roles.environmentScope
+  };
+}
+var setCommand = new Command19("set").description(
+  "Set (create or update) a single secret. Two-step by default: the key is validated first, then the value is prompted MASKED so it never lands in shell history. KEY=VALUE inline works for CI."
+).argument(
+  "[key-or-assignment]",
+  "KEY (value prompted masked) or KEY=VALUE (CI; lands in shell history)"
+).option("-e, --env <environment>", "Environment (defaults to active)").option("-p, --project <name-or-id>", "Linked project (defaults to active)").option("-d, --description <text>", "Optional description").option("--sensitive", "Mark the secret as sensitive").option(
+  "--all-envs",
+  "Confirm updating a variable whose value is shared across multiple environments"
+).action(
+  async (keyOrAssignment, options) => {
+    try {
+      const { projectId, projectName, environment } = resolveTarget(options);
+      const route = await withSpinner(
+        "Checking role and plan...",
+        () => resolveWriteRoute(projectId)
+      );
+      if (!route.canWrite && !route.canRequest) {
+        error(
+          `Your role (${route.role}) cannot write variables or file requests in this project.`
+        );
+        process.exit(3);
       }
-      process.exit(1);
-    }
-    let status;
-    if (options.status) {
-      const parsed = variableRequestStatusSchema.safeParse(options.status);
-      if (!parsed.success) {
+      if (route.environmentScope && !route.environmentScope.includes(environment)) {
         error(
-          `Invalid status: ${options.status}. Must be one of pending, approved, rejected, canceled.`
+          `Your assignment is scoped to [${route.environmentScope.join(", ")}] \u2014 ${environment} is outside it.`
+        );
+        process.exit(3);
+      }
+      let key;
+      let inlineValue;
+      if (keyOrAssignment && keyOrAssignment.includes("=")) {
+        const parsed = parseAssignment(keyOrAssignment);
+        if (!parsed.ok) throw invalidInput(parsed.error);
+        key = parsed.key;
+        inlineValue = parsed.value;
+        warning(
+          "Value passed on the command line \u2014 it is now in your shell history. Prefer `envpilot secrets set KEY` to be prompted masked."
+        );
+      } else if (keyOrAssignment) {
+        if (!KEY_PATTERN.test(keyOrAssignment) || keyOrAssignment.length > 100) {
+          throw invalidInput(
+            "Variable key must be UPPER_SNAKE_CASE (A-Z, 0-9, _), start with a letter, max 100 chars."
+          );
+        }
+        key = keyOrAssignment;
+      } else {
+        if (!process.stdin.isTTY) {
+          throw invalidInput(
+            "No key provided. Non-interactive usage: envpilot secrets set KEY=VALUE"
+          );
+        }
+        const answer = await inquirer8.prompt([
+          {
+            type: "input",
+            name: "key",
+            message: "Key:",
+            validate: (input) => KEY_PATTERN.test(input) && input.length <= 100 || "Must be UPPER_SNAKE_CASE (A-Z, 0-9, _), start with a letter, max 100 chars."
+          }
+        ]);
+        key = answer.key;
+      }
+      const existing = await withSpinner(
+        `Checking ${key}...`,
+        () => createAPIClient().findVariable(projectId, environment, key)
+      );
+      if (existing && existing.environments.length > 1 && !options.allEnvs) {
+        const envList = existing.environments.join(", ");
+        if (process.stdin.isTTY) {
+          const { proceed } = await inquirer8.prompt([
+            {
+              type: "confirm",
+              name: "proceed",
+              message: `${key}'s value is shared across [${envList}] \u2014 updating it changes ALL of them. Continue?`,
+              default: false
+            }
+          ]);
+          if (!proceed) {
+            info(
+              "Nothing changed. To give this environment its own value, edit the variable's environments in the dashboard first."
+            );
+            return;
+          }
+        } else {
+          error(
+            `${key} is shared across [${envList}] \u2014 updating it changes all of them. Re-run with --all-envs to confirm.`
+          );
+          process.exit(1);
+        }
+      }
+      let value;
+      let isSensitive = options.sensitive ?? false;
+      if (inlineValue !== void 0) {
+        value = inlineValue;
+      } else {
+        if (!process.stdin.isTTY) {
+          throw invalidInput(
+            "No value provided. Non-interactive usage: envpilot secrets set KEY=VALUE"
+          );
+        }
+        const answers = await inquirer8.prompt([
+          {
+            type: "password",
+            name: "value",
+            message: "Value:",
+            mask: "*",
+            validate: (input) => input.length > 0 || "Value cannot be empty."
+          },
+          ...options.sensitive === void 0 ? [
+            {
+              type: "confirm",
+              name: "isSensitive",
+              message: "Mark as sensitive?",
+              default: false
+            }
+          ] : []
+        ]);
+        value = answers.value;
+        if (options.sensitive === void 0) {
+          isSensitive = answers.isSensitive ?? false;
+        }
+      }
+      const api = createAPIClient();
+      if (route.canWrite) {
+        const result = await withSpinner(
+          `Setting ${key} in ${environment}...`,
+          () => api.setVariable(projectId, environment, key, value, {
+            description: options.description,
+            isSensitive
+          })
+        );
+        if (result.unchanged) {
+          success(
+            `${chalk18.bold(key)} already has this value in ${projectName}/${environment} \u2014 nothing to change.`
+          );
+        } else {
+          const verb = result.created > 0 ? "Created" : "Updated";
+          success(
+            `${verb} ${chalk18.bold(key)} in ${projectName}/${environment}.`
+          );
+        }
+        return;
+      }
+      if (process.stdin.isTTY && inlineValue === void 0) {
+        const { proceed } = await inquirer8.prompt([
+          {
+            type: "confirm",
+            name: "proceed",
+            message: "Your role can't write variables directly \u2014 file this as a request for review?",
+            default: true
+          }
+        ]);
+        if (!proceed) {
+          info("Nothing submitted.");
+          return;
+        }
+      } else {
+        warning(
+          "Your role can't write variables directly \u2014 filing this as a request for review."
         );
-        process.exit(1);
       }
-      status = parsed.data;
+      const request = await withSpinner(
+        "Submitting request...",
+        () => api.createVariableRequest({
+          projectId,
+          key,
+          value,
+          environments: [environment],
+          isSensitive,
+          description: options.description
+        })
+      );
+      success(`Request submitted for ${chalk18.bold(key)} (${environment}).`);
+      info(
+        `A reviewer can approve it with: envpilot requests approve ${request._id}`
+      );
+    } catch (err) {
+      await handleError(err);
     }
+  }
+);
+var rmCommand = new Command19("rm").alias("delete").description("Delete a single secret from one environment (moves to trash)").argument("<key>", "Variable key to delete").option("-e, --env <environment>", "Environment (defaults to active)").option("-p, --project <name-or-id>", "Linked project (defaults to active)").option("-y, --yes", "Skip the confirmation prompt").action(async (key, options) => {
+  try {
+    const { projectId, projectName, environment } = resolveTarget(options);
     const api = createAPIClient();
-    const requests = await withSpinner(
-      "Fetching variable requests...",
-      () => api.listVariableRequests(project.projectId, status)
+    const roles = await withSpinner(
+      "Checking role...",
+      () => api.resolveProjectRoles(projectId)
     );
-    header(
-      formatRequestsListHeader({
-        projectName: project.projectName || project.projectId,
-        organizationName: project.organizationName || project.organizationId
-      })
+    if (!roles.assigned || roles.capabilities["project.variables.delete"] !== true) {
+      error(
+        `Your role (${roles.role}) cannot delete variables in this project.`
+      );
+      process.exit(3);
+    }
+    const found = await withSpinner(
+      `Finding ${key}...`,
+      () => api.findVariable(projectId, environment, key)
     );
-    if (requests.length === 0) {
-      info("No variable requests found.");
+    if (!found) {
+      error(
+        `No variable ${key} found in ${projectName}/${environment} (or you lack access).`
+      );
+      process.exit(1);
+    }
+    const shared = found.environments.length > 1;
+    const consequence = shared ? `remove ${key} from ${environment} (still live in: ${found.environments.filter((e) => e !== environment).join(", ")})` : `move ${key} (${environment}) to trash`;
+    if (!options.yes) {
+      if (!process.stdin.isTTY) {
+        warning(`This will ${consequence}. Re-run with --yes to confirm.`);
+        return;
+      }
+      const { proceed } = await inquirer8.prompt([
+        {
+          type: "confirm",
+          name: "proceed",
+          message: `${consequence[0].toUpperCase()}${consequence.slice(1)} \u2014 continue?`,
+          default: false
+        }
+      ]);
+      if (!proceed) {
+        info("Nothing deleted.");
+        return;
+      }
+    }
+    if (shared) {
+      await withSpinner(
+        `Removing ${key} from ${environment}...`,
+        () => api.removeVariableFromEnvironment(found._id, environment)
+      );
+      success(
+        `Removed ${chalk18.bold(key)} from ${environment} \u2014 still live in: ${found.environments.filter((e) => e !== environment).join(", ")}.`
+      );
+    } else {
+      await withSpinner(
+        `Deleting ${key}...`,
+        () => api.removeVariable(found._id)
+      );
+      success(
+        `Deleted ${chalk18.bold(key)} from ${projectName}/${environment}.`
+      );
+      info("Recover it from the dashboard trash if this was a mistake.");
+    }
+  } catch (err) {
+    await handleError(err);
+  }
+});
+var secretsCommand = new Command19("secrets").alias("var").description("Manage a single secret (set, delete)").addCommand(setCommand).addCommand(rmCommand);
+
+// src/commands/diff.ts
+import { Command as Command20 } from "commander";
+import chalk19 from "chalk";
+var diffCommand = new Command20("diff").description("Compare variables between two environments").argument("<envA>", "First environment").argument("<envB>", "Second environment").option("-p, --project <name-or-id>", "Linked project (defaults to active)").option("--values", "Also compare values (decrypts both environments)").option("--json", "Output as JSON").action(async (envA, envB, options) => {
+  try {
+    if (!isAuthenticated()) throw notAuthenticated();
+    for (const env of [envA, envB]) {
+      if (!validateEnvironment(env)) {
+        throw invalidInput(
+          `Unknown environment "${env}". Valid: development, staging, production.`
+        );
+      }
+    }
+    if (envA === envB) {
+      throw invalidInput("Pick two different environments to compare.");
+    }
+    const config2 = readProjectConfigV2();
+    if (!config2) throw notInitialized();
+    const project = resolveProject(config2, options.project);
+    if (!project) {
+      error(`Project not found: ${options.project ?? "(active)"}`);
+      process.exit(1);
+    }
+    const api = createAPIClient();
+    const [metaA, metaB] = await withSpinner(
+      `Comparing ${envA} vs ${envB}...`,
+      () => Promise.all([
+        api.listVariableKeys(project.projectId, envA),
+        api.listVariableKeys(project.projectId, envB)
+      ])
+    );
+    const keysA = new Set(metaA.keys);
+    const keysB = new Set(metaB.keys);
+    const truncated = metaA.truncated || metaB.truncated;
+    let valsA = /* @__PURE__ */ new Map();
+    let valsB = /* @__PURE__ */ new Map();
+    let undecryptable = [];
+    if (options.values) {
+      const [a, b] = await withSpinner(
+        `Decrypting values...`,
+        () => Promise.all([
+          api.listVariables(project.projectId, envA, project.organizationId),
+          api.listVariables(project.projectId, envB, project.organizationId)
+        ])
+      );
+      valsA = new Map(a.variables.map((v) => [v.key, v.value]));
+      valsB = new Map(b.variables.map((v) => [v.key, v.value]));
+      undecryptable = [
+        .../* @__PURE__ */ new Set([...a.decryptionFailures, ...b.decryptionFailures])
+      ].sort();
+    }
+    const allKeys = [.../* @__PURE__ */ new Set([...keysA, ...keysB])].sort();
+    const unknown = new Set(undecryptable);
+    const onlyA = [];
+    const onlyB = [];
+    const differing = [];
+    const same = [];
+    for (const key of allKeys) {
+      const inA = keysA.has(key);
+      const inB = keysB.has(key);
+      if (inA && !inB) onlyA.push(key);
+      else if (!inA && inB) onlyB.push(key);
+      else if (unknown.has(key))
+        continue;
+      else if (options.values && valsA.has(key) && valsB.has(key) && valsA.get(key) !== valsB.get(key))
+        differing.push(key);
+      else same.push(key);
+    }
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            envA,
+            envB,
+            onlyA,
+            onlyB,
+            differing,
+            same,
+            undecryptable,
+            truncated
+          },
+          null,
+          2
+        )
+      );
       return;
     }
-    table(formatRequestRows(requests), [
-      { key: "key", header: "KEY" },
-      { key: "environments", header: "ENVIRONMENTS" },
-      { key: "status", header: "STATUS" },
-      { key: "requested", header: "REQUESTED" },
-      { key: "reason", header: "REASON" }
-    ]);
+    if (truncated) {
+      warning(
+        "Project exceeds the 5000-variable read window \u2014 this diff may be incomplete."
+      );
+    }
+    header(`Diff: ${chalk19.bold(envA)} vs ${chalk19.bold(envB)}`);
+    console.log();
+    printGroup(`Only in ${envA}`, onlyA, chalk19.yellow);
+    printGroup(`Only in ${envB}`, onlyB, chalk19.cyan);
+    if (options.values) {
+      printGroup("Different values", differing, chalk19.red);
+      printGroup(
+        "Could not decrypt (comparison unknown)",
+        undecryptable,
+        chalk19.magenta
+      );
+    }
+    if (onlyA.length === 0 && onlyB.length === 0 && differing.length === 0 && undecryptable.length === 0) {
+      info(
+        options.values ? "Environments are identical (keys and values)." : "Same keys in both environments (run with --values to compare values)."
+      );
+    }
   } catch (err) {
     await handleError(err);
   }
 });
+function printGroup(title, keys, color) {
+  if (keys.length === 0) return;
+  console.log(color(`${title} (${keys.length}):`));
+  for (const key of keys) console.log(`  ${key}`);
+  console.log();
+}
 
 // src/lib/command-catalog.ts
 function formatArgv(argv) {
@@ -5695,21 +6455,76 @@ var COMMAND_CATALOG = [
   },
   {
     id: "requests",
-    title: "List variable requests",
+    title: "List and review variable requests",
     category: "Browse",
-    description: "List pending and past variable requests for a project.",
+    description: "List variable requests, or approve/reject/cancel them without leaving the terminal.",
     argv: ["requests"],
-    args: "[--project <name-or-id>] [--status <status>]",
-    examples: [["requests"], ["requests", "--status", "pending"]],
-    websiteSurface: "Maps to `/api/cli/variable-requests` (GET).",
+    args: "[list] [--project <p>] [--status <s>] [--json] | approve <id> [--value <v>|--value-stdin] [--reason <t>] | reject <id> [--reason <t>] | cancel <id>",
+    examples: [
+      ["requests"],
+      ["requests", "--status", "pending"],
+      ["requests", "approve", "<id>"],
+      ["requests", "approve", "<id>", "--value", "sk_live_\u2026"],
+      ["requests", "reject", "<id>", "--reason", "use the shared key"],
+      ["requests", "cancel", "<id>"]
+    ],
+    websiteSurface: "Convex features/variables/requests (review/cancel).",
     notes: [
-      "Reviewers (owner, assigned project manager/team lead) see every request for the project.",
-      "Developers see only their own requests."
+      "Reviewers (owner, assigned project manager/team lead) see every request; developers see only their own.",
+      "--status/--json apply to listing only; --value/--value-stdin/--reason apply to review subcommands only.",
+      "Approving a machine (valueless) request prompts MASKED for the value; --value-stdin reads it from stdin for CI (keeps it out of argv), --value is a last resort that lands in shell history.",
+      "Get the <id> from the ID column of `envpilot requests`."
     ],
-    keywords: ["requests", "approval", "review", "pending"],
+    keywords: ["requests", "approval", "review", "approve", "reject", "cancel"],
     topLevel: true,
     createCommand: () => requestsCommand
   },
+  {
+    id: "secrets",
+    title: "Set or delete a single secret",
+    category: "Sync",
+    description: "Change one secret without pull/edit/push. Two-step by default: key first, value prompted MASKED (never in shell history).",
+    argv: ["secrets"],
+    aliases: [["var"]],
+    args: "set [<key>|<key=value>] [-e <env>] [-p <project>] [-d <text>] [--sensitive] [--all-envs] | rm <key> [-e <env>] [-p <project>] [--yes]",
+    examples: [
+      ["secrets", "set"],
+      ["secrets", "set", "STRIPE_SECRET_KEY", "--env", "production"],
+      ["secrets", "set", "API_URL=https://api.example.com"],
+      ["secrets", "rm", "OLD_FLAG", "--env", "staging", "--yes"]
+    ],
+    websiteSurface: "Convex features/variables (bulk upsert / remove).",
+    notes: [
+      "Interactive by default: the key is validated first, then the value is prompted masked so it never lands in shell history \u2014 KEY=VALUE inline is for CI and prints a history warning.",
+      "Role-aware: direct-write roles set immediately; request-only roles are offered the request workflow instead (a reviewer approves with `requests approve`).",
+      "Plan limits are enforced server-side and reported readably; check `envpilot usage` for your tier.",
+      "set upserts one key in one environment (merge); updating a value shared across environments requires confirmation (--all-envs non-interactively).",
+      "rm on a single-environment secret moves it to trash (recoverable from the dashboard); on a shared secret it only removes THIS environment \u2014 the value stays live in the others.",
+      "`envpilot var \u2026` still works as an alias."
+    ],
+    keywords: ["secrets", "var", "set", "delete", "remove", "variable", "edit"],
+    topLevel: true,
+    createCommand: () => secretsCommand
+  },
+  {
+    id: "diff",
+    title: "Compare two environments",
+    category: "Browse",
+    description: "Show which variable keys differ between two environments (add --values to compare values).",
+    argv: ["diff"],
+    args: "<envA> <envB> [--values] [--project <name-or-id>] [--json]",
+    examples: [
+      ["diff", "staging", "production"],
+      ["diff", "development", "staging", "--values"]
+    ],
+    websiteSurface: "Convex features/variables (client-side compare).",
+    notes: [
+      "Default is a metadata-only key comparison; --values decrypts both environments."
+    ],
+    keywords: ["diff", "compare", "environments", "drift"],
+    topLevel: true,
+    createCommand: () => diffCommand
+  },
   {
     id: "run",
     title: "Run command with secrets",