@openape/apes 0.5.4 → 0.6.0

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {
+  CliError,
+  CliExit,
   parseDuration
-} from "./chunk-AGHP6MNV.js";
+} from "./chunk-ZSJU7IXE.js";
 import {
   loadEd25519PrivateKey
 } from "./chunk-KVBHBOED.js";
@@ -22,8 +24,8 @@ import {
 } from "./chunk-KXESKY4X.js";
 
 // src/cli.ts
-import consola22 from "consola";
-import { defineCommand as defineCommand25, runMain } from "citty";
+import consola21 from "consola";
+import { defineCommand as defineCommand26, runMain } from "citty";
 
 // src/commands/auth/login.ts
 import { Buffer } from "buffer";
@@ -57,8 +59,7 @@ var loginCommand = defineCommand({
     const config = loadConfig();
     const idp = args.idp || process.env.APES_IDP || process.env.GRAPES_IDP || config.defaults?.idp;
     if (!idp) {
-      consola.error("IdP URL required. Use --idp <url> or set APES_IDP.");
-      return process.exit(1);
+      throw new CliError("IdP URL required. Use --idp <url> or set APES_IDP.");
     }
     if (args.key) {
       await loginWithKey(idp, args.key, args.email);
@@ -137,14 +138,12 @@ async function loginWithPKCE(idp) {
   });
   if (!tokenResponse.ok) {
     const text = await tokenResponse.text();
-    consola.error(`Token exchange failed: ${text}`);
-    return process.exit(1);
+    throw new CliError(`Token exchange failed: ${text}`);
   }
   const tokens = await tokenResponse.json();
   const accessToken = tokens.access_token || tokens.id_token || tokens.assertion;
   if (!accessToken) {
-    consola.error("No access token received");
-    return process.exit(1);
+    throw new CliError("No access token received");
   }
   const payload = JSON.parse(atob(accessToken.split(".")[1]));
   saveAuth({
@@ -162,8 +161,7 @@ async function loginWithKey(idp, keyPath, email) {
   const { loadEd25519PrivateKey: loadEd25519PrivateKey2 } = await import("./ssh-key-Q7KG4K25.js");
   const agentEmail = email;
   if (!agentEmail) {
-    consola.error("Agent email required for key-based login. Use --email <agent-email>");
-    return process.exit(1);
+    throw new CliError("Agent email required for key-based login. Use --email <agent-email>");
   }
   const challengeUrl = await getAgentChallengeEndpoint(idp);
   const challengeResp = await fetch(challengeUrl, {
@@ -172,8 +170,7 @@ async function loginWithKey(idp, keyPath, email) {
     body: JSON.stringify({ agent_id: agentEmail })
   });
   if (!challengeResp.ok) {
-    consola.error(`Challenge failed: ${await challengeResp.text()}`);
-    return process.exit(1);
+    throw new CliError(`Challenge failed: ${await challengeResp.text()}`);
   }
   const { challenge } = await challengeResp.json();
   const keyContent = readFileSync2(keyPath, "utf-8");
@@ -190,8 +187,7 @@ async function loginWithKey(idp, keyPath, email) {
     })
   });
   if (!authResp.ok) {
-    consola.error(`Authentication failed: ${await authResp.text()}`);
-    return process.exit(1);
+    throw new CliError(`Authentication failed: ${await authResp.text()}`);
   }
   const { token, expires_in } = await authResp.json();
   saveAuth({
@@ -228,8 +224,7 @@ var whoamiCommand = defineCommand3({
   run() {
     const auth = loadAuth();
     if (!auth) {
-      consola3.error("Not logged in. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("Not logged in. Run `apes login` first.");
     }
     const isAgent = auth.email.includes("agent+");
     const expiresAt = new Date(auth.expires_at * 1e3).toISOString();
@@ -275,8 +270,7 @@ var listCommand = defineCommand4({
   async run({ args }) {
     const idp = getIdpUrl();
     if (!idp) {
-      consola4.error("No IdP URL configured. Run `apes login` first or pass --idp.");
-      return process.exit(1);
+      throw new CliError("No IdP URL configured. Run `apes login` first or pass --idp.");
     }
     const auth = loadAuth();
     const grantsUrl = await getGrantsEndpoint(idp);
@@ -335,13 +329,11 @@ var inboxCommand = defineCommand5({
   async run({ args }) {
     const idp = getIdpUrl();
     if (!idp) {
-      consola5.error("No IdP URL configured. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("No IdP URL configured. Run `apes login` first.");
     }
     const auth = loadAuth();
     if (!auth) {
-      consola5.error("Not logged in. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("Not logged in. Run `apes login` first.");
     }
     const grantsUrl = await getGrantsEndpoint(idp);
     const params = new URLSearchParams();
@@ -477,8 +469,7 @@ var requestCommand = defineCommand7({
   async run({ args }) {
     const auth = loadAuth();
     if (!auth) {
-      consola6.error("Not logged in. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("Not logged in. Run `apes login` first.");
     }
     const idp = getIdpUrl();
     const grantsUrl = await getGrantsEndpoint(idp);
@@ -516,17 +507,14 @@ async function waitForApproval(grantsUrl, grantId) {
       return;
     }
     if (grant.status === "denied") {
-      consola6.error("Grant denied.");
-      return process.exit(1);
+      throw new CliError("Grant denied.");
     }
     if (grant.status === "revoked") {
-      consola6.error("Grant revoked.");
-      return process.exit(1);
+      throw new CliError("Grant revoked.");
     }
     await new Promise((r) => setTimeout(r, interval));
   }
-  consola6.error("Timed out waiting for approval.");
-  return process.exit(1);
+  throw new CliError("Timed out waiting for approval.");
 }
 
 // src/commands/grants/request-capability.ts
@@ -644,17 +632,14 @@ async function waitForApproval2(grantsUrl, grantId) {
       return;
     }
     if (grant.status === "denied") {
-      consola7.error("Grant denied.");
-      process.exit(1);
+      throw new CliError("Grant denied.");
     }
     if (grant.status === "revoked") {
-      consola7.error("Grant revoked.");
-      process.exit(1);
+      throw new CliError("Grant revoked.");
     }
     await new Promise((resolve2) => setTimeout(resolve2, interval));
   }
-  consola7.error("Timed out waiting for approval.");
-  process.exit(1);
+  throw new CliError("Timed out waiting for approval.");
 }
 var requestCapabilityCommand = defineCommand8({
   meta: {
@@ -713,14 +698,12 @@ var requestCapabilityCommand = defineCommand8({
   async run({ rawArgs }) {
     const auth = loadAuth();
     if (!auth) {
-      consola7.error("Not logged in. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("Not logged in. Run `apes login` first.");
     }
     const parsed = parseCapabilityArgs(rawArgs);
     const idp = getIdpUrl(parsed.idp);
     if (!idp) {
-      consola7.error("No IdP URL configured. Use --idp or log in first.");
-      return process.exit(1);
+      throw new CliError("No IdP URL configured. Use --idp or log in first.");
     }
     const loaded = loadAdapter(parsed.cliId, parsed.adapter);
     const resolved = resolveCapabilityRequest(loaded, {
@@ -822,23 +805,40 @@ var revokeCommand = defineCommand11({
       type: "boolean",
       description: "Revoke all own pending grants",
       default: false
+    },
+    debug: {
+      type: "boolean",
+      description: "Print debug information (does not include full tokens)",
+      default: false
     }
   },
   async run({ args }) {
+    const auth = loadAuth();
+    const token = getAuthToken();
     const idp = getIdpUrl();
     const grantsUrl = await getGrantsEndpoint(idp);
+    if (args.debug) {
+      consola10.debug(`idp: ${idp}`);
+      consola10.debug(`grantsUrl: ${grantsUrl}`);
+      consola10.debug(`auth.email: ${auth?.email}`);
+      consola10.debug(`auth.expires_at: ${auth?.expires_at} (now: ${Math.floor(Date.now() / 1e3)})`);
+      consola10.debug(`getAuthToken(): ${token ? `${token.substring(0, 20)}...` : "NULL"}`);
+    }
+    if (!auth || !token) {
+      throw new CliError("Authentication required. Run `apes login` and try again.");
+    }
     const explicitIds = args.id ? [String(args.id), ...args._].filter(Boolean) : [];
     if (args.allPending && explicitIds.length > 0) {
-      consola10.error("Use either --all-pending or grant IDs, not both.");
-      return process.exit(1);
+      throw new CliError("Use either --all-pending or grant IDs, not both.");
     }
     let ids;
     if (args.allPending) {
-      const auth = loadAuth();
+      const auth2 = loadAuth();
       const response = await apiFetch(
-        `${grantsUrl}?status=pending&limit=100`
+        `${grantsUrl}?status=pending&limit=100`,
+        { token }
       );
-      const ownPending = auth?.email ? response.data.filter((g) => g.requester === auth.email) : response.data;
+      const ownPending = auth2?.email ? response.data.filter((g) => g.request?.requester === auth2.email) : response.data;
       if (ownPending.length === 0) {
         consola10.info("No pending grants to revoke.");
         return;
@@ -848,18 +848,17 @@ var revokeCommand = defineCommand11({
     } else if (explicitIds.length > 0) {
       ids = explicitIds;
     } else {
-      consola10.error("Provide grant ID(s) or use --all-pending.");
-      return process.exit(1);
+      throw new CliError("Provide grant ID(s) or use --all-pending.");
     }
     if (ids.length === 1) {
-      await apiFetch(`${grantsUrl}/${ids[0]}/revoke`, { method: "POST" });
+      await apiFetch(`${grantsUrl}/${ids[0]}/revoke`, { method: "POST", token });
       consola10.success(`Grant ${ids[0]} revoked.`);
       return;
     }
     const operations = ids.map((id) => ({ id, action: "revoke" }));
     const { results } = await apiFetch(
       `${grantsUrl}/batch`,
-      { method: "POST", body: { operations } }
+      { method: "POST", body: { operations }, token }
     );
     let succeeded = 0;
     for (const r of results) {
@@ -871,8 +870,7 @@ var revokeCommand = defineCommand11({
       }
     }
     if (succeeded < results.length) {
-      consola10.info(`Revoked ${succeeded} of ${results.length} grants.`);
-      process.exit(1);
+      throw new CliError(`Revoked ${succeeded} of ${results.length} grants.`);
     } else {
       consola10.success(`All ${succeeded} grants revoked.`);
     }
@@ -881,7 +879,6 @@ var revokeCommand = defineCommand11({
 
 // src/commands/grants/token.ts
 import { defineCommand as defineCommand12 } from "citty";
-import consola11 from "consola";
 var tokenCommand = defineCommand12({
   meta: {
     name: "token",
@@ -901,8 +898,7 @@ var tokenCommand = defineCommand12({
       method: "POST"
     });
     if (!result.authz_jwt) {
-      consola11.error("No token received. Grant may not be approved.");
-      return process.exit(1);
+      throw new CliError("No token received. Grant may not be approved.");
     }
     process.stdout.write(result.authz_jwt);
   }
@@ -910,7 +906,7 @@ var tokenCommand = defineCommand12({
 
 // src/commands/grants/delegate.ts
 import { defineCommand as defineCommand13 } from "citty";
-import consola12 from "consola";
+import consola11 from "consola";
 var delegateCommand = defineCommand13({
   meta: {
     name: "delegate",
@@ -944,8 +940,7 @@ var delegateCommand = defineCommand13({
   async run({ args }) {
     const auth = loadAuth();
     if (!auth) {
-      consola12.error("Not logged in. Run `apes login` first.");
-      return process.exit(1);
+      throw new CliError("Not logged in. Run `apes login` first.");
     }
     const idp = getIdpUrl();
     const delegationsUrl = await getDelegationsEndpoint(idp);
@@ -964,7 +959,7 @@ var delegateCommand = defineCommand13({
       method: "POST",
       body
     });
-    consola12.success(`Delegation created: ${result.id}`);
+    consola11.success(`Delegation created: ${result.id}`);
     console.log(`  Delegate: ${args.to}`);
     console.log(`  Audience: ${args.at}`);
     if (args.scopes)
@@ -977,7 +972,7 @@ var delegateCommand = defineCommand13({
 
 // src/commands/grants/delegations.ts
 import { defineCommand as defineCommand14 } from "citty";
-import consola13 from "consola";
+import consola12 from "consola";
 var delegationsCommand = defineCommand14({
   meta: {
     name: "delegations",
@@ -999,7 +994,7 @@ var delegationsCommand = defineCommand14({
       return;
     }
     if (delegations.length === 0) {
-      consola13.info("No delegations found.");
+      consola12.info("No delegations found.");
       return;
     }
     for (const d of delegations) {
@@ -1012,7 +1007,7 @@ var delegationsCommand = defineCommand14({
 
 // src/commands/adapter/index.ts
 import { defineCommand as defineCommand15 } from "citty";
-import consola14 from "consola";
+import consola13 from "consola";
 import {
   fetchRegistry,
   findAdapter,
@@ -1061,7 +1056,7 @@ var adapterCommand = defineCommand15({
 `);
             return;
           }
-          consola14.info(`Registry: ${index2.adapters.length} adapters (${index2.generated_at})`);
+          consola13.info(`Registry: ${index2.adapters.length} adapters (${index2.generated_at})`);
           for (const a of index2.adapters) {
             const installed = isInstalled(a.id, false) ? " [installed]" : "";
             console.log(`  ${a.id.padEnd(12)} ${a.name.padEnd(24)} ${a.category}${installed}`);
@@ -1083,7 +1078,7 @@ var adapterCommand = defineCommand15({
           return;
         }
         if (local.length === 0) {
-          consola14.info("No adapters installed. Use `apes adapter list --remote` to see available adapters.");
+          consola13.info("No adapters installed. Use `apes adapter list --remote` to see available adapters.");
           return;
         }
         for (const a of local) {
@@ -1120,20 +1115,20 @@ var adapterCommand = defineCommand15({
         for (const id of ids) {
           const entry = findAdapter(index, id);
           if (!entry) {
-            consola14.error(`Adapter "${id}" not found in registry. Use \`apes adapter search ${id}\` to search.`);
+            consola13.error(`Adapter "${id}" not found in registry. Use \`apes adapter search ${id}\` to search.`);
             continue;
           }
           const conflicts = findConflictingAdapters(entry.executable, id);
           if (conflicts.length > 0) {
             for (const c of conflicts) {
-              consola14.warn(`Conflicting adapter found: ${c.path} (id: ${c.adapterId}, executable: ${c.executable})`);
-              consola14.warn(`  Remove it with: apes adapter remove ${c.adapterId}`);
+              consola13.warn(`Conflicting adapter found: ${c.path} (id: ${c.adapterId}, executable: ${c.executable})`);
+              consola13.warn(`  Remove it with: apes adapter remove ${c.adapterId}`);
             }
           }
           const result = await installAdapter(entry, { local });
           const verb = result.updated ? "Updated" : "Installed";
-          consola14.success(`${verb} ${result.id} \u2192 ${result.path}`);
-          consola14.info(`Digest: ${result.digest}`);
+          consola13.success(`${verb} ${result.id} \u2192 ${result.path}`);
+          consola13.info(`Digest: ${result.digest}`);
         }
       }
     }),
@@ -1160,14 +1155,14 @@ var adapterCommand = defineCommand15({
         let failed = false;
         for (const id of ids) {
           if (removeAdapter(id, local)) {
-            consola14.success(`Removed adapter: ${id}`);
+            consola13.success(`Removed adapter: ${id}`);
           } else {
-            consola14.error(`Adapter "${id}" is not installed${local ? " locally" : ""}`);
+            consola13.error(`Adapter "${id}" is not installed${local ? " locally" : ""}`);
             failed = true;
           }
         }
         if (failed)
-          process.exit(1);
+          throw new CliError("Some adapters could not be removed");
       }
     }),
     info: defineCommand15({
@@ -1244,7 +1239,7 @@ var adapterCommand = defineCommand15({
           return;
         }
         if (results.length === 0) {
-          consola14.info(`No adapters matching "${query}"`);
+          consola13.info(`No adapters matching "${query}"`);
           return;
         }
         for (const a of results) {
@@ -1279,29 +1274,29 @@ var adapterCommand = defineCommand15({
         const targetId = args.id ? String(args.id) : void 0;
         const targets = targetId ? [targetId] : index.adapters.map((a) => a.id).filter((id) => isInstalled(id, false));
         if (targets.length === 0) {
-          consola14.info("No adapters installed to update.");
+          consola13.info("No adapters installed to update.");
           return;
         }
         for (const id of targets) {
           const entry = findAdapter(index, id);
           if (!entry) {
-            consola14.warn(`${id}: not found in registry, skipping`);
+            consola13.warn(`${id}: not found in registry, skipping`);
             continue;
           }
           const localDigest = getInstalledDigest(id, false);
           if (localDigest === entry.digest) {
-            consola14.info(`${id}: already up to date`);
+            consola13.info(`${id}: already up to date`);
             continue;
           }
           if (localDigest && !args.yes) {
-            consola14.warn(`${id}: digest will change \u2014 existing grants for this adapter will be invalidated`);
-            consola14.info(`  Old: ${localDigest}`);
-            consola14.info(`  New: ${entry.digest}`);
-            consola14.info("  Use --yes to confirm");
+            consola13.warn(`${id}: digest will change \u2014 existing grants for this adapter will be invalidated`);
+            consola13.info(`  Old: ${localDigest}`);
+            consola13.info(`  New: ${entry.digest}`);
+            consola13.info("  Use --yes to confirm");
             continue;
           }
           const result = await installAdapter(entry);
-          consola14.success(`Updated ${result.id} \u2192 ${result.path}`);
+          consola13.success(`Updated ${result.id} \u2192 ${result.path}`);
         }
       }
     }),
@@ -1338,12 +1333,11 @@ var adapterCommand = defineCommand15({
         if (!localDigest)
           throw new Error(`Adapter "${id}" is not installed${local ? " locally" : ""}`);
         if (localDigest === entry.digest) {
-          consola14.success(`${id}: digest matches registry`);
+          consola13.success(`${id}: digest matches registry`);
         } else {
-          consola14.error(`${id}: digest mismatch`);
           console.log(`  Local:    ${localDigest}`);
           console.log(`  Registry: ${entry.digest}`);
-          process.exit(1);
+          throw new CliError(`${id}: digest mismatch`);
         }
       }
     })
@@ -1365,7 +1359,7 @@ import {
   verifyAndExecute,
   waitForGrantStatus
 } from "@openape/shapes";
-import consola15 from "consola";
+import consola14 from "consola";
 var runCommand = defineCommand16({
   meta: {
     name: "run",
@@ -1440,6 +1434,10 @@ async function runAdapterMode(command, rawArgs, args) {
   const idp = getIdpUrl(args.idp);
   if (!idp)
     throw new Error("No IdP URL configured. Run `apes login` first or pass --idp.");
+  if (args.as) {
+    await runAudienceMode("escapes", command.join(" "), args);
+    return;
+  }
   const adapterOpt = extractOption(rawArgs, "adapter");
   const loaded = loadAdapter3(command[0], adapterOpt);
   const resolved = await resolveCommand(loaded, command);
@@ -1447,7 +1445,7 @@ async function runAdapterMode(command, rawArgs, args) {
   try {
     const existingGrantId = await findExistingGrant(resolved, idp);
     if (existingGrantId) {
-      consola15.info(`Reusing existing grant: ${existingGrantId}`);
+      consola14.info(`Reusing existing grant: ${existingGrantId}`);
       const token2 = await fetchGrantToken(idp, existingGrantId);
       await verifyAndExecute(token2, resolved);
       return;
@@ -1459,17 +1457,17 @@ async function runAdapterMode(command, rawArgs, args) {
     approval,
     ...args.reason ? { reason: args.reason } : {}
   });
-  consola15.info(`Grant requested: ${grant.id}`);
-  consola15.info(`Approve at: ${idp}/grant-approval?grant_id=${grant.id}`);
+  consola14.info(`Grant requested: ${grant.id}`);
+  consola14.info(`Approve at: ${idp}/grant-approval?grant_id=${grant.id}`);
   if (grant.similar_grants?.similar_grants?.length) {
     const n = grant.similar_grants.similar_grants.length;
-    consola15.info("");
-    consola15.info(`  Similar grant(s) found (${n}). Your approver can extend an existing grant to cover this request.`);
+    consola14.info("");
+    consola14.info(`  Similar grant(s) found (${n}). Your approver can extend an existing grant to cover this request.`);
     if (grant.similar_grants.widened_details?.length) {
       const wider = grant.similar_grants.widened_details.map((d) => d.permission).join(", ");
-      consola15.info(`  Broader scope: ${wider}`);
+      consola14.info(`  Broader scope: ${wider}`);
     }
-    consola15.info("");
+    consola14.info("");
   }
   const status = await waitForGrantStatus(idp, grant.id);
   if (status !== "approved")
@@ -1480,14 +1478,13 @@ async function runAdapterMode(command, rawArgs, args) {
 async function runAudienceMode(audience, action, args) {
   const auth = loadAuth();
   if (!auth) {
-    consola15.error("Not logged in. Run `apes login` first.");
-    return process.exit(1);
+    throw new CliError("Not logged in. Run `apes login` first.");
   }
   const idp = getIdpUrl(args.idp);
   const grantsUrl = await getGrantsEndpoint(idp);
   const command = action.split(" ");
   const targetHost = args.host || hostname3();
-  consola15.info(`Requesting ${audience} grant on ${targetHost}: ${command.join(" ")}`);
+  consola14.info(`Requesting ${audience} grant on ${targetHost}: ${command.join(" ")}`);
   const grant = await apiFetch(grantsUrl, {
     method: "POST",
     body: {
@@ -1500,36 +1497,35 @@ async function runAudienceMode(audience, action, args) {
       ...args.as ? { run_as: args.as } : {}
     }
   });
-  consola15.success(`Grant requested: ${grant.id}`);
-  consola15.info("Waiting for approval...");
+  consola14.success(`Grant requested: ${grant.id}`);
+  consola14.info("Waiting for approval...");
   const maxWait = 3e5;
   const interval = 3e3;
   const start = Date.now();
   while (Date.now() - start < maxWait) {
     const status = await apiFetch(`${grantsUrl}/${grant.id}`);
     if (status.status === "approved") {
-      consola15.success("Grant approved!");
+      consola14.success("Grant approved!");
       break;
     }
     if (status.status === "denied" || status.status === "revoked") {
-      consola15.error(`Grant ${status.status}.`);
-      return process.exit(1);
+      throw new CliError(`Grant ${status.status}.`);
     }
     await new Promise((r) => setTimeout(r, interval));
   }
-  consola15.info("Fetching grant token...");
+  consola14.info("Fetching grant token...");
   const { authz_jwt } = await apiFetch(`${grantsUrl}/${grant.id}/token`, {
     method: "POST"
   });
   if (audience === "escapes") {
-    consola15.info(`Executing: ${command.join(" ")}`);
+    consola14.info(`Executing: ${command.join(" ")}`);
     try {
       execFileSync(args["escapes-path"] || "escapes", ["--grant", authz_jwt, "--", ...command], {
         stdio: "inherit"
       });
     } catch (err) {
       const exitCode = err.status || 1;
-      process.exit(exitCode);
+      throw new CliExit(exitCode);
     }
   } else {
     process.stdout.write(authz_jwt);
@@ -1578,7 +1574,7 @@ var explainCommand = defineCommand17({
 
 // src/commands/config/get.ts
 import { defineCommand as defineCommand18 } from "citty";
-import consola16 from "consola";
+import consola15 from "consola";
 var configGetCommand = defineCommand18({
   meta: {
     name: "get",
@@ -1599,7 +1595,7 @@ var configGetCommand = defineCommand18({
         if (idp)
           console.log(idp);
         else
-          consola16.info("No IdP configured.");
+          consola15.info("No IdP configured.");
         break;
       }
       case "email": {
@@ -1607,7 +1603,7 @@ var configGetCommand = defineCommand18({
         if (auth?.email)
           console.log(auth.email);
         else
-          consola16.info("Not logged in.");
+          consola15.info("Not logged in.");
         break;
       }
       default: {
@@ -1620,11 +1616,10 @@ var configGetCommand = defineCommand18({
           if (sectionObj && field in sectionObj) {
             console.log(sectionObj[field]);
           } else {
-            consola16.info(`Key "${key}" not set.`);
+            consola15.info(`Key "${key}" not set.`);
           }
         } else {
-          consola16.error(`Unknown key: "${key}". Use: idp, email, defaults.idp, defaults.approval, agent.key, agent.email`);
-          process.exit(1);
+          throw new CliError(`Unknown key: "${key}". Use: idp, email, defaults.idp, defaults.approval, agent.key, agent.email`);
         }
       }
     }
@@ -1633,7 +1628,7 @@ var configGetCommand = defineCommand18({
 
 // src/commands/config/set.ts
 import { defineCommand as defineCommand19 } from "citty";
-import consola17 from "consola";
+import consola16 from "consola";
 var configSetCommand = defineCommand19({
   meta: {
     name: "set",
@@ -1657,8 +1652,7 @@ var configSetCommand = defineCommand19({
     const config = loadConfig();
     const parts = key.split(".");
     if (parts.length !== 2) {
-      consola17.error(`Invalid key: "${key}". Use: defaults.idp, defaults.approval, agent.key, agent.email`);
-      return process.exit(1);
+      throw new CliError(`Invalid key: "${key}". Use: defaults.idp, defaults.approval, agent.key, agent.email`);
     }
     const [section, field] = parts;
     if (section === "defaults") {
@@ -1668,22 +1662,19 @@ var configSetCommand = defineCommand19({
       config.agent = config.agent || {};
       config.agent[field] = value;
     } else {
-      consola17.error(`Unknown section: "${section}". Use: defaults, agent`);
-      return process.exit(1);
+      throw new CliError(`Unknown section: "${section}". Use: defaults, agent`);
     }
     saveConfig(config);
-    consola17.success(`Set ${key} = ${value}`);
+    consola16.success(`Set ${key} = ${value}`);
   }
 });
 
 // src/commands/fetch/index.ts
 import { defineCommand as defineCommand20 } from "citty";
-import consola18 from "consola";
 async function doRequest(method, url, body, contentType, raw, showHeaders) {
   const token = getAuthToken();
   if (!token) {
-    consola18.error("Not authenticated. Run `apes login` first.");
-    return process.exit(1);
+    throw new CliError("Not authenticated. Run `apes login` first.");
   }
   const response = await fetch(url, {
     method,
@@ -1712,7 +1703,7 @@ async function doRequest(method, url, body, contentType, raw, showHeaders) {
     }
   }
   if (!response.ok) {
-    process.exit(1);
+    throw new CliError(`HTTP ${response.status} ${response.statusText}`);
   }
 }
 var fetchCommand = defineCommand20({
@@ -1810,7 +1801,7 @@ var mcpCommand = defineCommand21({
     if (transport !== "stdio" && transport !== "sse") {
       throw new Error('Transport must be "stdio" or "sse"');
     }
-    const { startMcpServer } = await import("./server-5ZRR26S4.js");
+    const { startMcpServer } = await import("./server-IYR5LM63.js");
     await startMcpServer(transport, port);
   }
 });
@@ -1821,7 +1812,7 @@ import { randomBytes } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import { join } from "path";
 import { defineCommand as defineCommand22 } from "citty";
-import consola19 from "consola";
+import consola17 from "consola";
 var DEFAULT_IDP_URL = "https://id.openape.at";
 async function downloadTemplate(repo, targetDir) {
   const { downloadTemplate: gigetDownload } = await import("giget");
@@ -1838,16 +1829,16 @@ function installDeps(dir) {
   }
 }
 async function promptChoice(message, choices) {
-  const result = await consola19.prompt(message, { type: "select", options: choices });
+  const result = await consola17.prompt(message, { type: "select", options: choices });
   if (typeof result === "symbol") {
-    process.exit(0);
+    throw new CliExit(0);
   }
   return result;
 }
 async function promptText(message, defaultValue) {
-  const result = await consola19.prompt(message, { type: "text", default: defaultValue, placeholder: defaultValue });
+  const result = await consola17.prompt(message, { type: "text", default: defaultValue, placeholder: defaultValue });
   if (typeof result === "symbol") {
-    process.exit(0);
+    throw new CliExit(0);
   }
   return result || defaultValue || "";
 }
@@ -1894,23 +1885,22 @@ var initCommand = defineCommand22({
 async function initSP(targetDir) {
   const dir = targetDir || "my-app";
   if (existsSync(join(dir, "package.json"))) {
-    consola19.error(`Directory "${dir}" already contains a project.`);
-    return process.exit(1);
+    throw new CliError(`Directory "${dir}" already contains a project.`);
   }
-  consola19.start("Scaffolding SP starter...");
+  consola17.start("Scaffolding SP starter...");
   await downloadTemplate("openape-ai/openape-sp-starter", dir);
-  consola19.success("Scaffolded from openape-sp-starter");
-  consola19.start("Installing dependencies...");
+  consola17.success("Scaffolded from openape-sp-starter");
+  consola17.start("Installing dependencies...");
   installDeps(dir);
-  consola19.success("Dependencies installed");
+  consola17.success("Dependencies installed");
   const envExample = join(dir, ".env.example");
   const envFile = join(dir, ".env");
   if (existsSync(envExample) && !existsSync(envFile)) {
     copyFileSync(envExample, envFile);
-    consola19.success(`\`.env\` created (using Free IdP at ${DEFAULT_IDP_URL})`);
+    consola17.success(`\`.env\` created (using Free IdP at ${DEFAULT_IDP_URL})`);
   }
   console.log("");
-  consola19.box([
+  consola17.box([
     `cd ${dir}`,
     "npm run dev",
     "",
@@ -1920,8 +1910,7 @@ async function initSP(targetDir) {
 async function initIdP(targetDir) {
   const dir = targetDir || "my-idp";
   if (existsSync(join(dir, "package.json"))) {
-    consola19.error(`Directory "${dir}" already contains a project.`);
-    return process.exit(1);
+    throw new CliError(`Directory "${dir}" already contains a project.`);
   }
   const domain = await promptText("Domain for the IdP", "localhost");
   const storage = await promptChoice("Storage backend", [
@@ -1930,15 +1919,15 @@ async function initIdP(targetDir) {
     "s3 (S3-compatible)"
   ]);
   const adminEmail = await promptText("Admin email");
-  consola19.start("Scaffolding IdP starter...");
+  consola17.start("Scaffolding IdP starter...");
   await downloadTemplate("openape-ai/openape-idp-starter", dir);
-  consola19.success("Scaffolded from openape-idp-starter");
-  consola19.start("Installing dependencies...");
+  consola17.success("Scaffolded from openape-idp-starter");
+  consola17.start("Installing dependencies...");
   installDeps(dir);
-  consola19.success("Dependencies installed");
+  consola17.success("Dependencies installed");
   const sessionSecret = randomBytes(32).toString("hex");
   const managementToken = randomBytes(32).toString("hex");
-  consola19.success("Secrets generated");
+  consola17.success("Secrets generated");
   const isLocalhost = domain === "localhost";
   const origin = isLocalhost ? "http://localhost:3000" : `https://${domain}`;
   const envContent = [
@@ -1952,10 +1941,11 @@ async function initIdP(targetDir) {
     `NUXT_OPENAPE_RP_ID=${domain}`,
     `NUXT_OPENAPE_RP_ORIGIN=${origin}`
   ].join("\n");
-  writeFileSync(join(dir, ".env"), envContent + "\n", { mode: 384 });
-  consola19.success(".env created");
+  writeFileSync(join(dir, ".env"), `${envContent}
+`, { mode: 384 });
+  consola17.success(".env created");
   console.log("");
-  consola19.box([
+  consola17.box([
     `cd ${dir}`,
     "npm run dev",
     "",
@@ -1978,7 +1968,7 @@ import { generateKeyPairSync, sign } from "crypto";
 import { dirname, resolve } from "path";
 import { homedir } from "os";
 import { defineCommand as defineCommand23 } from "citty";
-import consola20 from "consola";
+import consola18 from "consola";
 var DEFAULT_IDP_URL2 = "https://id.openape.at";
 var DEFAULT_KEY_PATH = "~/.ssh/id_ed25519";
 var POLL_INTERVAL = 3e3;
@@ -2083,38 +2073,48 @@ var enrollCommand = defineCommand23({
     }
   },
   async run({ args }) {
-    const idp = args.idp || await consola20.prompt("IdP URL", { type: "text", default: DEFAULT_IDP_URL2, placeholder: DEFAULT_IDP_URL2 }).then((r) => typeof r === "symbol" ? process.exit(0) : r) || DEFAULT_IDP_URL2;
-    const agentName = args.name || await consola20.prompt("Agent name", { type: "text", placeholder: "deploy-bot" }).then((r) => typeof r === "symbol" ? process.exit(0) : r);
+    const idp = args.idp || await consola18.prompt("IdP URL", { type: "text", default: DEFAULT_IDP_URL2, placeholder: DEFAULT_IDP_URL2 }).then((r) => {
+      if (typeof r === "symbol") throw new CliExit(0);
+      return r;
+    }) || DEFAULT_IDP_URL2;
+    const agentName = args.name || await consola18.prompt("Agent name", { type: "text", placeholder: "deploy-bot" }).then((r) => {
+      if (typeof r === "symbol") throw new CliExit(0);
+      return r;
+    });
     if (!agentName) {
-      consola20.error("Agent name is required.");
-      return process.exit(1);
+      throw new CliError("Agent name is required.");
     }
-    const keyPath = args.key || await consola20.prompt("Ed25519 key", { type: "text", default: DEFAULT_KEY_PATH, placeholder: DEFAULT_KEY_PATH }).then((r) => typeof r === "symbol" ? process.exit(0) : r) || DEFAULT_KEY_PATH;
+    const keyPath = args.key || await consola18.prompt("Ed25519 key", { type: "text", default: DEFAULT_KEY_PATH, placeholder: DEFAULT_KEY_PATH }).then((r) => {
+      if (typeof r === "symbol") throw new CliExit(0);
+      return r;
+    }) || DEFAULT_KEY_PATH;
     const resolvedKey = resolvePath(keyPath);
     let publicKey;
     if (existsSync2(resolvedKey)) {
       publicKey = readPublicKey(resolvedKey);
-      consola20.success(`Using existing key ${keyPath}`);
+      consola18.success(`Using existing key ${keyPath}`);
     } else {
-      consola20.start(`Generating Ed25519 key pair at ${keyPath}...`);
+      consola18.start(`Generating Ed25519 key pair at ${keyPath}...`);
       publicKey = generateAndSaveKey(keyPath);
-      consola20.success(`Key pair generated at ${keyPath}`);
+      consola18.success(`Key pair generated at ${keyPath}`);
     }
     const encodedKey = encodeURIComponent(publicKey);
     const enrollUrl = `${idp}/enroll?name=${encodeURIComponent(agentName)}&key=${encodedKey}`;
-    consola20.info("Opening browser for enrollment...");
-    consola20.info(`\u2192 ${idp}/enroll`);
+    consola18.info("Opening browser for enrollment...");
+    consola18.info(`\u2192 ${idp}/enroll`);
     openBrowser2(enrollUrl);
     console.log("");
-    const agentEmail = await consola20.prompt(
+    const agentEmail = await consola18.prompt(
       "Agent email (shown in browser after enrollment)",
       { type: "text", placeholder: `agent+${agentName}@...` }
-    ).then((r) => typeof r === "symbol" ? process.exit(0) : r);
+    ).then((r) => {
+      if (typeof r === "symbol") throw new CliExit(0);
+      return r;
+    });
     if (!agentEmail) {
-      consola20.error("Agent email is required to verify enrollment.");
-      return process.exit(1);
+      throw new CliError("Agent email is required to verify enrollment.");
     }
-    consola20.start("Verifying enrollment...");
+    consola18.start("Verifying enrollment...");
     const { token, expiresIn } = await pollForEnrollment(idp, agentEmail, keyPath);
     saveAuth({
       idp,
@@ -2126,16 +2126,16 @@ var enrollCommand = defineCommand23({
     config.defaults = { ...config.defaults, idp };
     config.agent = { key: keyPath, email: agentEmail };
     saveConfig(config);
-    consola20.success(`Agent enrolled as ${agentEmail}`);
-    consola20.success("Config saved to ~/.config/apes/");
+    consola18.success(`Agent enrolled as ${agentEmail}`);
+    consola18.success("Config saved to ~/.config/apes/");
     console.log("");
-    consola20.info("Verify with: apes whoami");
+    consola18.info("Verify with: apes whoami");
   }
 });
 
 // src/commands/dns-check.ts
 import { defineCommand as defineCommand24 } from "citty";
-import consola21 from "consola";
+import consola19 from "consola";
 import { resolveDDISA } from "@openape/core";
 var dnsCheckCommand = defineCommand24({
   meta: {
@@ -2151,17 +2151,16 @@ var dnsCheckCommand = defineCommand24({
   },
   async run({ args }) {
     const domain = args.domain;
-    consola21.start(`Checking _ddisa.${domain}...`);
+    consola19.start(`Checking _ddisa.${domain}...`);
     try {
       const result = await resolveDDISA(domain);
       if (!result) {
-        consola21.error(`No DDISA record found for ${domain}`);
         console.log("");
         console.log("To set up DDISA, add a DNS TXT record:");
         console.log(`  _ddisa.${domain} TXT "v=ddisa1 idp=https://id.${domain}"`);
-        return process.exit(1);
+        throw new CliError(`No DDISA record found for ${domain}`);
       }
-      consola21.success(`_ddisa.${domain} \u2192 ${result.idp}`);
+      consola19.success(`_ddisa.${domain} \u2192 ${result.idp}`);
       console.log("");
       console.log(`  Version:  ${result.version || "ddisa1"}`);
       console.log(`  IdP URL:  ${result.idp}`);
@@ -2170,14 +2169,14 @@ var dnsCheckCommand = defineCommand24({
       if (result.priority !== void 0)
         console.log(`  Priority: ${result.priority}`);
       console.log("");
-      consola21.start(`Verifying IdP at ${result.idp}...`);
+      consola19.start(`Verifying IdP at ${result.idp}...`);
       const discoResp = await fetch(`${result.idp}/.well-known/openid-configuration`);
       if (!discoResp.ok) {
-        consola21.warn(`IdP discovery failed (${discoResp.status}). Is the IdP running at ${result.idp}?`);
+        consola19.warn(`IdP discovery failed (${discoResp.status}). Is the IdP running at ${result.idp}?`);
         return;
       }
       const disco = await discoResp.json();
-      consola21.success(`IdP is reachable`);
+      consola19.success(`IdP is reachable`);
       console.log(`  Issuer:   ${disco.issuer}`);
       console.log(`  DDISA:    v${disco.ddisa_version || "?"}`);
       if (disco.ddisa_auth_methods_supported) {
@@ -2187,15 +2186,130 @@ var dnsCheckCommand = defineCommand24({
         console.log(`  Grants:   ${disco.openape_grant_types_supported.join(", ")}`);
       }
     } catch (err) {
-      consola21.error(`DNS check failed: ${err instanceof Error ? err.message : String(err)}`);
-      return process.exit(1);
+      throw new CliError(`DNS check failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+});
+
+// src/commands/workflows.ts
+import { defineCommand as defineCommand25 } from "citty";
+import consola20 from "consola";
+
+// src/guides/index.ts
+var guides = [
+  {
+    id: "timed-session",
+    title: "Timed maintenance session",
+    description: "Request a timed grant for multiple commands without per-command approval.",
+    steps: [
+      { description: "Request a timed grant (e.g. 1 hour)", command: "apes run --approval timed -- <your-command>" },
+      { description: "Approve the grant in the browser (link is printed)" },
+      { description: "Subsequent commands reuse the timed grant until it expires" },
+      { note: "Use --approval always for standing permissions (revoke manually when done)" }
+    ]
+  },
+  {
+    id: "agent-onboarding",
+    title: "Onboard a new agent",
+    description: "Register an AI agent with a DDISA identity in under 3 minutes.",
+    steps: [
+      { description: "Initialize a new project (optional)", command: "apes init --sp my-app" },
+      { description: "Enroll the agent at an IdP", command: "apes enroll" },
+      { description: "Verify enrollment", command: "apes whoami" },
+      { description: "Check DNS discovery", command: "apes dns-check" }
+    ]
+  },
+  {
+    id: "delegation",
+    title: "Delegate permissions",
+    description: "Let an agent act on your behalf at a specific service.",
+    steps: [
+      { description: "Create a delegation", command: "apes grants delegate --to agent@example.com --at api.example.com" },
+      { description: "List active delegations", command: "apes grants delegations" },
+      { description: "Revoke when no longer needed", command: "apes grants revoke <delegation-id>" }
+    ]
+  },
+  {
+    id: "privilege-escalation",
+    title: "Run commands as root (escapes)",
+    description: "Execute privileged commands with grant-verified escalation.",
+    steps: [
+      { description: "Request a grant to run a command as root", command: "apes run --as root -- apt-get upgrade" },
+      { description: "Approve the grant in the browser" },
+      { description: "The command executes via escapes with verified authorization" },
+      { note: "escapes must be installed on the target machine (cargo build && sudo make install)" }
+    ]
+  }
+];
+
+// src/commands/workflows.ts
+var workflowsCommand = defineCommand25({
+  meta: {
+    name: "workflows",
+    description: "Discover workflow guides"
+  },
+  args: {
+    id: {
+      type: "positional",
+      description: "Guide ID to show (omit for list)",
+      required: false
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON",
+      default: false
     }
+  },
+  run({ args }) {
+    if (args.id) {
+      const guide = guides.find((g) => g.id === String(args.id));
+      if (!guide) {
+        consola20.info(`Available: ${guides.map((g) => g.id).join(", ")}`);
+        throw new CliError(`Guide not found: ${args.id}`);
+      }
+      if (args.json) {
+        console.log(JSON.stringify(guide, null, 2));
+        return;
+      }
+      console.log(`
+  ${guide.title}`);
+      console.log(`  ${guide.description}
+`);
+      for (let i = 0; i < guide.steps.length; i++) {
+        const step = guide.steps[i];
+        if (step.note) {
+          console.log(`  Note: ${step.note}`);
+        } else {
+          console.log(`  ${i + 1}. ${step.description}`);
+          if (step.command) {
+            console.log(`     $ ${step.command}`);
+          }
+        }
+      }
+      console.log();
+      return;
+    }
+    if (args.json) {
+      console.log(JSON.stringify(guides.map((g) => ({ id: g.id, title: g.title, description: g.description })), null, 2));
+      return;
+    }
+    console.log("\n  Workflow Guides\n");
+    for (const guide of guides) {
+      console.log(`  ${guide.id.padEnd(24)} ${guide.title}`);
+    }
+    console.log(`
+  Show a guide: apes workflows <id>
+`);
   }
 });
 
 // src/cli.ts
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") process.exit(0);
+  throw err;
+});
 var debug = process.argv.includes("--debug");
-var grantsCommand = defineCommand25({
+var grantsCommand = defineCommand26({
   meta: {
     name: "grants",
     description: "Grant management"
@@ -2214,7 +2328,7 @@ var grantsCommand = defineCommand25({
     delegations: delegationsCommand
   }
 });
-var configCommand = defineCommand25({
+var configCommand = defineCommand26({
   meta: {
     name: "config",
     description: "Configuration management"
@@ -2224,10 +2338,10 @@ var configCommand = defineCommand25({
     set: configSetCommand
   }
 });
-var main = defineCommand25({
+var main = defineCommand26({
   meta: {
     name: "apes",
-    version: "0.5.4",
+    version: "0.6.0",
     description: "Unified CLI for OpenApe"
   },
   subCommands: {
@@ -2243,14 +2357,22 @@ var main = defineCommand25({
     adapter: adapterCommand,
     config: configCommand,
     fetch: fetchCommand,
-    mcp: mcpCommand
+    mcp: mcpCommand,
+    workflows: workflowsCommand
   }
 });
 runMain(main).catch((err) => {
+  if (err instanceof CliExit) {
+    process.exit(err.exitCode);
+  }
+  if (err instanceof CliError) {
+    consola21.error(err.message);
+    process.exit(err.exitCode);
+  }
   if (debug) {
-    consola22.error(err);
+    consola21.error(err);
   } else {
-    consola22.error(err instanceof ApiError ? err.message : err instanceof Error ? err.message : String(err));
+    consola21.error(err instanceof ApiError ? err.message : err instanceof Error ? err.message : String(err));
   }
   process.exit(1);
 });