@tinycloud/cli 1.5.0-beta.2 → 1.5.0-beta.21

package/dist/legacy-entry.js

@@ -174,6 +174,35 @@ var init_storage = __esm({
   }
 });
 
+// src/config/types.ts
+function isCLIProfilePosture(value) {
+  return typeof value === "string" && CLI_PROFILE_POSTURES.includes(value);
+}
+function isCLIOperatorType(value) {
+  return typeof value === "string" && CLI_OPERATOR_TYPES.includes(value);
+}
+function resolveProfilePosture(profile) {
+  if (isCLIProfilePosture(profile.posture)) return profile.posture;
+  if (profile.authMethod === "local") return "local-owner-key";
+  return "owner-openkey";
+}
+function resolveProfileOperatorType(profile) {
+  if (isCLIOperatorType(profile.operatorType)) return profile.operatorType;
+  return "human";
+}
+var CLI_PROFILE_POSTURES, CLI_OPERATOR_TYPES;
+var init_types = __esm({
+  "src/config/types.ts"() {
+    "use strict";
+    CLI_PROFILE_POSTURES = [
+      "owner-openkey",
+      "delegate-session",
+      "local-owner-key"
+    ];
+    CLI_OPERATOR_TYPES = ["human", "agent"];
+  }
+});
+
 // src/lib/replication-registry.ts
 function stopForSignal(signal) {
   void closeReplication().finally(() => {
@@ -903,35 +932,6 @@ var init_errors = __esm({
   }
 });
 
-// src/config/types.ts
-function isCLIProfilePosture(value) {
-  return typeof value === "string" && CLI_PROFILE_POSTURES.includes(value);
-}
-function isCLIOperatorType(value) {
-  return typeof value === "string" && CLI_OPERATOR_TYPES.includes(value);
-}
-function resolveProfilePosture(profile) {
-  if (isCLIProfilePosture(profile.posture)) return profile.posture;
-  if (profile.authMethod === "local") return "local-owner-key";
-  return "owner-openkey";
-}
-function resolveProfileOperatorType(profile) {
-  if (isCLIOperatorType(profile.operatorType)) return profile.operatorType;
-  return "human";
-}
-var CLI_PROFILE_POSTURES, CLI_OPERATOR_TYPES;
-var init_types = __esm({
-  "src/config/types.ts"() {
-    "use strict";
-    CLI_PROFILE_POSTURES = [
-      "owner-openkey",
-      "delegate-session",
-      "local-owner-key"
-    ];
-    CLI_OPERATOR_TYPES = ["human", "agent"];
-  }
-});
-
 // src/lib/space.ts
 import { CLI_NAME as CLI_NAME3 } from "@tinycloud/operations/cli-name";
 function invalidSpaceError(input) {
@@ -1857,7 +1857,8 @@ var init_sha256 = __esm({
 });
 
 // ../sdk-core/src/manifest.ts
-import { resolveSecretPath, SECRET_NAME_RE } from "@tinycloud/sdk-services";
+import { resolveSecretPath, SECRET_NAME_RE, parseNetworkId } from "@tinycloud/sdk-services";
+import { parseEncryptionResource } from "@tinycloud/sdk-services/encryption/resource";
 function parseExpiry(duration) {
   if (typeof duration !== "string" || duration.length === 0) {
     throw new ManifestValidationError(
@@ -1900,6 +1901,14 @@ function expandEncryptionPermissionEntry(entry) {
       `tinycloud.encryption entries require path to be a networkId URN (got ${JSON.stringify(entry.path)})`
     );
   }
+  if (entry.path.includes("/")) {
+    throw new ManifestValidationError("named keys go in manifest.keys");
+  }
+  try {
+    parseNetworkId(entry.path);
+  } catch {
+    throw new ManifestValidationError("tinycloud.encryption entries require a valid networkId URN");
+  }
   const normalizedActions = [];
   for (const action of entry.actions) {
     if (action === "decrypt" || action === "tinycloud.encryption/decrypt") {
@@ -2004,8 +2013,52 @@ function validateManifest(input) {
   if (m.secrets !== void 0) {
     validateManifestSecrets(m.secrets);
   }
+  if (Object.prototype.hasOwnProperty.call(m, "keys_app_id") && (typeof m.keys_app_id !== "string" || !KEY_APP_ID.test(m.keys_app_id))) {
+    throw new ManifestValidationError("manifest.keys_app_id is invalid");
+  }
+  validateManifestKeys(m.keys_app_id ?? m.app_id, m.keys);
   return m;
 }
+function validateManifestKeys(appId, keys) {
+  if (keys === void 0) return;
+  if (!Array.isArray(keys) || keys.length > 32) {
+    throw new ManifestValidationError("manifest.keys must contain at most 32 entries");
+  }
+  if (keys.length === 0) return;
+  if (!KEY_APP_ID.test(appId)) {
+    throw new ManifestValidationError("manifest.keys requires a valid app_id");
+  }
+  const paths = /* @__PURE__ */ new Set();
+  let prefixSeen = false;
+  for (const [index, value] of keys.entries()) {
+    const label = `manifest.keys[${index}]`;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new ManifestValidationError(`${label} must be an object`);
+    }
+    const entry = value;
+    const fields = Object.keys(entry);
+    const hasPath = Object.prototype.hasOwnProperty.call(entry, "path");
+    const hasPrefix = Object.prototype.hasOwnProperty.call(entry, "prefix");
+    if (hasPath === hasPrefix || fields.some((field) => !["path", "prefix", "abilities"].includes(field))) {
+      throw new ManifestValidationError(`${label} must have one path or prefix and abilities`);
+    }
+    if (!Array.isArray(entry.abilities) || entry.abilities.length === 0 || new Set(entry.abilities).size !== entry.abilities.length || entry.abilities.some((ability) => typeof ability !== "string" || !KEY_ABILITIES.includes(ability))) {
+      throw new ManifestValidationError(`${label}.abilities is invalid`);
+    }
+    if (hasPath) {
+      const path = entry.path;
+      if (typeof path !== "string" || path.length > 255 || !KEY_PATH.test(path) || !path.startsWith(`apps/${appId}/`) || paths.has(path)) {
+        throw new ManifestValidationError(`${label}.path is invalid`);
+      }
+      paths.add(path);
+    } else {
+      if (entry.prefix !== `apps/${appId}/` || prefixSeen) {
+        throw new ManifestValidationError(`${label}.prefix is invalid`);
+      }
+      prefixSeen = true;
+    }
+  }
+}
 function resolveManifestKnowledgeRoot(knowledge) {
   if (knowledge === void 0) {
     return void 0;
@@ -2405,7 +2458,7 @@ function withCapabilitiesReadForSpaces(resources) {
     ...[...spaces].map(capabilitiesReadPermission)
   ]);
 }
-var import_ms, DEFAULT_KNOWLEDGE_ROOT, ManifestValidationError, DEFAULT_EXPIRY, DEFAULT_DEFAULTS, DEFAULT_MANIFEST_VERSION, DEFAULT_MANIFEST_SPACE, SECRETS_SPACE, VAULT_PERMISSION_SERVICE, SERVICE_SHORT_TO_LONG, ENCRYPTION_PERMISSION_SERVICE, ENCRYPTION_MANIFEST_SPACE, SERVICE_LONG_TO_SHORT2, DEFAULT_STANDARD_ENTRIES, DEFAULT_ADMIN_ENTRIES, DEFAULT_ALL_ENTRIES;
+var import_ms, DEFAULT_KNOWLEDGE_ROOT, ManifestValidationError, DEFAULT_EXPIRY, DEFAULT_DEFAULTS, DEFAULT_MANIFEST_VERSION, DEFAULT_MANIFEST_SPACE, SECRETS_SPACE, VAULT_PERMISSION_SERVICE, SERVICE_SHORT_TO_LONG, ENCRYPTION_PERMISSION_SERVICE, ENCRYPTION_MANIFEST_SPACE, SERVICE_LONG_TO_SHORT2, DEFAULT_STANDARD_ENTRIES, DEFAULT_ADMIN_ENTRIES, DEFAULT_ALL_ENTRIES, KEY_SEGMENT, KEY_APP_ID, KEY_PATH, KEY_ABILITIES;
 var init_manifest = __esm({
   "../sdk-core/src/manifest.ts"() {
     "use strict";
@@ -2488,6 +2541,10 @@ var init_manifest = __esm({
         actions: ["read", "write"]
       }
     ];
+    KEY_SEGMENT = "[a-z0-9][a-z0-9._-]{0,63}";
+    KEY_APP_ID = new RegExp(`^${KEY_SEGMENT}$`);
+    KEY_PATH = new RegExp(`^${KEY_SEGMENT}(?:/${KEY_SEGMENT}){2,7}$`);
+    KEY_ABILITIES = ["key.create", "decrypt", "key.block", "key.unblock"];
   }
 });
 
@@ -5203,6 +5260,9 @@ function assertReadable(authority, now) {
 function contentHash(bytes) {
   return bytesToHex(blake3(bytes));
 }
+function repairId(entry) {
+  return `${entry.hash}\0${entry.key}`;
+}
 function sameEtag(a, b) {
   return a.replace(/^"|"$/g, "") === b.replace(/^"|"$/g, "");
 }
@@ -5518,8 +5578,8 @@ function fetched(key, result, request) {
   }
   return { bytes: result.data.data, etag: result.data.headers.etag ?? "" };
 }
-function kvSyncTransport(kv, options = {}) {
-  const host = options.host ?? kv.host;
+function kvSyncTransport(kv2, options = {}) {
+  const host = options.host ?? kv2.host;
   const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
   return {
     async syncPage({ prefix, cursor, limit, retentionGrant, signal }) {
@@ -5538,7 +5598,7 @@ function kvSyncTransport(kv, options = {}) {
           );
         }
       }
-      const result = await kv.changes({
+      const result = await kv2.changes({
         prefix,
         limit,
         ...cursor === void 0 ? {} : { cursor },
@@ -5553,7 +5613,7 @@ function kvSyncTransport(kv, options = {}) {
       if (keys.length === 0) return contents;
       const signal = options2?.signal;
       const ordered = [...keys].sort(compareKeyBytes);
-      const batch = await kv.batchGet(ordered, { binary: true, ...signal === void 0 ? {} : { signal } });
+      const batch = await kv2.batchGet(ordered, { binary: true, ...signal === void 0 ? {} : { signal } });
       if (batch.ok) {
         for (const item of batch.data.results) {
           const result = item.result;
@@ -5566,13 +5626,13 @@ function kvSyncTransport(kv, options = {}) {
       for (const key of keys) {
         if (contents.has(key)) continue;
         const request = `Failed to get key ${JSON.stringify(key)}`;
-        contents.set(key, fetched(key, await kv.get(key, { binary: true, ...signal === void 0 ? {} : { signal } }), request));
+        contents.set(key, fetched(key, await kv2.get(key, { binary: true, ...signal === void 0 ? {} : { signal } }), request));
       }
       return contents;
     }
   };
 }
-var ReplicaErrorCode, REPLICA_ERROR, ReplicaError, RFC3339, DEFAULT_PAGE_LIMIT, DEFAULT_LEASE_TTL_MS, FETCH_CHUNK, REPAIR_BATCH, RETENTION_REVOKED, PENDING_REFUSALS, Replica, BASE58, BASE32, featureCache, REVOKED_CODES, REVOKED_BODY, encoder;
+var ReplicaErrorCode, REPLICA_ERROR, ReplicaError, RFC3339, DEFAULT_PAGE_LIMIT, DEFAULT_LEASE_TTL_MS, FETCH_CHUNK, REPAIR_BATCH, REPAIR_MAX_TRIES, REPAIR_BACKOFF_BASE_MS, RETENTION_REVOKED, PENDING_REFUSALS, Replica, BASE58, BASE32, featureCache, REVOKED_CODES, REVOKED_BODY, encoder;
 var init_dist = __esm({
   "../replica/dist/index.js"() {
     "use strict";
@@ -5660,6 +5720,8 @@ var init_dist = __esm({
     DEFAULT_LEASE_TTL_MS = 12e4;
     FETCH_CHUNK = 100;
     REPAIR_BATCH = 100;
+    REPAIR_MAX_TRIES = 5;
+    REPAIR_BACKOFF_BASE_MS = 6e4;
     RETENTION_REVOKED = /* @__PURE__ */ new Set(["retention-grant-revoked", "retention-grant-ancestor-revoked"]);
     PENDING_REFUSALS = /* @__PURE__ */ new Set([
       ReplicaErrorCode.GRANT_UNAUTHORIZED,
@@ -5672,6 +5734,9 @@ var init_dist = __esm({
       #now;
       #leaseTtlMs;
       #onCommit;
+      #contentFetch;
+      /** Failed repair fetches of this session, by key and ETag hash. Never persisted: a new `Replica` retries afresh. */
+      #repairTries = /* @__PURE__ */ new Map();
       constructor(options) {
         this.#store = options.store;
         const transport = options.transport;
@@ -5679,6 +5744,7 @@ var init_dist = __esm({
         this.#now = options.now ?? Date.now;
         this.#leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#onCommit = options.onCommit;
+        this.#contentFetch = options.contentFetch ?? "eager";
       }
       async #state() {
         const state2 = await this.#store.open();
@@ -6007,6 +6073,7 @@ var init_dist = __esm({
           changes[candidate.index].content = true;
           return false;
         });
+        if (this.#contentFetch === "lazy") return { changes, blobs, fetched: 0 };
         let fetched2 = 0;
         for (let start = 0; start < needed.length; start += FETCH_CHUNK) {
           const chunk = needed.slice(start, start + FETCH_CHUNK);
@@ -6026,7 +6093,15 @@ var init_dist = __esm({
         return { changes, blobs, fetched: fetched2 };
       }
       async #repair(attempt, cursor, nodeDid, coverage, retentionGrantCid) {
-        const pending = await this.#store.pendingRepairs(Number.MAX_SAFE_INTEGER);
+        if (this.#contentFetch === "lazy") return 0;
+        const all = await this.#store.pendingRepairs(Number.MAX_SAFE_INTEGER);
+        const now = this.#now();
+        const pendingIds = new Set(all.map((entry) => repairId(entry)));
+        for (const id of this.#repairTries.keys()) if (!pendingIds.has(id)) this.#repairTries.delete(id);
+        const pending = all.filter((entry) => {
+          const state2 = this.#repairTries.get(repairId(entry));
+          return state2 === void 0 || state2.tries < REPAIR_MAX_TRIES && now >= state2.nextAttemptAt;
+        });
         let repaired = 0;
         for (let start = 0; start < pending.length; start += REPAIR_BATCH) {
           const chunk = pending.slice(start, start + REPAIR_BATCH);
@@ -6038,7 +6113,14 @@ var init_dist = __esm({
           const changes = [];
           for (const entry of chunk) {
             const bytes = acceptContent(entry, contents.get(entry.key));
-            if (bytes === void 0) continue;
+            const id = repairId(entry);
+            if (bytes === void 0) {
+              const tries = (this.#repairTries.get(id)?.tries ?? 0) + 1;
+              const wait = tries === 1 ? 0 : REPAIR_BACKOFF_BASE_MS * 2 ** (tries - 2);
+              this.#repairTries.set(id, { tries, nextAttemptAt: this.#now() + wait });
+              continue;
+            }
+            this.#repairTries.delete(id);
             blobs.set(entry.hash, bytes);
             changes.push({ ...entry, content: true });
           }
@@ -9760,6 +9842,7 @@ var init_profiles = __esm({
     "use strict";
     init_constants();
     init_storage();
+    init_types();
     init_errors();
     ProfileManager = class _ProfileManager {
       // ── Initialization ──────────────────────────────────────────────────
@@ -10041,6 +10124,7 @@ var init_profiles = __esm({
           quiet: options.quiet ?? false,
           replication,
           replicationDebug: options.replicationDebug === true || process.env.TC_REPLICATION_DEBUG === "1",
+          ...profileConfig === void 0 ? {} : { posture: resolveProfilePosture(profileConfig) },
           ...localDiscovery === void 0 ? {} : { localDiscovery }
         };
       }
@@ -15794,7 +15878,7 @@ async function refusal(response) {
 async function prepareLinkRecord(input) {
   const apiOrigin2 = checkApiOrigin(input.apiOrigin);
   const nowMs = toEpochMs(input.now);
-  const expiresMs = input.expiresAt.getTime();
+  const expiresMs = Math.floor(input.expiresAt.getTime() / 1e3) * 1e3;
   if (!Number.isFinite(nowMs) || !Number.isFinite(expiresMs)) throw new LinkError("invalid_argument", "now and expiresAt must be valid dates");
   let blob;
   let key;
@@ -29060,12 +29144,12 @@ async function verifyEnvelopeV3(envelope, options) {
   const nativeProjection2 = sortedCapabilities.map((capability) => capability.kind === "encryption" ? { service: "tinycloud.encryption", space: capability.resource, path: capability.resource, actions: [capability.action] } : { service: "tinycloud.kv", space: capability.resource.slice(0, capability.resource.indexOf("/kv/")), path: capability.resource.split("/kv/")[1], actions: [...capability.actions], caveat: { type: "xyz.tinycloud.resource/selector", kind: capability.selector, value: capability.resource } }).sort((left, right) => canonicalize2(left).localeCompare(canonicalize2(right)));
   const nativeProjectionHashHex = hex(sha2562(new TextEncoder().encode(`${NATIVE_PROJECTION_V1_DOMAIN}${canonicalize2(nativeProjection2)}`)));
   const expectedAttenuation = Object.fromEntries(sortedCapabilities.map((capability) => capability.kind === "encryption" ? [capability.resource, { [capability.action]: [{}] }] : [capability.resource, Object.fromEntries(capability.actions.map((action) => [action, [{ kind: capability.selector, type: "xyz.tinycloud.resource/selector", value: capability.resource }]]))]));
-  const kv = policy.capabilityCeiling.find((capability) => capability.kind === "kv");
+  const kv2 = policy.capabilityCeiling.find((capability) => capability.kind === "kv");
   const expectedKvActions = parsed.actions.flatMap((action) => action === "read" ? ["tinycloud.kv/get", "tinycloud.kv/metadata"] : action === "list" ? ["tinycloud.kv/list"] : ["tinycloud.kv/put"]);
   const marker = parsed.contentSource.kvResource.indexOf("/kv/");
   const resourceSpace = marker < 1 ? "" : parsed.contentSource.kvResource.slice(0, marker);
   const resourcePath = marker < 1 ? "" : parsed.contentSource.kvResource.slice(marker + 4);
-  if (parsed.shareId !== parsed.contentSource.shareId || resourceSpace !== parsed.target.spaceId || resourcePath !== parsed.resource.path.replace(/\/$/, "") || parsed.resource.kind !== parsed.contentSource.selector || kv?.kind !== "kv" || expectedKvActions.some((action) => !kv.actions.includes(action)) || parsed.encryptionNetwork !== parsed.contentSource.encryptionNetwork || parsed.contentSource.keyVersion <= 0 || policy.expiresAt !== void 0 && Date.parse(parsed.expiry) > Date.parse(policy.expiresAt)) return false;
+  if (parsed.shareId !== parsed.contentSource.shareId || resourceSpace !== parsed.target.spaceId || resourcePath !== parsed.resource.path.replace(/\/$/, "") || parsed.resource.kind !== parsed.contentSource.selector || kv2?.kind !== "kv" || expectedKvActions.some((action) => !kv2.actions.includes(action)) || parsed.encryptionNetwork !== parsed.contentSource.encryptionNetwork || parsed.contentSource.keyVersion <= 0 || policy.expiresAt !== void 0 && Date.parse(parsed.expiry) > Date.parse(policy.expiresAt)) return false;
   const binding = parsed.attestedEnforcerBinding;
   const { signature: bindingSignature, ...unsignedBinding } = binding;
   const expectedBindingDigestHex = hex(sha2562(new TextEncoder().encode(canonicalize2({ enforcerDid: binding.enforcerDid, nodeAudience: binding.nodeAudience }))));
@@ -32441,10 +32525,10 @@ function hasKvAction(permission, action) {
   return permission.actions.some((entry) => entry === action || entry === `tinycloud.kv/${action}`);
 }
 function readTarget(permissions) {
-  const kv = (permissions ?? []).filter((permission) => permission.service === "tinycloud.kv" || permission.service === "kv");
-  const list = kv.find((permission) => hasKvAction(permission, "list"));
+  const kv2 = (permissions ?? []).filter((permission) => permission.service === "tinycloud.kv" || permission.service === "kv");
+  const list = kv2.find((permission) => hasKvAction(permission, "list"));
   if (list) return { op: "list", prefix: list.path };
-  const get = kv.find((permission) => hasKvAction(permission, "get"));
+  const get = kv2.find((permission) => hasKvAction(permission, "get"));
   if (!get) return void 0;
   return { op: "get", key: get.path === "" || get.path.endsWith("/") ? `${get.path}.tinycloud-space-probe` : get.path };
 }
@@ -32456,8 +32540,8 @@ function kvSpaceProbe(ctx, permissions, restore2 = restoreProfileSessionNode) {
     if (!target) return "unreadable";
     restored ??= await restore2(ctx);
     if ("unavailable" in restored) return "unreadable";
-    const kv = restored.node.kv;
-    const result = target.op === "list" ? await kv.list({ prefix: target.prefix, limit: 1 }) : await kv.get(target.key);
+    const kv2 = restored.node.kv;
+    const result = target.op === "list" ? await kv2.list({ prefix: target.prefix, limit: 1 }) : await kv2.get(target.key);
     if (result.ok) return "hosted";
     const status = result.error.meta?.status;
     if (status === 404 && UNHOSTED.test(result.error.message)) return "unhosted";
@@ -33002,7 +33086,8 @@ async function revokeDelegationOnNode(params) {
         throw new CLIError(
           "RAW_RECAP_RESOURCE_UNSUPPORTED",
           `Cannot revoke "${cid}": this CLI profile has no record of this grant and the node's record does not match the signed-in owner.`,
-          ExitCode.PERMISSION_DENIED
+          ExitCode.PERMISSION_DENIED,
+          profile.authMethod === "openkey" ? { hint: "This permission can't be revoked from the CLI yet. Revoke it at https://account.tinycloud.xyz/delegations." } : void 0
         );
       }
       fallbackSpaceId = fallback.space;
@@ -33827,7 +33912,7 @@ async function prepareProfileRemoteLogout(ctx, expectedSessionCid, discardLocalC
       "REVOCATION_AUTHORITY_UNAVAILABLE",
       "OpenKey owner CID revocation requires a verified signed revoke-control grant or wallet proof. No CID was revoked; session, key and replica files remain for retry, while local replica reads stay denied.",
       ExitCode.AUTH_REQUIRED,
-      { hint: "Obtain verified owner revoke authority before retrying `auth logout --revoke`, or use plain `auth logout` to end this local session without node revocation." }
+      { hint: `This sign-in can't be revoked from the CLI yet. Revoke it at https://account.tinycloud.xyz/delegations. To sign out on this computer only, run \`${CLI_NAME18} auth logout\`.` }
     );
   }
   const signerDid = addressToDID(
@@ -35986,7 +36071,7 @@ async function refreshOpenKeySession(profileName2, host, options = {}) {
     // owner is verified below.
     permissions: permissions ?? ownerLoginPermissions(expectedOwner),
     expiry: openKeyExpiry,
-    ...permissions ? { reason: "Allow this TinyCloud CLI profile to use the permissions in the requested manifest." } : {}
+    ...permissions ? { reason: options.reason ?? "Allow this TinyCloud CLI profile to use the permissions in the requested manifest." } : {}
   });
   let sanitizedSession;
   let verifiedOwner;
@@ -36254,6 +36339,52 @@ function listedDelegation(d) {
     resources
   };
 }
+var ISSUED_ORDER_NOTE = "Sorted by delegation ID, not by date.";
+function issuedFailure(error, host) {
+  if (error.code === "UNSUPPORTED_OPERATION") {
+    return new CLIError(
+      "ISSUED_DELEGATIONS_UNAVAILABLE",
+      `${host} can't list the delegations you issued yet.`,
+      ExitCode.NODE_ERROR
+    );
+  }
+  if (error.code === "CHAIN_TOO_DEEP") {
+    return new CLIError(
+      "CHAIN_TOO_DEEP",
+      "The node can't check this delegation chain right now because it's too long. Try again later.",
+      ExitCode.NODE_ERROR,
+      { status: 503 }
+    );
+  }
+  if (error.code === "INVALID_CURSOR") {
+    return new CLIError(
+      "INVALID_CURSOR",
+      "The node couldn't continue the list. Run the command again.",
+      ExitCode.NODE_ERROR,
+      { status: 400 }
+    );
+  }
+  return cliErrorFromService(error);
+}
+async function revokeIssuedDelegation(node, ctx, cid) {
+  const result = await node.delegationManager.revokeIssued(cid);
+  if (result.ok) return { cid: result.data.cid, revoked: true };
+  if (result.error.code === "PERMISSION_DENIED") {
+    throw new CLIError(
+      "REVOKE_UNAUTHORIZED",
+      `The node refused this revocation: ${result.error.message}.`,
+      ExitCode.PERMISSION_DENIED,
+      {
+        status: result.error.meta?.status,
+        hint: `A profile can revoke only the delegations its own key issued. See them with \`${CLI_NAME21} --profile ${ctx.profile} delegation list --granted\`.`
+      }
+    );
+  }
+  if (result.error.code === "NOT_FOUND") {
+    throw new CLIError("TARGET_NOT_FOUND", `The node has no delegation "${cid}".`, ExitCode.NOT_FOUND);
+  }
+  throw issuedFailure(result.error, ctx.host);
+}
 async function confirmCurrentSessionRevoke(yes) {
   if (yes) return;
   const warning = "This is your current sign-in session; revoking it signs you out";
@@ -36342,6 +36473,16 @@ function registerDelegationCommand(program, configuration = {}) {
       if (options.granted && options.received) {
         throw new CLIError("USAGE_ERROR", "Use only one of --granted or --received.", ExitCode.USAGE_ERROR);
       }
+      if (options.granted && ctx.posture === "delegate-session" && node.address === void 0) {
+        const issued = await node.delegationManager.queryAllIssued({ space: options.space });
+        if (!issued.ok) throw issuedFailure(issued.error, ctx.host);
+        outputJson({
+          delegations: issued.data.map(listedDelegation),
+          count: issued.data.length,
+          note: ISSUED_ORDER_NOTE
+        });
+        return;
+      }
       const delegations = await queryDelegations(node, {
         direction: options.granted ? "granted" : options.received ? "received" : "all",
         space: options.space
@@ -36372,11 +36513,16 @@ function registerDelegationCommand(program, configuration = {}) {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
+      const delegateCandidate = ctx.posture === "delegate-session" ? await ensureAuthenticated(ctx) : void 0;
+      if (delegateCandidate !== void 0 && delegateCandidate.address === void 0) {
+        outputJson(await revokeIssuedDelegation(delegateCandidate, ctx, cid));
+        return;
+      }
       const session = await ProfileManager.getSession(ctx.profile);
       const currentSession = session && "delegationCid" in session && session.delegationCid === cid;
       if (currentSession) await confirmCurrentSessionRevoke(options.yes === true);
       const prepared = currentSession ? await prepareProfileRemoteLogout(ctx, cid) : void 0;
-      const node = prepared?.node ?? await ensureAuthenticated(ctx);
+      const node = prepared?.node ?? delegateCandidate ?? await ensureAuthenticated(ctx);
       const profile = prepared?.profile ?? await ProfileManager.getProfile(ctx.profile);
       const revoked = await revokeDelegationOnNode({
         ctx,
@@ -37008,7 +37154,7 @@ Examples:
     }
   });
 }
-function appsInstallIo(kv, db) {
+function appsInstallIo(kv2, db) {
   return {
     async fetchBytes(url) {
       const response = await fetch(url, { redirect: "error" });
@@ -37016,7 +37162,7 @@ function appsInstallIo(kv, db) {
       return new Uint8Array(await response.arrayBuffer());
     },
     async kvGet(key) {
-      const result = await kv.get(key, { binary: true });
+      const result = await kv2.get(key, { binary: true });
       if (result.ok) {
         const bytes = result.data.data;
         if (bytes instanceof Uint8Array) return bytes;
@@ -37026,7 +37172,7 @@ function appsInstallIo(kv, db) {
       throw new Error(result.error.code ?? "KV_GET_FAILED");
     },
     async kvCreate(key, bytes) {
-      const result = await kv.put(key, bytes, { ifNoneMatch: "*" });
+      const result = await kv2.put(key, bytes, { ifNoneMatch: "*" });
       if (result.ok) return "created";
       if (result.error.code === "KV_PRECONDITION_FAILED") return "exists";
       throw new Error(result.error.code ?? "KV_PUT_FAILED");
@@ -37079,6 +37225,25 @@ init_formatter();
 init_errors();
 init_constants();
 import { CLI_NAME as CLI_NAME25 } from "@tinycloud/operations/cli-name";
+async function createKeyOnlyProfile(profileName2, host, defaultSpace) {
+  await ProfileManager.ensureConfigDir();
+  const { jwk, did } = await generateKey2();
+  await ProfileManager.setKey(profileName2, jwk);
+  await ProfileManager.setProfile(profileName2, {
+    name: profileName2,
+    host,
+    chainId: DEFAULT_CHAIN_ID,
+    spaceName: "default",
+    did,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...defaultSpace ? { defaultSpace } : {}
+  });
+  const config = await ProfileManager.getConfig();
+  if (profileName2 === "default" || !await ProfileManager.profileExists(config.defaultProfile)) {
+    await ProfileManager.setConfig({ ...config, defaultProfile: profileName2 });
+  }
+  return { did };
+}
 function registerInitCommand(program) {
   program.command("init").description("Initialize a new TinyCloud profile").option("--name <profile>", "Profile name", "default").option("--key-only", "Only generate key, skip authentication").option("--host <url>", "TinyCloud node URL").option("--paste", "Use manual paste mode for authentication").option("--no-popup", "Print the OpenKey URL without opening a browser").option("--default-space <name>", "Default space used when --space is omitted (e.g. applications)").action(async (options, cmd) => {
     try {
@@ -37100,25 +37265,7 @@ function registerInitCommand(program) {
           ExitCode.ERROR
         );
       }
-      await ProfileManager.ensureConfigDir();
-      const { jwk, did } = await withSpinner("Generating key...", async () => {
-        return generateKey2();
-      });
-      await ProfileManager.setKey(profileName2, jwk);
-      const profileConfig = {
-        name: profileName2,
-        host,
-        chainId: DEFAULT_CHAIN_ID,
-        spaceName: "default",
-        did,
-        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-        ...defaultSpace ? { defaultSpace } : {}
-      };
-      await ProfileManager.setProfile(profileName2, profileConfig);
-      const config = await ProfileManager.getConfig();
-      if (profileName2 === "default" || !await ProfileManager.profileExists(config.defaultProfile)) {
-        await ProfileManager.setConfig({ ...config, defaultProfile: profileName2 });
-      }
+      const { did } = await withSpinner("Generating key...", () => createKeyOnlyProfile(profileName2, host, defaultSpace));
       if (options.keyOnly) {
         outputJson({
           profile: profileName2,
@@ -37393,25 +37540,25 @@ async function readStdin2() {
 }
 async function kvHandle(node, spaceInput, profileName2) {
   const spaceUri = await resolveSpaceUri(spaceInput, profileName2);
-  const kv = spaceUri ? node.kvForSpace(spaceUri) : node.kv;
-  return { kv, spaceUri };
+  const kv2 = spaceUri ? node.kvForSpace(spaceUri) : node.kv;
+  return { kv: kv2, spaceUri };
 }
 function retryFields(retry) {
   return retry ? { attempts: retry.attempts, backoffMs: retry.backoffMs } : {};
 }
 function registerKvCommand(program) {
-  const kv = program.command("kv").description("Key-value store operations");
-  kv.command("get <key>").description("Get a value by key").option("--raw", "Output raw value (no JSON wrapping)").option("-o, --output <file>", "Write value to file").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
+  const kv2 = program.command("kv").description("Key-value store operations");
+  kv2.command("get <key>").description("Get a value by key").option("--raw", "Output raw value (no JSON wrapping)").option("-o, --output <file>", "Write value to file").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
     try {
       assertAddressableKey(key);
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const { kv: kv3, spaceUri } = await kvHandle(node, options.space, ctx.profile);
       const wantBytes = !!options.output || !!options.raw;
       const result = await withSpinner(
         `Getting ${key}...`,
-        () => kv2.get(key, wantBytes ? { binary: true } : void 0)
+        () => kv3.get(key, wantBytes ? { binary: true } : void 0)
       );
       if (!result.ok) {
         const hosted = await unhostedSpaceError(result.error, spaceUri, ctx.profile);
@@ -37447,7 +37594,7 @@ function registerKvCommand(program) {
       return handleError(error);
     }
   });
-  kv.command("put <key> [value]").description("Set a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--if-none-match <value>", "`--if-none-match '*'`: Write only if the key doesn't exist yet; never overwrite").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, value, options, cmd) => {
+  kv2.command("put <key> [value]").description("Set a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--if-none-match <value>", "`--if-none-match '*'`: Write only if the key doesn't exist yet; never overwrite").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, value, options, cmd) => {
     try {
       assertAddressableKey(key);
       if (options.ifNoneMatch !== void 0 && options.ifNoneMatch !== "*") {
@@ -37475,8 +37622,8 @@ function registerKvCommand(program) {
           putValue = value;
         }
       }
-      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
-      const result = await withSpinner(`Writing ${key}...`, () => kv2.put(
+      const { kv: kv3, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const result = await withSpinner(`Writing ${key}...`, () => kv3.put(
         key,
         putValue,
         options.ifNoneMatch === "*" ? { ifNoneMatch: "*" } : void 0
@@ -37492,14 +37639,14 @@ function registerKvCommand(program) {
       return handleError(error);
     }
   });
-  kv.command("delete <key>").description("Delete a key").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
+  kv2.command("delete <key>").description("Delete a key").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
     try {
       assertAddressableKey(key);
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
-      const result = await withSpinner(`Deleting ${key}...`, () => kv2.delete(key));
+      const { kv: kv3, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const result = await withSpinner(`Deleting ${key}...`, () => kv3.delete(key));
       if (!result.ok) {
         await throwKvError(result.error, spaceUri, ctx.profile);
       }
@@ -37508,7 +37655,7 @@ function registerKvCommand(program) {
       return handleError(error);
     }
   });
-  kv.command("list").description("List keys").option("--prefix <prefix>", "Filter by key prefix").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("--limit <n>", "Keys per page, 1-1000 (the node's default otherwise)").option("--cursor <cursor>", "Continue from a previous page's nextCursor").option("--all", "Follow nextCursor until the listing is complete").action(async (options, cmd) => {
+  kv2.command("list").description("List keys").option("--prefix <prefix>", "Filter by key prefix").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("--limit <n>", "Keys per page, 1-1000 (the node's default otherwise)").option("--cursor <cursor>", "Continue from a previous page's nextCursor").option("--all", "Follow nextCursor until the listing is complete").action(async (options, cmd) => {
     try {
       if (options.prefix) assertAddressableKey(options.prefix);
       const limit = options.limit === void 0 ? void 0 : Number(options.limit);
@@ -37518,13 +37665,13 @@ function registerKvCommand(program) {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const { kv: kv3, spaceUri } = await kvHandle(node, options.space, ctx.profile);
       const keyList = [];
       let cursor = options.cursor;
       let truncated;
       const seenCursors = /* @__PURE__ */ new Set();
       for (; ; ) {
-        const result = await withSpinner("Listing keys...", () => kv2.list({
+        const result = await withSpinner("Listing keys...", () => kv3.list({
           ...options.prefix ? { prefix: options.prefix } : {},
           ...limit === void 0 ? {} : { limit },
           ...cursor === void 0 ? {} : { cursor }
@@ -37579,14 +37726,14 @@ function registerKvCommand(program) {
       return handleError(error);
     }
   });
-  kv.command("head <key>").description("Get metadata for a key (no body)").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
+  kv2.command("head <key>").description("Get metadata for a key (no body)").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
     try {
       assertAddressableKey(key);
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
-      const result = await withSpinner(`Checking ${key}...`, () => kv2.head(key));
+      const { kv: kv3, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const result = await withSpinner(`Checking ${key}...`, () => kv3.head(key));
       if (!result.ok) {
         const hosted = await unhostedSpaceError(result.error, spaceUri, ctx.profile);
         if (hosted) throw hosted;
@@ -37988,12 +38135,129 @@ function registerNodeCommand(program) {
   });
 }
 
+// src/commands/onboard.ts
+import { CLI_NAME as CLI_NAME29 } from "@tinycloud/operations/cli-name";
+init_constants();
+init_profiles();
+init_types();
+init_permissions();
+init_sdk();
+init_errors();
+init_formatter();
+var ONBOARD_EXPIRY = "30d";
+var kv = (actions) => actions.map((action) => `tinycloud.kv/${action}`);
+var ONBOARD_STEPS = [
+  {
+    space: "applications",
+    asks: "Read and change your apps' data for 30 days.",
+    permissions: [{ service: "tinycloud.kv", space: "applications", path: "", actions: kv(["get", "list", "put", "del", "metadata"]) }]
+  },
+  {
+    space: "account",
+    asks: "See which spaces and apps you have, read-only, for 30 days.",
+    permissions: [
+      { service: "tinycloud.kv", space: "account", path: "spaces/", actions: kv(["get", "list"]) },
+      { service: "tinycloud.kv", space: "account", path: "applications/", actions: kv(["get", "list"]) }
+    ]
+  }
+];
+var ApprovalNeeded = class extends Error {
+  constructor(approvalUrl) {
+    super("approval needed");
+    this.approvalUrl = approvalUrl;
+  }
+};
+function registerOnboardCommand(program) {
+  program.command("onboard").description(`Set up this computer to act for its owner: a profile, the owner's OpenKey sign-in (or new account), and a starting grant for 30 days (read and change the applications space; read which spaces and apps exist). Each run does the next approval: it prints the approval link and exits ${ExitCode.PENDING}; run it again with the code OpenKey shows. Exits 0 when onboarding is complete.`).option("--code <code>", "The code OpenKey showed after the owner approved the last link").action(async (options, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext(globalOpts, { storedSession: "unused" });
+      if (!await ProfileManager.profileExists(ctx.profile)) await createKeyOnlyProfile(ctx.profile, ctx.host);
+      let profile = await ProfileManager.getProfile(ctx.profile);
+      if (resolveProfilePosture(profile) !== "owner-openkey") {
+        throw new CLIError(
+          "PROFILE_NOT_ONBOARDABLE",
+          `Profile "${ctx.profile}" doesn't sign in with OpenKey, so onboarding can't use it. Run \`${CLI_NAME29} --profile <new name> onboard\` instead.`,
+          ExitCode.USAGE_ERROR
+        );
+      }
+      let code5 = typeof options.code === "string" && options.code.trim() !== "" ? options.code.trim() : void 0;
+      const acquire = async (did, flow = {}) => {
+        if (code5 === void 0) throw new ApprovalNeeded(buildAuthUrl(did, flow));
+        const pasted = code5;
+        code5 = void 0;
+        return delegationFromInput(pasted, did, flow);
+      };
+      for (const [index, step] of ONBOARD_STEPS.entries()) {
+        const reason = `TinyCloud onboarding, step ${index + 1} of ${ONBOARD_STEPS.length}: ${step.asks}`;
+        try {
+          const session2 = await ProfileManager.getSession(ctx.profile);
+          if (!sessionStateIsUsable(storedSessionState(session2, profile).state)) {
+            const { delegationData } = await refreshOpenKeySession(ctx.profile, ctx.host, {
+              permissions: step.permissions,
+              expiry: ONBOARD_EXPIRY,
+              reason,
+              persistHost: globalOpts.host !== void 0,
+              openKeyAcquisition: acquire
+            });
+            await ensureSpaceSetup({ profile: ctx.profile, host: ctx.host }, delegationData, delegationData.permissions);
+            profile = await ProfileManager.getProfile(ctx.profile);
+            continue;
+          }
+          await ensureDelegationAuthority({
+            ctx,
+            profile,
+            node: await ensureAuthenticated(ctx),
+            requested: await resolvePermissionSpaces(step.permissions, ctx.profile),
+            expiryOption: ONBOARD_EXPIRY,
+            reason,
+            yes: true,
+            openKeyAcquisition: acquire
+          });
+        } catch (error) {
+          if (!(error instanceof ApprovalNeeded)) throw error;
+          const next = `${CLI_NAME29} --profile ${ctx.profile} onboard --code <code>`;
+          output({
+            onboarded: false,
+            profile: ctx.profile,
+            step: index + 1,
+            steps: ONBOARD_STEPS.length,
+            asks: step.asks,
+            approvalUrl: error.approvalUrl,
+            next
+          }, () => [
+            `Step ${index + 1} of ${ONBOARD_STEPS.length}: ${step.asks}`,
+            `Open this link, sign in or create an account, and approve:`,
+            `  ${error.approvalUrl}`,
+            `Then run: ${next}`
+          ].join("\n"));
+          process.exitCode = ExitCode.PENDING;
+          return;
+        }
+      }
+      profile = await ProfileManager.getProfile(ctx.profile);
+      const session = await ProfileManager.getSession(ctx.profile);
+      output({
+        onboarded: true,
+        profile: ctx.profile,
+        ownerDid: profile.ownerDid ?? null,
+        host: ctx.host,
+        granted: ONBOARD_STEPS.map(({ space, asks }) => ({ space, asks })),
+        expiresAt: storedSessionState(session, profile).expiresAt
+      }, () => `Onboarded: profile ${ctx.profile} acts for ${profile.ownerDid ?? "the owner"}.
+${ONBOARD_STEPS.map(({ asks }) => `  ${asks}`).join("\n")}`);
+    } catch (error) {
+      return handleError(error);
+    }
+  });
+}
+
 // src/commands/profile.ts
 init_profiles();
 init_formatter();
 init_errors();
 init_constants();
-import { CLI_NAME as CLI_NAME29 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME30 } from "@tinycloud/operations/cli-name";
 import { createInterface as createInterface5 } from "readline";
 init_theme();
 init_types();
@@ -38139,9 +38403,9 @@ profile at command time. Precedence for every kv/sql command:
   explicit --space flag  >  profile defaultSpace  >  primary space.
 
 Examples:
-  $ ${CLI_NAME29} profile set-default-space applications
-  $ ${CLI_NAME29} profile set-default-space applications --profile cli-test
-  $ ${CLI_NAME29} profile set-default-space --unset
+  $ ${CLI_NAME30} profile set-default-space applications
+  $ ${CLI_NAME30} profile set-default-space applications --profile cli-test
+  $ ${CLI_NAME30} profile set-default-space --unset
 `).action(async (name, options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -38153,7 +38417,7 @@ Examples:
       if (!options.unset && (name === void 0 || name === "")) {
         throw new CLIError(
           "USAGE_ERROR",
-          `Provide a space name (e.g. \`${CLI_NAME29} profile set-default-space applications\`) or pass --unset.`,
+          `Provide a space name (e.g. \`${CLI_NAME30} profile set-default-space applications\`) or pass --unset.`,
           ExitCode.USAGE_ERROR
         );
       }
@@ -38212,7 +38476,7 @@ function parseOperatorType(raw) {
 
 // src/commands/replica.ts
 init_profile_replicas();
-import { CLI_NAME as CLI_NAME30 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME31 } from "@tinycloud/operations/cli-name";
 import { randomBytes as randomBytes7 } from "crypto";
 import { constants as fsConstants5 } from "fs";
 import { mkdir as mkdir5, open as open11, readdir as readdir6, rename as rename4, unlink as unlink5, lstat as lstat9 } from "fs/promises";
@@ -38353,11 +38617,11 @@ var EXIT_BY_CODE = {
 var READ_FAILURE = {
   absent: { code: "KEY_ABSENT", exit: ExitCode.NOT_FOUND, what: "is not in the replica (the replica covers its whole prefix)" },
   deleted: { code: "KEY_DELETED", exit: ExitCode.NOT_FOUND, what: "was deleted at the source" },
-  content_missing: { code: "CONTENT_MISSING", exit: ExitCode.NOT_FOUND, what: `is known but its content has not been fetched yet; run ${CLI_NAME30} replica sync` },
+  content_missing: { code: "CONTENT_MISSING", exit: ExitCode.NOT_FOUND, what: `is known but its content has not been fetched yet; run ${CLI_NAME31} replica sync` },
   coverage_incomplete: {
     code: "COVERAGE_INCOMPLETE",
     exit: ExitCode.NOT_FOUND,
-    what: `is not in the replica, which has not finished its first sync; run ${CLI_NAME30} replica sync`
+    what: `is not in the replica, which has not finished its first sync; run ${CLI_NAME31} replica sync`
   },
   not_covered: { code: "NOT_COVERED", exit: ExitCode.USAGE_ERROR, what: "is outside the replica's prefix" }
 };
@@ -38475,7 +38739,7 @@ async function existingReplicaName(profile, option) {
   const names = await replicaNames(profile);
   if (names.length === 1) return names[0];
   if (names.length === 0) {
-    throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, `Profile "${profile}" has no replicas. Create one with: ${CLI_NAME30} replica sync --prefix <prefix>`);
+    throw new ReplicaError(ReplicaErrorCode.NOT_FOUND, `Profile "${profile}" has no replicas. Create one with: ${CLI_NAME31} replica sync --prefix <prefix>`);
   }
   throw new CLIError("USAGE_ERROR", `Profile "${profile}" has several replicas (${names.join(", ")}); pass --replica <name>.`, ExitCode.USAGE_ERROR);
 }
@@ -38583,9 +38847,9 @@ async function storedGrants(profile) {
 function grantHint(space, prefix) {
   return [
     "A replica needs a device grant with get and sync on its prefix:",
-    `  device: ${CLI_NAME30} auth request --cap tinycloud.kv:${space}:${prefix}:get,list,metadata,sync --expiry 30d --emit req.json`,
-    `  owner:  ${CLI_NAME30} auth grant req.json > grant.json`,
-    `  device: ${CLI_NAME30} auth import grant.json`
+    `  device: ${CLI_NAME31} auth request --cap tinycloud.kv:${space}:${prefix}:get,list,metadata,sync --expiry 30d --emit req.json`,
+    `  owner:  ${CLI_NAME31} auth grant req.json > grant.json`,
+    `  device: ${CLI_NAME31} auth import grant.json`
   ].join("\n");
 }
 function resolveSpace(input, prefix, grants) {
@@ -38641,9 +38905,9 @@ async function grantTransports(input) {
       fetch: globalThis.fetch.bind(globalThis),
       hosts: [input.host]
     });
-    const kv = new KVService({});
-    kv.initialize(context);
-    context.registerService("kv", kv);
+    const kv2 = new KVService({});
+    kv2.initialize(context);
+    context.registerService("kv", kv2);
     context.setSession({
       delegationHeader: { Authorization: new TextDecoder().decode(grant.bytes) },
       delegationCid: grant.cid,
@@ -38651,7 +38915,7 @@ async function grantTransports(input) {
       verificationMethod: input.deviceDid,
       jwk: input.jwk
     });
-    const client = kv;
+    const client = kv2;
     return kvSyncTransport(client);
   };
 }
@@ -38676,7 +38940,7 @@ function describeStatus(status) {
     formatField("Size", formatBytes(status.bytes)),
     formatField("Grant", status.device.delegationCid),
     formatField("Last error", status.lastError ? `${status.lastError.code}: ${status.lastError.message}` : null),
-    formatField("Purge", status.purgePending ? `incomplete: content files remain; the next ${CLI_NAME30} replica command retries` : null)
+    formatField("Purge", status.purgePending ? `incomplete: content files remain; the next ${CLI_NAME31} replica command retries` : null)
   ].join("\n");
 }
 async function writeFileAtomic(path, bytes) {
@@ -38840,7 +39104,7 @@ or coverage incomplete; 5 grant expired, revoked or not yet valid; 6 network;
     (options, cmd) => run(async () => {
       const profile = await profileName(cmd);
       if (options.purge) {
-        throw new CLIError("REPORT_READ_ONLY", `Replica report is read-only. To remove a named local replica, run ${CLI_NAME30} replica reset --replica <name> --purge; flag-owned purge has no equivalent yet (TC-1309).`, ExitCode.USAGE_ERROR);
+        throw new CLIError("REPORT_READ_ONLY", `Replica report is read-only. To remove a named local replica, run ${CLI_NAME31} replica reset --replica <name> --purge; flag-owned purge has no equivalent yet (TC-1309).`, ExitCode.USAGE_ERROR);
       }
       if (options.clearPending) {
         throw new CLIError("REPORT_READ_ONLY", "Clearing pending replica writes has no equivalent yet; see TC-1309 for a safe replacement command.", ExitCode.USAGE_ERROR);
@@ -38942,7 +39206,7 @@ or coverage incomplete; 5 grant expired, revoked or not yet valid; 6 network;
               if (differs !== void 0) {
                 throw new ReplicaError(
                   ReplicaErrorCode.CONFIG_MISMATCH,
-                  `Replica ${name} already follows ${differs}. Use another --replica name, or ${CLI_NAME30} replica reset --replica ${name} --purge first.`
+                  `Replica ${name} already follows ${differs}. Use another --replica name, or ${CLI_NAME31} replica reset --replica ${name} --purge first.`
                 );
               }
             }
@@ -39107,10 +39371,10 @@ init_theme();
 init_errors();
 init_warnings();
 init_constants();
-import { CLI_NAME as CLI_NAME32 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME33 } from "@tinycloud/operations/cli-name";
 import { readFile as readFile14 } from "fs/promises";
 import { join as join17 } from "path";
-import { homedir, hostname, userInfo } from "os";
+import { constants as osConstants, homedir, hostname, userInfo } from "os";
 import { appSecretScope } from "@tinycloud/sdk-core";
 import { invokeOperation as invokeOperation3 } from "@tinycloud/operations";
 import { isLocalOwnerProfile as isLocalOwnerProfile4, ownerSessionLacksProof as ownerSessionLacksProof5 } from "@tinycloud/operations/profile";
@@ -39131,6 +39395,7 @@ import {
 } from "@tinycloud/operations/secret-capabilities";
 import { invokeSecretsGetWithLocalAuthorityRetry } from "@tinycloud/operations/cli-runtime";
 init_sdk();
+init_replication_registry();
 init_session_expired();
 init_space();
 
@@ -39196,14 +39461,14 @@ function runProbeChild(request, options = {}) {
   const args = options.argv ?? probeChildArgv(request);
   const budgetMs = options.budgetMs ?? ATTEMPT_BUDGET_MS;
   const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
-  const spawn2 = options.spawn ?? nodeSpawn;
+  const spawn3 = options.spawn ?? nodeSpawn;
   const signal = options.signal;
   return new Promise((resolve9) => {
     if (signal?.aborted) {
       resolve9({ kind: "cancelled" });
       return;
     }
-    const child = spawn2(command, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn3(command, args, { env: process.env, stdio: ["ignore", "pipe", "pipe"] });
     let outcome;
     let stdout = Buffer.alloc(0);
     let stderr = Buffer.alloc(0);
@@ -39315,10 +39580,79 @@ function parseStatusEnvelope(line) {
   return void 0;
 }
 
+// src/lib/run-command.ts
+import { execFileSync, spawn as spawn2 } from "child_process";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+var FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+var TERMINAL_SIGNALS = { SIGINT: true, SIGQUIT: true, SIGHUP: true };
+function psGroupArgs(pid) {
+  return ["-o", "pgid=", "-o", "tpgid=", "-p", String(pid)];
+}
+function parsePsGroups(output2) {
+  const columns = output2.trim().split(/\s+/);
+  if (columns.length !== 2) return void 0;
+  const group = Number(columns[0]);
+  const foreground = Number(columns[1]);
+  return Number.isSafeInteger(group) && Number.isSafeInteger(foreground) ? { group, foreground } : void 0;
+}
+function processGroups() {
+  try {
+    const stat8 = readFileSync2("/proc/self/stat", "utf8");
+    const fields = stat8.slice(stat8.lastIndexOf(")") + 2).split(" ");
+    return { group: Number(fields[2]), foreground: Number(fields[5]) };
+  } catch {
+  }
+  try {
+    const ps = existsSync("/bin/ps") ? "/bin/ps" : "/usr/bin/ps";
+    return parsePsGroups(execFileSync(ps, psGroupArgs(process.pid), {
+      env: {},
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2e3
+    }));
+  } catch {
+    return void 0;
+  }
+}
+function inTerminalForeground() {
+  const groups = processGroups();
+  return groups !== void 0 && groups.foreground > 0 && groups.group === groups.foreground;
+}
+function runCommand(argv, env) {
+  return new Promise((resolve9) => {
+    let child;
+    try {
+      child = spawn2(argv[0], argv.slice(1), { stdio: "inherit", env, shell: false });
+    } catch (error) {
+      const code5 = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+      resolve9({ kind: "not_started", ...code5 === void 0 ? {} : { errno: code5 } });
+      return;
+    }
+    const forward = (signal) => {
+      if (TERMINAL_SIGNALS[signal] && inTerminalForeground()) return;
+      child.kill(signal);
+    };
+    for (const signal of FORWARDED_SIGNALS) process.on(signal, forward);
+    const settle = (outcome) => {
+      for (const signal of FORWARDED_SIGNALS) process.off(signal, forward);
+      resolve9(outcome);
+    };
+    child.on("error", (error) => {
+      if (child.pid === void 0) settle({ kind: "not_started", ...error.code === void 0 ? {} : { errno: error.code } });
+    });
+    child.once("exit", (code5, signal) => {
+      settle(signal !== null ? { kind: "signaled", signal } : { kind: "exited", code: code5 ?? 1 });
+    });
+  });
+}
+
+// src/commands/secrets.ts
+init_safe_text();
+
 // src/lib/secrets-wait.ts
 init_constants();
 init_errors();
-import { CLI_NAME as CLI_NAME31 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME32 } from "@tinycloud/operations/cli-name";
 var WAIT_BACKOFF_MS = [3e3, 4500, 6750, 10125];
 var WAIT_STEADY_INTERVAL_MS = 15e3;
 var DEFAULT_WAIT_TIMEOUT = "5m";
@@ -39326,7 +39660,7 @@ var MAX_WAIT_TIMEOUT_MS = 9 * 6e4;
 var MAX_CONSECUTIVE_FAILURES = 5;
 var TIMEOUT_RE = /^(0|\d+s|\d+m)$/;
 var RETRYABLE_STATUS_ERRORS = { NODE_UNREACHABLE: true, NODE_ERROR: true };
-var EXPLICIT_KEY_HINT = `${CLI_NAME31} secrets wait never signs in, and an explicit private key has no stored session. Use a local profile signed in once with ${CLI_NAME31} --profile <profile> auth login --method local, without TC_PRIVATE_KEY.`;
+var EXPLICIT_KEY_HINT = `${CLI_NAME32} secrets wait never signs in, and an explicit private key has no stored session. Use a local profile signed in once with ${CLI_NAME32} --profile <profile> auth login --method local, without TC_PRIVATE_KEY.`;
 function abortableSleep(ms2, signal) {
   return new Promise((resolve9) => {
     if (signal.aborted) {
@@ -39362,7 +39696,7 @@ async function runSecretsWait(request, deps) {
   let step = 0;
   const cancelled = () => new CLIError(
     "CANCELLED",
-    `Interrupted: ${CLI_NAME31} secrets wait stopped before the secrets were ready.`,
+    `Interrupted: ${CLI_NAME32} secrets wait stopped before the secrets were ready.`,
     ExitCode.CANCELLED,
     progress === void 0 ? {} : { progress }
   );
@@ -39506,13 +39840,13 @@ function statusError(error, profile, warnings) {
   if (error.code === "AUTH_REQUIRED" || error.code === "SESSION_NOT_FOUND") {
     const recovery = recoveryOf(error, "sign_in");
     if (recovery !== void 0) {
-      const hint = recovery.command !== void 0 ? `Sign in once with: ${recovery.command}, then retry.` : `Sign in to profile "${profile}" once with ${CLI_NAME31} auth login, then retry.`;
+      const hint = recovery.command !== void 0 ? `Sign in once with: ${recovery.command}, then retry.` : `Sign in to profile "${profile}" once with ${CLI_NAME32} auth login, then retry.`;
       return new CLIError("AUTH_REQUIRED", error.message, ExitCode.AUTH_REQUIRED, { hint, recovery, ...extra });
     }
   }
   if (error.code === "PROFILE_MIGRATION_REQUIRED") {
     const recovery = recoveryOf(error, "complete_migration");
-    const hint = recovery?.command !== void 0 ? `Run ${recovery.command} once to finish this profile's one-time upgrade, then retry wait.` : `Run ${CLI_NAME31} auth caps once with profile "${profile}" to finish its one-time upgrade, then retry wait.`;
+    const hint = recovery?.command !== void 0 ? `Run ${recovery.command} once to finish this profile's one-time upgrade, then retry wait.` : `Run ${CLI_NAME32} auth caps once with profile "${profile}" to finish its one-time upgrade, then retry wait.`;
     return new CLIError("PROFILE_MIGRATION_REQUIRED", error.message, ExitCode.ERROR, {
       hint,
       ...recovery === void 0 ? {} : { recovery },
@@ -39704,11 +40038,11 @@ async function runSecretOperation(params) {
 }
 function secretPermissionReason(action, name) {
   const target = name ? ` secret "${name}"` : " secrets";
-  return `Allow \`${CLI_NAME32} secrets ${action}${name ? ` ${name}` : ""}\` to access${target} with the required TinyCloud permissions.`;
+  return `Allow \`${CLI_NAME33} secrets ${action}${name ? ` ${name}` : ""}\` to access${target} with the required TinyCloud permissions.`;
 }
 function assertOwnerApprovalPossible(profileName2, profile, action, name, missing = []) {
   if (profile.authMethod !== "openkey" || process.stdin.isTTY || process.stderr.isTTY) return;
-  const command = `${CLI_NAME32} secrets ${action === "del" ? "delete" : action}${name ? ` ${name}` : ""}`;
+  const command = `${CLI_NAME33} secrets ${action === "del" ? "delete" : action}${name ? ` ${name}` : ""}`;
   throw new CLIError(
     "PERMISSION_DENIED",
     action === "get" ? missing.length > 0 && missing.every((permission) => permission.service === "tinycloud.encryption" && Array.isArray(permission.actions) && permission.actions.length > 0 && permission.actions.every((capability) => capability === SECRET_DECRYPT_CAPABILITY)) ? `Profile "${profileName2}" lacks the scoped decrypt authority (${SECRET_DECRYPT_CAPABILITY}) needed to read secret "${name}", and requesting it needs an interactive browser approval.` : `Profile "${profileName2}" lacks a scoped read or decrypt grant needed to read secret "${name}", and requesting it needs an interactive browser approval.` : `Profile "${profileName2}" holds no grant for \`${command}\`, and requesting one needs an interactive browser approval.`,
@@ -39719,7 +40053,7 @@ function assertOwnerApprovalPossible(profileName2, profile, action, name, missin
   );
 }
 function scopedSecretLoginHint(profileName2) {
-  return `Have the owner approve a scoped login whose manifest names the secret: ${CLI_NAME32} --profile ${profileName2} auth login --method openkey --paste --manifest <manifest.json>. Pass the owner's code on stdin, newline-terminated.`;
+  return `Have the owner approve a scoped login whose manifest names the secret: ${CLI_NAME33} --profile ${profileName2} auth login --method openkey --paste --manifest <manifest.json>. Pass the owner's code on stdin, newline-terminated.`;
 }
 async function runSecretOperationAttempt(label, operation) {
   try {
@@ -39853,7 +40187,7 @@ ${message}`,
           "AUTH_REQUIRED",
           "Not signed in to TinyCloud.",
           ExitCode.AUTH_REQUIRED,
-          { hint: `Sign in with: ${CLI_NAME32} --profile ${result.context.profile} auth login` }
+          { hint: `Sign in with: ${CLI_NAME33} --profile ${result.context.profile} auth login` }
         );
       }
       if (result.error.code === "NODE_UNREACHABLE") {
@@ -40269,6 +40603,153 @@ function outputSecretDoctor(result) {
     process.stdout.write(theme.warn(`${failed} secrets check${failed > 1 ? "s" : ""} need attention.`) + "\n");
   }
 }
+async function resolveSecretReadTarget(ctx, name, options) {
+  const scopeOptions = resolveSecretScope(options);
+  const legacySpaceUri = await resolveSecretSpace(options.space, ctx.profile);
+  const resolved = resolveSecretPath2(name, scopeOptions);
+  return { name, scopeOptions, scope: resolved.scope, legacySpaceUri, secretPath: resolved.permissionPaths.vault };
+}
+async function readSecret(params) {
+  const { ctx, target, options } = params;
+  const { name } = target;
+  if (options.delegation) {
+    const delegated = await resolveDelegatedSecretSource(
+      options.delegation,
+      target.secretPath,
+      target.legacySpaceUri ?? SECRETS_SPACE2
+    );
+    const effectiveHost = params.host ?? delegated.delegation.host ?? ctx.host;
+    const delegatedCtx = { ...ctx, host: effectiveHost };
+    const local = effectiveLocal(await ProfileManager.getProfile(ctx.profile).catch(() => null), options);
+    const node = await ensureSecretsNode(delegatedCtx, options);
+    const value = await withSpinner(
+      `Getting secret ${name}...`,
+      () => readDelegatedSecretValue({
+        node,
+        delegation: delegated.delegation,
+        delegationCid: delegated.delegation.cid,
+        permissions: delegated.permissions,
+        secretPath: target.secretPath,
+        space: target.legacySpaceUri ?? SECRETS_SPACE2,
+        name,
+        ...target.scope === void 0 ? {} : { scope: target.scope },
+        local
+      })
+    );
+    return { value };
+  }
+  const privateKey = authOptions(options)?.privateKey;
+  const spaceUri = privateKey !== void 0 && options.space !== void 0 && !options.space.startsWith("tinycloud:") ? options.space : target.legacySpaceUri;
+  const result = await invokeCanonicalSecretGet({
+    ctx,
+    name,
+    ...target.scopeOptions?.scope === void 0 ? {} : { scope: target.scopeOptions.scope },
+    ...spaceUri === void 0 ? {} : { space: spaceUri },
+    options,
+    label: `Getting secret ${name}...`,
+    openKeyAcquisition: params.openKeyAcquisition
+  });
+  if (result.status !== "ok") {
+    try {
+      throwCanonicalSecretGetError(result, name);
+    } catch (error) {
+      throw withOperationWarnings(error, result.warnings);
+    }
+  }
+  return { value: result.output.value, warnings: result.warnings };
+}
+var ENV_VAR_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function argvAfterSeparator(cmd) {
+  let root = cmd;
+  while (root.parent) root = root.parent;
+  const raw = "rawArgs" in root ? root.rawArgs : void 0;
+  if (!Array.isArray(raw)) return void 0;
+  const args = raw.map(String);
+  const withValue = (flag) => root.options.some((option) => option.required && (option.long === flag || option.short === flag));
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--") return args.slice(index + 1);
+    if (arg.startsWith("--")) {
+      if (withValue(arg)) index += 1;
+      continue;
+    }
+    if (arg.length < 2 || !arg.startsWith("-")) continue;
+    for (let char = 1; char < arg.length; char += 1) {
+      const option = root.options.find((candidate) => candidate.short === `-${arg[char]}`);
+      if (option === void 0) break;
+      if (option.required) {
+        if (char === arg.length - 1) index += 1;
+        break;
+      }
+    }
+  }
+  return void 0;
+}
+function secretRunPlan(cmd, operands, maps) {
+  const usage3 = `${CLI_NAME33} secrets run NAME... [--map NAME=ENV_VAR] -- <command> [args...]`;
+  const after = argvAfterSeparator(cmd);
+  if (after === void 0 || after.length > operands.length) {
+    throw new CLIError("USAGE_ERROR", `Put the command after \`--\`: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const [program, ...args] = after;
+  if (program === void 0) {
+    throw new CLIError("USAGE_ERROR", `Add the command to run after \`--\`: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const exports = [];
+  for (const name of operands.slice(0, operands.length - after.length)) {
+    if (!ENV_VAR_RE.test(name)) {
+      throw new CLIError(
+        "USAGE_ERROR",
+        `${JSON.stringify(name)} can't be used as an environment variable name. Use \`--map ${name}=ENV_VAR\` to choose one.`,
+        ExitCode.USAGE_ERROR
+      );
+    }
+    exports.push({ name, variable: name });
+  }
+  for (const map of maps) {
+    const equals7 = map.indexOf("=");
+    const variable = map.slice(equals7 + 1);
+    if (equals7 <= 0 || !ENV_VAR_RE.test(variable)) {
+      throw new CLIError(
+        "USAGE_ERROR",
+        `Invalid \`--map ${JSON.stringify(map)}\`: use NAME=ENV_VAR, where ENV_VAR starts with a letter or _ and uses only letters, digits and _.`,
+        ExitCode.USAGE_ERROR
+      );
+    }
+    exports.push({ name: map.slice(0, equals7), variable });
+  }
+  if (exports.length === 0) {
+    throw new CLIError("USAGE_ERROR", `Name at least one secret: ${usage3}`, ExitCode.USAGE_ERROR);
+  }
+  const variables = /* @__PURE__ */ new Set();
+  for (const { variable } of exports) {
+    if (variables.has(variable)) {
+      throw new CLIError("USAGE_ERROR", `Two secrets are mapped to ${variable}. Give each its own variable.`, ExitCode.USAGE_ERROR);
+    }
+    variables.add(variable);
+  }
+  return { command: [program, ...args], exports };
+}
+var RERAISED_SIGNALS = {
+  SIGINT: true,
+  SIGTERM: true,
+  SIGHUP: true,
+  SIGKILL: true,
+  SIGALRM: true,
+  SIGUSR2: true
+};
+var TC_CREDENTIAL_VARIABLES = ["TC_PRIVATE_KEY"];
+function exitAsCommand(outcome, program) {
+  if (outcome.kind === "exited") return process.exit(outcome.code);
+  if (outcome.kind === "signaled") {
+    if (RERAISED_SIGNALS[outcome.signal]) process.kill(process.pid, outcome.signal);
+    return process.exit(128 + (osConstants.signals[outcome.signal] ?? 0));
+  }
+  const reason = outcome.errno === "ENOENT" ? "command not found" : outcome.errno === "EACCES" ? "permission denied" : `cannot run (${outcome.errno ?? "unknown error"})`;
+  process.stderr.write(`${CLI_NAME33} secrets run: ${safeInline(program)}: ${reason}
+`);
+  return process.exit(outcome.errno === "ENOENT" ? 127 : 126);
+}
 function registerSecretsCommand(program, openKeyAcquisition) {
   const secrets = program.command("secrets").description("Encrypted secrets management");
   const network = secrets.command("network").description("Manage the default secrets encryption network");
@@ -40330,7 +40811,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
           name: "Encryption network",
           ok: false,
           detail: `${networkName} not found`,
-          hint: `${CLI_NAME32} secrets network init ${networkName}`
+          hint: `${CLI_NAME33} secrets network init ${networkName}`
         }
       ];
       let secret;
@@ -40376,7 +40857,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
             name: "Secret access",
             ok: false,
             detail: notFound ? `${resolved.permissionPaths.vault} not found` : result.error.message,
-            hint: notFound ? local ? `${CLI_NAME32} secrets put ${resolved.name}${formatSecretScopeFlag(scopeOptions)} --stdin` : `${CLI_NAME32} secrets request ${resolved.name}${formatSecretScopeFlag(scopeOptions)}` : `Ask the owner profile to grant ${secretCapabilityAction("get")} and ${SECRET_DECRYPT_CAPABILITY}.`
+            hint: notFound ? local ? `${CLI_NAME33} secrets put ${resolved.name}${formatSecretScopeFlag(scopeOptions)} --stdin` : `${CLI_NAME33} secrets request ${resolved.name}${formatSecretScopeFlag(scopeOptions)}` : `Ask the owner profile to grant ${secretCapabilityAction("get")} and ${SECRET_DECRYPT_CAPABILITY}.`
           });
         }
       } else {
@@ -40436,66 +40917,23 @@ function registerSecretsCommand(program, openKeyAcquisition) {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
-      const scopeOptions = resolveSecretScope(options);
-      const legacySpaceUri = await resolveSecretSpace(options.space, ctx.profile);
-      const secretPath = resolveSecretPath2(name, scopeOptions).permissionPaths.vault;
+      const target = await resolveSecretReadTarget(ctx, name, options);
       if (options.output) await validatePrivateOutput(options.output, "Secret output");
+      const secret = await readSecret({ ctx, host: globalOpts.host, target, options, openKeyAcquisition });
+      const value = secret.value;
       if (options.delegation) {
-        const delegated = await resolveDelegatedSecretSource(
-          options.delegation,
-          secretPath,
-          legacySpaceUri ?? SECRETS_SPACE2
-        );
-        const effectiveHost = globalOpts.host ?? delegated.delegation.host ?? ctx.host;
-        const delegatedCtx = { ...ctx, host: effectiveHost };
-        const local = effectiveLocal(await ProfileManager.getProfile(ctx.profile).catch(() => null), options);
-        const scope = resolveSecretPath2(name, scopeOptions).scope;
-        const node = await ensureSecretsNode(delegatedCtx, options);
-        const value2 = await withSpinner(
-          `Getting secret ${name}...`,
-          () => readDelegatedSecretValue({
-            node,
-            delegation: delegated.delegation,
-            delegationCid: delegated.delegation.cid,
-            permissions: delegated.permissions,
-            secretPath,
-            space: legacySpaceUri ?? SECRETS_SPACE2,
-            name,
-            ...scope === void 0 ? {} : { scope },
-            local
-          })
-        );
         if (options.output) {
-          await writePrivateOutput(options.output, value2, "Secret output");
+          await writePrivateOutput(options.output, value, "Secret output");
           outputJson({ name, written: options.output });
           return;
         }
         if (options.raw) {
-          process.stdout.write(value2);
+          process.stdout.write(value);
           return;
         }
-        outputJson({ name, value: value2 });
+        outputJson({ name, value });
         return;
       }
-      const privateKey = authOptions(options)?.privateKey;
-      const spaceUri = privateKey !== void 0 && options.space !== void 0 && !options.space.startsWith("tinycloud:") ? options.space : legacySpaceUri;
-      const result = await invokeCanonicalSecretGet({
-        ctx,
-        name,
-        ...scopeOptions?.scope === void 0 ? {} : { scope: scopeOptions.scope },
-        ...spaceUri === void 0 ? {} : { space: spaceUri },
-        options,
-        label: `Getting secret ${name}...`,
-        openKeyAcquisition
-      });
-      if (result.status !== "ok") {
-        try {
-          throwCanonicalSecretGetError(result, name);
-        } catch (error) {
-          throw withOperationWarnings(error, result.warnings);
-        }
-      }
-      const value = result.output.value;
       try {
         if (options.output) {
           await writePrivateOutput(options.output, value, "Secret output");
@@ -40506,9 +40944,47 @@ function registerSecretsCommand(program, openKeyAcquisition) {
           outputJson({ name, value });
         }
       } catch (error) {
-        throw withOperationWarnings(error, result.warnings);
+        throw withOperationWarnings(error, secret.warnings);
       }
-      outputWarnings(operationWarnings(result.warnings));
+      outputWarnings(operationWarnings(secret.warnings));
+    } catch (error) {
+      return handleError(error);
+    }
+  });
+  secrets.command("run [names...]").description("Run a command with secrets in its environment").usage("[options] [names...] -- <command> [args...]").option(
+    "--map <NAME=ENV_VAR>",
+    "Give secret NAME to the command as environment variable ENV_VAR (repeatable)",
+    (value, previous) => [...previous ?? [], value]
+  ).option("--scope <scope>", "Logical secret scope").option("--space <name|uri>", "Target a non-default secrets space (short name or full URI)").option("--delegation <source>", "Delegation file path or imported profile name").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (operands, options, cmd) => {
+    try {
+      const plan = secretRunPlan(cmd, operands, options.map ?? []);
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext(globalOpts);
+      const targets = [];
+      for (const name of new Set(plan.exports.map((entry) => entry.name))) {
+        targets.push(await resolveSecretReadTarget(ctx, name, options));
+      }
+      const values = /* @__PURE__ */ new Map();
+      let warnings = [];
+      for (const target of targets) {
+        const secret = await readSecret({ ctx, host: globalOpts.host, target, options, openKeyAcquisition });
+        if (secret.value.includes("\0")) {
+          throw new CLIError(
+            "SECRET_NOT_EXPORTABLE",
+            `Secret "${target.name}" contains a NUL character, so it can't be put in an environment variable. The command wasn't started.`,
+            ExitCode.ERROR
+          );
+        }
+        values.set(target.name, secret.value);
+        warnings = mergeWarnings(warnings, secret.warnings ?? []);
+      }
+      outputWarnings(operationWarnings(warnings));
+      await closeReplication();
+      const env = { ...process.env };
+      for (const variable of TC_CREDENTIAL_VARIABLES) delete env[variable];
+      for (const entry of plan.exports) env[entry.variable] = values.get(entry.name);
+      values.clear();
+      exitAsCommand(await runCommand(plan.command, env), plan.command[0]);
     } catch (error) {
       return handleError(error);
     }
@@ -40620,7 +41096,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
       if (effectiveLocal(profile, options)) {
         throw new CLIError(
           "LOCAL_OWNER_PROFILE",
-          `Profile "${ctx.profile}" uses a local key, which owns its secrets: store them with ${CLI_NAME32} secrets put NAME --stdin instead of requesting them.`,
+          `Profile "${ctx.profile}" uses a local key, which owns its secrets: store them with ${CLI_NAME33} secrets put NAME --stdin instead of requesting them.`,
           ExitCode.USAGE_ERROR
         );
       }
@@ -40743,7 +41219,7 @@ function registerSecretsCommand(program, openKeyAcquisition) {
 
 // src/commands/share.ts
 import { Option } from "commander";
-import { CLI_NAME as CLI_NAME33 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME34 } from "@tinycloud/operations/cli-name";
 import { ProfileLockTimeoutError as ProfileLockTimeoutError3 } from "@tinycloud/operations/state";
 init_errors();
 
@@ -40970,7 +41446,7 @@ async function writeShareOutput(directory, filename, bytes, force) {
 init_profiles();
 
 // src/share/html-folder.ts
-import { constants as constants2, existsSync } from "fs";
+import { constants as constants2, existsSync as existsSync2 } from "fs";
 import { lstat as lstat11, open as open14, readdir as readdir7, realpath as realpath3, stat as stat7 } from "fs/promises";
 import { basename as basename5, dirname as dirname9, isAbsolute, join as join19, relative as relativePath, resolve as resolve7, sep as sep4 } from "path";
 
@@ -41908,7 +42384,7 @@ function isRaceError(error) {
 }
 var PROC_FD = "/proc/self/fd";
 async function linuxDescriptorPath(fd) {
-  if (process.platform !== "linux" || !existsSync(PROC_FD)) return void 0;
+  if (process.platform !== "linux" || !existsSync2(PROC_FD)) return void 0;
   return realpath3(`${PROC_FD}/${fd}`);
 }
 async function parentChainIsRealDirectories(root, path) {
@@ -42204,7 +42680,7 @@ function shareCliError(error, operation = "publish") {
       "SHARE_HISTORY_UNREADABLE",
       "sender history cannot be read with the current session key",
       1,
-      { hint: `Run \`${CLI_NAME33} share history recover\` to move the unreadable file aside. The old file is kept, not deleted.` }
+      { hint: `Run \`${CLI_NAME34} share history recover\` to move the unreadable file aside. The old file is kept, not deleted.` }
     );
   }
   if (error instanceof SharePublishAuthorityError) {
@@ -42212,12 +42688,12 @@ function shareCliError(error, operation = "publish") {
     const profileName2 = "profileName" in failure ? failure.profileName : void 0;
     const localKey = "localKey" in failure && failure.localKey === true;
     const profileHint = profileName2 === void 0 ? "" : `--profile ${profileName2} `;
-    const loginHint = localKey ? `\`${CLI_NAME33} ${profileHint}auth login --method local\`` : `\`${CLI_NAME33} ${profileHint}auth login --device --manifest builtin:share-publishing\` (or \`${CLI_NAME33} ${profileHint}enable share\`)`;
+    const loginHint = localKey ? `\`${CLI_NAME34} ${profileHint}auth login --method local\`` : `\`${CLI_NAME34} ${profileHint}auth login --device --manifest builtin:share-publishing\` (or \`${CLI_NAME34} ${profileHint}enable share\`)`;
     if (failure.kind === "caveated-session") {
       const holder = profileName2 === void 0 ? "this session" : `profile ${profileName2}'s session`;
       return new CLIError(
         "PERMISSION_DENIED",
-        `${holder} carries signed restrictions (caveats) on the authority an anyone-with-link share needs, so it cannot create the share link; nothing was shared. Approve Share publishing without restrictions on a new, dedicated profile (any unused name): \`${CLI_NAME33} init --name publisher --key-only && ${CLI_NAME33} --profile publisher enable share\``,
+        `${holder} carries signed restrictions (caveats) on the authority an anyone-with-link share needs, so it cannot create the share link; nothing was shared. Approve Share publishing without restrictions on a new, dedicated profile (any unused name): \`${CLI_NAME34} init --name publisher --key-only && ${CLI_NAME34} --profile publisher enable share\``,
         5
       );
     }
@@ -42318,7 +42794,7 @@ function shareCliError(error, operation = "publish") {
   if (nodeCode === "ENOENT") return new CLIError("INVALID_ARGUMENT", "share input was not found", 2);
   if (nodeCode === "EISDIR") return new CLIError("INVALID_ARGUMENT", "share input must be a Markdown file", 2);
   const mapped = typeof nodeCode === "string" && known[nodeCode] !== void 0 ? known[nodeCode] : known[message];
-  const classified = mapped === void 0 ? classifyShareFailure(error, `\`${CLI_NAME33} auth login\``) : void 0;
+  const classified = mapped === void 0 ? classifyShareFailure(error, `\`${CLI_NAME34} auth login\``) : void 0;
   if (classified !== void 0) return Object.assign(new CLIError(classified.code, classified.reason, classified.exitCode), { cause: error });
   if (error instanceof TypeError) return new CLIError("INVALID_ARGUMENT", "share input is invalid", 2);
   return new CLIError(mapped?.code ?? "INVALID_ARGUMENT", mapped ? mapped.code : "share operation failed", mapped?.exit ?? 2);
@@ -42728,7 +43204,7 @@ init_constants();
 init_sdk();
 init_host();
 init_theme();
-import { CLI_NAME as CLI_NAME34 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME35 } from "@tinycloud/operations/cli-name";
 import { ACCOUNT_REGISTRY_SPACE } from "@tinycloud/node-sdk";
 import { randomBytes as randomBytes9 } from "crypto";
 import { mkdir as mkdir7, writeFile as writeFile4 } from "fs/promises";
@@ -42775,7 +43251,7 @@ function registerSpaceCommand(program) {
       } else {
         const profile = await ProfileManager.getProfile(ctx.profile);
         const cap = "tinycloud.kv:account:spaces/:get,list";
-        const hint = resolveProfilePosture(profile) === "delegate-session" ? `Ask the space owner to grant it. Create the request with: ${CLI_NAME34} --profile ${ctx.profile} auth request --cap ${cap} --emit` : `Grant it to this session with: ${CLI_NAME34} --profile ${ctx.profile} auth request --grant --cap ${cap}. The default OpenKey owner sign-in covers only the default space, so it includes neither.`;
+        const hint = resolveProfilePosture(profile) === "delegate-session" ? `Ask the space owner to grant it. Create the request with: ${CLI_NAME35} --profile ${ctx.profile} auth request --cap ${cap} --emit` : `Grant it to this session with: ${CLI_NAME35} --profile ${ctx.profile} auth request --grant --cap ${cap}. The default OpenKey owner sign-in covers only the default space, so it includes neither.`;
         throw new CLIError(
           "PERMISSION_DENIED",
           `Listing spaces needs tinycloud.kv/get and tinycloud.kv/list on the account space's spaces/ registry (${accountSpaceId ?? ACCOUNT_REGISTRY_SPACE}), or tinycloud.space/list. This session holds neither.`,
@@ -42812,10 +43288,10 @@ function registerSpaceCommand(program) {
 
 A delegate cannot host a space \u2014 only its owner (root authority) can. This
 emits a tinycloud.host.request artifact naming the space and its owner so you
-can hand it to the owner; they run \`${CLI_NAME34} space host <name>\` and confirm.
+can hand it to the owner; they run \`${CLI_NAME35} space host <name>\` and confirm.
 
 If you ARE the owner of the resolved space, this refuses and tells you to host
-it directly with \`${CLI_NAME34} space host <name>\` (no request needed).
+it directly with \`${CLI_NAME35} space host <name>\` (no request needed).
 `).action(async (name, options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -42826,7 +43302,7 @@ it directly with \`${CLI_NAME34} space host <name>\` (no request needed).
       if (await isRootAuthority(spaceId, ctx.profile)) {
         throw new CLIError(
           "ALREADY_ROOT_AUTHORITY",
-          `You are the owner of ${spaceId}. Host it directly: ${CLI_NAME34} space host ${spaceName}`,
+          `You are the owner of ${spaceId}. Host it directly: ${CLI_NAME35} space host ${spaceName}`,
           ExitCode.USAGE_ERROR
         );
       }
@@ -42912,7 +43388,7 @@ init_sdk();
 init_space();
 init_host();
 init_theme();
-import { CLI_NAME as CLI_NAME35 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME36 } from "@tinycloud/operations/cli-name";
 import { writeFile as writeFile5 } from "fs/promises";
 import { resolve as resolve8 } from "path";
 async function dbHandle(node, dbName, spaceInput, profileName2) {
@@ -42936,12 +43412,12 @@ database for simple apps, or pass --db to target a named database. Pass
 --space to target a non-primary space (e.g. the manifest "applications" space).
 
 Common workflows:
-  $ ${CLI_NAME35} sql execute "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
-  $ ${CLI_NAME35} sql execute "INSERT INTO notes (body) VALUES (?)" --params '["ship docs"]'
-  $ ${CLI_NAME35} sql query "SELECT id, body FROM notes ORDER BY id"
-  $ ${CLI_NAME35} sql query "SELECT * FROM events WHERE type = ?" --db analytics --params '["signup"]'
-  $ ${CLI_NAME35} sql query "SELECT count(*) FROM conversation" --space applications --db xyz.tinycloud.listen/conversations
-  $ ${CLI_NAME35} sql export --db analytics --output analytics.db
+  $ ${CLI_NAME36} sql execute "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
+  $ ${CLI_NAME36} sql execute "INSERT INTO notes (body) VALUES (?)" --params '["ship docs"]'
+  $ ${CLI_NAME36} sql query "SELECT id, body FROM notes ORDER BY id"
+  $ ${CLI_NAME36} sql query "SELECT * FROM events WHERE type = ?" --db analytics --params '["signup"]'
+  $ ${CLI_NAME36} sql query "SELECT count(*) FROM conversation" --space applications --db xyz.tinycloud.listen/conversations
+  $ ${CLI_NAME36} sql export --db analytics --output analytics.db
 
 Commands:
   query     Read rows with SELECT statements
@@ -42958,10 +43434,10 @@ Tips:
   sql.command("query <sql>").description("Run a read-only SELECT query").option("--db <name>", "SQLite database name within the current space", "default").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("--params <json>", "Bind parameters as a JSON array for ? placeholders").addHelpText("after", `
 
 Examples:
-  $ ${CLI_NAME35} sql query "SELECT * FROM notes ORDER BY id"
-  $ ${CLI_NAME35} sql query "SELECT * FROM notes WHERE id = ?" --params '[42]'
-  $ ${CLI_NAME35} sql query "SELECT count(*) AS total FROM events" --db analytics --json
-  $ ${CLI_NAME35} sql query "SELECT count(*) FROM conversation" --space applications --db xyz.tinycloud.listen/conversations
+  $ ${CLI_NAME36} sql query "SELECT * FROM notes ORDER BY id"
+  $ ${CLI_NAME36} sql query "SELECT * FROM notes WHERE id = ?" --params '[42]'
+  $ ${CLI_NAME36} sql query "SELECT count(*) AS total FROM events" --db analytics --json
+  $ ${CLI_NAME36} sql query "SELECT count(*) FROM conversation" --space applications --db xyz.tinycloud.listen/conversations
 
 Output:
   Human output is formatted as a table. Piped output or --json returns
@@ -43002,11 +43478,11 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
   sql.command("execute <sql>").description("Run a write or schema statement").option("--db <name>", "SQLite database name within the current space", "default").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("--params <json>", "Bind parameters as a JSON array for ? placeholders").addHelpText("after", `
 
 Examples:
-  $ ${CLI_NAME35} sql execute "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
-  $ ${CLI_NAME35} sql execute "INSERT INTO notes (body) VALUES (?)" --params '["first note"]'
-  $ ${CLI_NAME35} sql execute "UPDATE notes SET body = ? WHERE id = ?" --params '["edited", 1]'
-  $ ${CLI_NAME35} sql execute "DROP TABLE old_notes" --db archive
-  $ ${CLI_NAME35} sql execute "DELETE FROM conversation WHERE id = ?" --space applications --db xyz.tinycloud.listen/conversations --params '["abc"]'
+  $ ${CLI_NAME36} sql execute "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)"
+  $ ${CLI_NAME36} sql execute "INSERT INTO notes (body) VALUES (?)" --params '["first note"]'
+  $ ${CLI_NAME36} sql execute "UPDATE notes SET body = ? WHERE id = ?" --params '["edited", 1]'
+  $ ${CLI_NAME36} sql execute "DROP TABLE old_notes" --db archive
+  $ ${CLI_NAME36} sql execute "DELETE FROM conversation WHERE id = ?" --space applications --db xyz.tinycloud.listen/conversations --params '["abc"]'
 
 Output:
   Returns JSON with the changed row count and last inserted row id when available.
@@ -43035,9 +43511,9 @@ Output:
   sql.command("export").description("Export a SQLite database as a binary .db file").option("--db <name>", "SQLite database name within the current space", "default").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").option("-o, --output <file>", "Output file path", "export.db").addHelpText("after", `
 
 Examples:
-  $ ${CLI_NAME35} sql export
-  $ ${CLI_NAME35} sql export --db analytics --output analytics.db
-  $ ${CLI_NAME35} sql export --space applications --db xyz.tinycloud.listen/conversations --output listen.db
+  $ ${CLI_NAME36} sql export
+  $ ${CLI_NAME36} sql export --db analytics --output analytics.db
+  $ ${CLI_NAME36} sql export --space applications --db xyz.tinycloud.listen/conversations --output listen.db
 
 Output:
   Writes the database file locally and returns JSON with the path and size.
@@ -43070,19 +43546,19 @@ Output:
   sql.command("copy").description("Copy rows between SQL databases (optionally across spaces)").requiredOption("--from-db <name>", "Source database name").requiredOption("--to-db <name>", "Destination database name").option("--from-space <name|uri>", "Source space (defaults to primary)").option("--to-space <name|uri>", "Destination space (defaults to primary)").option("--table <name...>", "Restrict copy to specific tables (repeat or comma-separated)").option("--dry-run", "Print the plan without writing", false).addHelpText("after", `
 
 Examples:
-  $ ${CLI_NAME35} sql copy --from-db com.tinycloud.conversation-sync/conversations \\
+  $ ${CLI_NAME36} sql copy --from-db com.tinycloud.conversation-sync/conversations \\
                 --to-db xyz.tinycloud.listen/conversations \\
                 --space applications --dry-run
-  $ ${CLI_NAME35} sql copy --from-space applications --from-db com.foo/data \\
+  $ ${CLI_NAME36} sql copy --from-space applications --from-db com.foo/data \\
                 --to-space applications --to-db com.bar/data \\
                 --table conversation --table participant
 
 Notes:
   - Refuses to run when (resolved space, db) is identical for source and destination.
-  - Does NOT create destination tables. Run the target app once (or use \`${CLI_NAME35} sql execute\`)
+  - Does NOT create destination tables. Run the target app once (or use \`${CLI_NAME36} sql execute\`)
     to materialize the schema before copying.
   - One row at a time; suitable for small/medium datasets. Large copies should
-    use \`${CLI_NAME35} sql export\` + bulk import.
+    use \`${CLI_NAME36} sql export\` + bulk import.
   - Authorization: the active session/delegation must cover sql/read on source
     AND sql/write on destination. Otherwise the relevant operation will fail.
 `).action(async (options, cmd) => {
@@ -43182,7 +43658,7 @@ init_errors();
 init_formatter();
 init_theme();
 init_permissions();
-import { CLI_NAME as CLI_NAME36 } from "@tinycloud/operations/cli-name";
+import { CLI_NAME as CLI_NAME37 } from "@tinycloud/operations/cli-name";
 import {
   NodeWasmBindings as NodeWasmBindings2
 } from "@tinycloud/node-sdk";
@@ -43456,7 +43932,7 @@ function formatStatus(summary) {
   lines.push(`Default profile: ${theme.value(summary.defaultProfile)}`);
   lines.push("");
   if (summary.profiles.length === 0) {
-    lines.push(theme.muted(`No profiles configured. Run: ${CLI_NAME36} init`));
+    lines.push(theme.muted(`No profiles configured. Run: ${CLI_NAME37} init`));
     return `${lines.join("\n")}
 `;
   }
@@ -43545,11 +44021,11 @@ function plural(count, label) {
 init_theme();
 init_errors();
 import { execSync } from "child_process";
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 var PACKAGE_NAME = "@tinycloud/cli";
 function getCurrentVersion() {
   const pkg = JSON.parse(
-    readFileSync2(new URL("../package.json", import.meta.url), "utf-8")
+    readFileSync3(new URL("../package.json", import.meta.url), "utf-8")
   );
   return pkg.version;
 }
@@ -43935,6 +44411,7 @@ function registerVarsCommand(program) {
 // src/command-registry.ts
 function registerTinyCloudCommands(program) {
   registerInitCommand(program);
+  registerOnboardCommand(program);
   registerContextCommand(program);
   registerAuthCommand(program);
   registerEnableCommand(program);