@aiaiai-pt/martha-cli 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.5.0] — 2026-05-20
+
+### Added — #372 PR4 collection-hierarchy CLI parity
+- `documents collections --tree` renders the parent → child hierarchy as ASCII, mirroring the admin tree UX from #372 PR3.
+- `documents create-collection --parent <slug-or-id>` creates a sub-collection under the named parent. Same slug/name/UUID resolution the agent uses.
+- `documents move-collection <id> --parent <slug-or-id> | --root` moves a collection atomically. Cycle prevention is server-side; CLI rejects self-as-parent eagerly.
+- `clients grant <c> function <fn> --collection <slug-or-id>` and the matching `clients revoke ... --collection`. Scoped grants only apply to functions (#372 PR2 cascade); passing `--collection` to a workflow or agent grant is a clean Validation error.
+- `agents add-function <a> <fn> --collection <slug-or-id>` and `agents remove-function <a> <fn> --collection` likewise. Omit the flag to target the root grant (`collection_id IS NULL` per the allowlist semantics).
+- Shared `lib/collections.ts:resolveCollectionIdForGrant` resolves UUID, slug, or name with a single `GET /api/admin/collections` round-trip.
+
 ## [0.3.0] — 2026-05-10
 
 First-run UX for third-party developers and agent runtimes.

package/dist/index.js

@@ -1019,7 +1019,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -10830,7 +10830,7 @@ function registerDefinitionCommands(program2, config) {
   function isJson() {
     return !!program2.opts().json;
   }
-  const listCmd = cmd.command("list").description(`List ${config.typeNamePlural}`).option("--inactive", "Include inactive items").option("--limit <n>", "Max results", "50");
+  const listCmd = cmd.command("list").description(`List ${config.typeNamePlural}`).option("--inactive", "Include inactive items").option("--limit <n>", "Max results per page", "50").option("--search <term>", "Case-insensitive substring filter on name (server-side)").option("--all", "Auto-paginate until every matching item is fetched (server caps at 500/page)");
   if (config.extraListOptions) {
     config.extraListOptions(listCmd);
   }
@@ -10840,17 +10840,65 @@ function registerDefinitionCommands(program2, config) {
     if (isNaN(limitN) || limitN < 1) {
       throw new CLIError("--limit must be a positive integer", 4 /* Validation */);
     }
-    const params = {
-      limit: String(limitN),
-      skip: "0"
-    };
+    const baseParams = {};
     if (!opts.inactive)
-      params.active_only = "true";
+      baseParams.active_only = "true";
+    if (opts.search)
+      baseParams.name_contains = String(opts.search);
     if (config.buildListParams) {
-      Object.assign(params, config.buildListParams(opts));
+      Object.assign(baseParams, config.buildListParams(opts));
+    }
+    let items;
+    let total;
+    if (opts.all) {
+      const pageSize = 500;
+      items = [];
+      let skip = 0;
+      while (true) {
+        const params = {
+          ...baseParams,
+          limit: String(pageSize),
+          skip: String(skip)
+        };
+        const res = await ctx.api.getRaw(config.apiPath, { params });
+        if (!res.ok) {
+          throw new CLIError(`List ${config.typeNamePlural} failed: HTTP ${res.status}`, 1 /* Error */);
+        }
+        const headerTotal = res.headers.get("x-total-count");
+        if (headerTotal !== null && total === undefined) {
+          total = Number(headerTotal);
+        }
+        const body = await res.json();
+        const pageItems = config.extractList(body);
+        items.push(...pageItems);
+        if (pageItems.length < pageSize)
+          break;
+        if (total !== undefined && items.length >= total)
+          break;
+        skip += pageSize;
+        if (skip > 50000) {
+          throw new CLIError(`Aborted --all after fetching ${items.length} ${config.typeNamePlural}; suspected pagination bug`, 1 /* Error */);
+        }
+      }
+    } else {
+      const params = {
+        ...baseParams,
+        limit: String(limitN),
+        skip: "0"
+      };
+      const res = await ctx.api.getRaw(config.apiPath, { params });
+      if (!res.ok) {
+        throw new CLIError(`List ${config.typeNamePlural} failed: HTTP ${res.status}`, 1 /* Error */);
+      }
+      const headerTotal = res.headers.get("x-total-count");
+      if (headerTotal !== null)
+        total = Number(headerTotal);
+      const data = await res.json();
+      items = config.extractList(data);
+      const bodyTotal = config.extractTotal?.(data);
+      if (bodyTotal !== undefined)
+        total = bodyTotal;
     }
-    const data = await ctx.api.get(config.apiPath, { params });
-    const items = config.extractList(data);
     if (isJson()) {
       console.log(JSON.stringify(items, null, 2));
       return;
@@ -10862,10 +10910,10 @@ function registerDefinitionCommands(program2, config) {
     for (const item of items) {
       console.log(config.listColumns.map((col, i) => col.accessor(item).padEnd(widths[i])).join("  "));
     }
-    const total = config.extractTotal?.(data);
     if (total !== undefined && total > items.length) {
+      const hint = opts.search ? `(narrow with --search or use --all)` : `(use --search <term> or --all to load everything)`;
       console.log(source_default.dim(`
-${items.length} of ${total} ${config.typeNamePlural} (use --limit ${total} to see all)`));
+${items.length} of ${total} ${config.typeNamePlural} ${hint}`));
     } else {
       console.log(source_default.dim(`
 ${items.length} ${config.typeNamePlural}`));
@@ -11456,16 +11504,46 @@ Error: ${err instanceof Error ? err.message : String(err)}
 `);
 }
 async function runOneShot(ctx, sessionId, message, isJson, clientId, showTools, timeoutMs) {
+  const toolCalls = [];
+  function recordToolStatus(data) {
+    try {
+      const tools = JSON.parse(data);
+      for (const t of tools) {
+        const name = t.tool_name ?? t.tool_label;
+        if (!name)
+          continue;
+        toolCalls.push({ name, status: t.status });
+      }
+    } catch {}
+  }
+  function recordToolCall(data) {
+    try {
+      const parsed = JSON.parse(data);
+      if (parsed.name)
+        toolCalls.push({ name: parsed.name });
+    } catch {}
+  }
   const { response } = await sendMessage(ctx, sessionId, message, {
     clientId,
     timeoutMs,
-    onToolCall: showTools ? (data) => process.stderr.write(formatToolCall(data)) : undefined,
+    onToolStatus: isJson ? recordToolStatus : showTools ? (data) => {
+      recordToolStatus(data);
+      process.stderr.write(formatToolStatus(data));
+    } : undefined,
+    onToolCall: isJson ? recordToolCall : showTools ? (data) => {
+      recordToolCall(data);
+      process.stderr.write(formatToolCall(data));
+    } : undefined,
     onToolResult: showTools ? (data) => process.stderr.write(formatToolResult(data)) : undefined,
     onClear: showTools ? () => process.stderr.write(source_default.dim(`  --- tool iteration ---
 `)) : undefined
   });
   if (isJson) {
-    console.log(JSON.stringify({ session_id: sessionId, response }));
+    console.log(JSON.stringify({
+      session_id: sessionId,
+      response,
+      tool_calls: toolCalls
+    }));
   } else {
     console.log(response);
   }
@@ -13140,6 +13218,27 @@ var workflowsConfig = {
 
 // src/commands/agents.ts
 init_errors();
+
+// src/lib/collections.ts
+init_errors();
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function resolveCollectionIdForGrant(ctx, ref) {
+  if (UUID_RE.test(ref)) {
+    return ref;
+  }
+  const all = await ctx.api.get("/api/admin/collections", {
+    params: { active_only: "false" }
+  });
+  const bySlug = all.find((c) => c.slug === ref);
+  if (bySlug)
+    return bySlug.id;
+  const byName = all.find((c) => c.name === ref);
+  if (byName)
+    return byName.id;
+  throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */, "Run `martha documents collections --tree` to see available collections.");
+}
+
+// src/commands/agents.ts
 function parseSetFlags(items) {
   const result = {};
   for (const item of items) {
@@ -13297,7 +13396,7 @@ var agentsConfig = {
       console.log(`  Updated:     ${agent.updated_at}`);
   },
   extraCommands: (parentCmd, getCtx, isJson) => {
-    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").action(async (agent, functionName, opts) => {
+    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").option("--collection <slug-or-id>", "Scope the grant to one collection (#372 PR2). " + "Server rejects with 400 if the function is collection-agnostic.").action(async (agent, functionName, opts) => {
       const ctx = getCtx();
       const body = {
         function_name: functionName
@@ -13305,25 +13404,36 @@ var agentsConfig = {
       if (opts.set) {
         body.config_overrides = parseSetFlags(opts.set);
       }
+      if (opts.collection) {
+        body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
+      }
       const result = await ctx.api.post(`${API_PATH}/${encodeURIComponent(agent)}/functions`, body);
       if (isJson()) {
         console.log(JSON.stringify(result, null, 2));
         return;
       }
-      console.log(`Added function '${functionName}' to agent '${agent}'`);
+      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+      console.log(`Added function '${functionName}' to agent '${agent}'${scopeLabel}`);
     });
-    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").action(async (agent, functionName) => {
+    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (#372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (agent, functionName, opts) => {
       const ctx = getCtx();
-      await ctx.api.del(`${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`);
+      let endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
+      if (opts.collection) {
+        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
+        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+      }
+      await ctx.api.del(endpoint);
       if (isJson()) {
         console.log(JSON.stringify({
           agent,
           function_name: functionName,
+          collection: opts.collection ?? null,
           removed: true
         }));
         return;
       }
-      console.log(`Removed function '${functionName}' from agent '${agent}'`);
+      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+      console.log(`Removed function '${functionName}' from agent '${agent}'${scopeLabel}`);
     });
     parentCmd.command("provision-auth <agent>").description("Provision, switch, or rotate agent auth credentials").requiredOption("--method <method>", "Auth method: service-account or api-key").action(async (agent, opts) => {
       const ctx = getCtx();
@@ -13429,6 +13539,32 @@ function formatBytes(bytes) {
     return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+function renderCollectionTree(items) {
+  const byParent = new Map;
+  const ids = new Set(items.map((c) => c.id));
+  for (const c of items) {
+    const key = c.parent_collection_id && ids.has(c.parent_collection_id) ? c.parent_collection_id : null;
+    const list = byParent.get(key);
+    if (list)
+      list.push(c);
+    else
+      byParent.set(key, [c]);
+  }
+  const byName = (a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+  for (const list of byParent.values())
+    list.sort(byName);
+  const roots = byParent.get(null) ?? [];
+  function walk(node, prefix, isLast) {
+    const connector = isLast ? "└── " : "├── ";
+    const count = node.document_count ?? 0;
+    const status = node.is_active === false ? source_default.dim(" [inactive]") : "";
+    console.log(`${prefix}${connector}${node.name}${source_default.dim(` (${count})`)}${status}`);
+    const children = byParent.get(node.id) ?? [];
+    const nextPrefix = prefix + (isLast ? "    " : "│   ");
+    children.forEach((child, idx) => walk(child, nextPrefix, idx === children.length - 1));
+  }
+  roots.forEach((root, idx) => walk(root, "", idx === roots.length - 1));
+}
 var STATUS_COLORS2 = {
   ready: source_default.green,
   active: source_default.green,
@@ -13548,7 +13684,25 @@ function registerDocumentCommands(program2) {
   function isJson() {
     return !!program2.opts().json;
   }
-  cmd.command("collections").description("List document collections").option("--inactive", "Include inactive collections").option("--limit <n>", "Max results", "50").action(async (opts) => {
+  async function resolveCollection(ctx, ref) {
+    const looksLikeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref);
+    if (looksLikeUuid) {
+      try {
+        return await ctx.api.get(`/api/admin/collections/${encodeURIComponent(ref)}`);
+      } catch {}
+    }
+    const all = await ctx.api.get("/api/admin/collections", {
+      params: { active_only: "false" }
+    });
+    const bySlug = all.find((c) => c.slug === ref);
+    if (bySlug)
+      return bySlug;
+    const byName = all.find((c) => c.name === ref);
+    if (byName)
+      return byName;
+    throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */);
+  }
+  cmd.command("collections").description("List document collections").option("--inactive", "Include inactive collections").option("--limit <n>", "Max results", "50").option("--tree", "Render the hierarchy as ASCII (--limit ignored in tree mode)").action(async (opts) => {
     const ctx = getCtx();
     const limitN = parseInt(opts.limit ?? "50", 10);
     if (isNaN(limitN) || limitN < 1) {
@@ -13557,13 +13711,17 @@ function registerDocumentCommands(program2) {
     const params = {};
     if (!opts.inactive)
       params.active_only = "true";
-    const items = await ctx.api.get("/api/admin/collections", {
-      params
-    });
+    const items = await ctx.api.get("/api/admin/collections", { params });
     if (isJson()) {
       console.log(JSON.stringify(items, null, 2));
       return;
     }
+    if (opts.tree) {
+      renderCollectionTree(items);
+      console.log(source_default.dim(`
+${items.length} collections`));
+      return;
+    }
     const columns = [
       { header: "NAME", accessor: (i) => i.name },
       {
@@ -13615,7 +13773,7 @@ ${items.length} collections`));
     if (col.updated_at)
       console.log(`  Updated:   ${col.updated_at}`);
   });
-  cmd.command("create-collection").description("Create a new document collection").requiredOption("--name <name>", "Collection name").option("--description <text>", "Collection description").action(async (opts) => {
+  cmd.command("create-collection").description("Create a new document collection").requiredOption("--name <name>", "Collection name").option("--description <text>", "Collection description").option("--parent <slug-or-id>", "Create as a sub-collection of the given collection (#372 PR1)").action(async (opts) => {
     const ctx = getCtx();
     const tenantId = await ctx.getTenantId();
     const body = {
@@ -13624,12 +13782,41 @@ ${items.length} collections`));
     };
     if (opts.description)
       body.description = opts.description;
+    if (opts.parent) {
+      const parent = await resolveCollection(ctx, opts.parent);
+      body.parent_collection_id = parent.id;
+    }
     const result = await ctx.api.post("/api/admin/collections", body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    console.log(`Created collection '${result.name}' (${result.id})`);
+    const parentLabel = opts.parent ? ` under '${opts.parent}'` : "";
+    console.log(`Created collection '${result.name}' (${result.id})${parentLabel}`);
+  });
+  cmd.command("move-collection <id>").description("Move a collection to a new parent or to the root (#372 PR1)").option("--parent <slug-or-id>", "New parent collection (mutually exclusive with --root)").option("--root", "Move to the top level (no parent)").action(async (id, opts) => {
+    if (!!opts.parent === !!opts.root) {
+      throw new CLIError("Pass exactly one of --parent <slug-or-id> or --root", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const moving = await resolveCollection(ctx, id);
+    let newParentId;
+    if (opts.root) {
+      newParentId = null;
+    } else {
+      const parent = await resolveCollection(ctx, opts.parent);
+      if (parent.id === moving.id) {
+        throw new CLIError("Cannot move a collection into itself.", 4 /* Validation */);
+      }
+      newParentId = parent.id;
+    }
+    const result = await ctx.api.put(`/api/admin/collections/${encodeURIComponent(moving.id)}`, { parent_collection_id: newParentId });
+    if (isJson()) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const target = newParentId ? `under '${opts.parent}'` : "to root (top-level)";
+    console.log(`Moved collection '${moving.name}' ${target}`);
   });
   cmd.command("upload <collection-id> <file>").description("Upload a document to a collection").option("--wait", "Wait for ingestion to complete").option("--follow", "Follow ingestion progress in real time").action(async (collectionId, filePath, opts) => {
     const ctx = getCtx();
@@ -15729,23 +15916,30 @@ async function resolveClientId(ctx, nameOrId) {
 async function resolveDefinitionId(ctx, type, name) {
   if (type === "agent")
     return name;
-  const path5 = type === "function" ? `${DEFS_API}/functions` : `${DEFS_API}/workflows`;
-  const data = await ctx.api.get(path5, {
-    params: { limit: "500", skip: "0" }
-  });
-  let items;
-  if (Array.isArray(data)) {
-    items = data;
-  } else if (data && typeof data === "object" && "items" in data) {
-    items = data.items;
-  } else {
-    throw new CLIError(`Unexpected response shape from ${type}s list`, 1 /* Error */);
-  }
-  const match = items.find((d) => String(d.name ?? "").toLowerCase() === name.toLowerCase());
-  if (!match) {
-    throw new CLIError(`${type} not found: '${name}'`, 3 /* NotFound */, `Run \`martha ${type}s list\` to see available ${type}s.`);
+  const listPath = type === "function" ? `${DEFS_API}/functions` : `${DEFS_API}/workflows`;
+  const exactPath = `${listPath}/${encodeURIComponent(name)}`;
+  try {
+    const exact = await ctx.api.get(exactPath);
+    if (exact && typeof exact === "object" && "id" in exact) {
+      return String(exact.id);
+    }
+  } catch (e) {
+    const code = e?.status ?? e?.statusCode;
+    if (code !== 404)
+      throw e;
   }
-  return String(match.id);
+  let suggestion = "";
+  try {
+    const fuzzy = await ctx.api.get(listPath, {
+      params: { name_contains: name, limit: "5", skip: "0" }
+    });
+    const items = Array.isArray(fuzzy) ? fuzzy : fuzzy && typeof fuzzy === "object" && ("items" in fuzzy) ? fuzzy.items : [];
+    const names = items.map((d) => String(d.name ?? "")).filter((n) => n.length > 0).slice(0, 5);
+    if (names.length > 0) {
+      suggestion = `Did you mean: ${names.join(", ")}?`;
+    }
+  } catch {}
+  throw new CLIError(`${type} not found: '${name}'`, 3 /* NotFound */, suggestion || `Run \`martha ${type}s list --search ${name}\` to find it.`);
 }
 function formatDate(val) {
   if (!val)
@@ -16052,7 +16246,7 @@ ${clients.length} client(s)`));
     }
     console.log(`Deleted client '${nameOrId}'`);
   });
-  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").action(async (clientNameOrId, type, defName, opts) => {
+  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").option("--collection <slug-or-id>", "Scope the grant to one collection (function grants only; #372 PR2)").action(async (clientNameOrId, type, defName, opts) => {
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
@@ -16080,20 +16274,30 @@ ${clients.length} client(s)`));
       }
       body.config_overrides = parseSetFlags(opts.config);
     }
+    if (opts.collection) {
+      if (accessType !== "function") {
+        throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
+      }
+      body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
+    }
     const result = await ctx.api.post(endpoint, body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'`);
+    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'${scopeLabel}`);
   });
-  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").action(async (clientNameOrId, type, defName) => {
+  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (function grants only; #372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (clientNameOrId, type, defName, opts) => {
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
     const accessType = type;
     const ctx = getCtx();
     const clientId = await resolveClientId(ctx, clientNameOrId);
+    if (opts.collection && accessType !== "function") {
+      throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
+    }
     let endpoint;
     if (accessType === "agent") {
       endpoint = `${DEFS_API}/clients/${clientId}/agents/${encodeURIComponent(defName)}`;
@@ -16101,6 +16305,10 @@ ${clients.length} client(s)`));
       const defId = await resolveDefinitionId(ctx, accessType, defName);
       const typePlural = `${accessType}s`;
       endpoint = `${DEFS_API}/clients/${clientId}/${typePlural}/${encodeURIComponent(defId)}`;
+      if (opts.collection) {
+        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
+        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+      }
     }
     await ctx.api.del(endpoint);
     if (isJson()) {
@@ -16108,11 +16316,13 @@ ${clients.length} client(s)`));
         client: clientNameOrId,
         type: accessType,
         name: defName,
+        collection: opts.collection ?? null,
         revoked: true
       }));
       return;
     }
-    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'`);
+    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'${scopeLabel}`);
   });
   const embed = cmd.command("embed").description("Create, configure, and test embeddable chat clients");
   function addEmbedConfigOptions(command) {
@@ -16231,7 +16441,11 @@ ${clients.length} client(s)`));
     const result = await ctx.api.get(`${API}/${clientId}`);
     const assetBaseUrl = getEmbedAssetBaseUrl(ctx.profile.api_url);
     if (isJson()) {
-      console.log(JSON.stringify({ ...result, asset_base_url: assetBaseUrl, embed_credentials: credentials }, null, 2));
+      console.log(JSON.stringify({
+        ...result,
+        asset_base_url: assetBaseUrl,
+        embed_credentials: credentials
+      }, null, 2));
       return;
     }
     printEmbedSummary(result, assetBaseUrl);
@@ -16331,7 +16545,9 @@ ${clients.length} client(s)`));
       const manifestPath = `/api/embed/manifest/${encodeURIComponent(key)}`;
       const manifest = await ctx.api.get(manifestPath, { headers: { Origin: origin } });
       const deniedUrl = `${deriveMarthaWebOrigin(ctx.profile.api_url)}${manifestPath}`;
-      const denied = await fetch(deniedUrl, { headers: { Origin: deniedOrigin } });
+      const denied = await fetch(deniedUrl, {
+        headers: { Origin: deniedOrigin }
+      });
       if (denied.status !== 403) {
         throw new CLIError(`Denied-origin manifest check expected 403, got ${denied.status}`, 1 /* Error */);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -272,11 +272,13 @@ martha agents generate-key <agent>
 **Function grants:**
 
 ```bash
-martha agents add-function <agent> <function> [--set key=value]    # config_overrides
-martha agents remove-function <agent> <function>
+martha agents add-function <agent> <function> [--set key=value] [--collection <slug-or-id>]
+martha agents remove-function <agent> <function> [--collection <slug-or-id>]
 martha agents functions <agent>                                     # List granted functions
 ```
 
+`--collection` scopes the grant to one collection per the #372 PR2 cascade. Omit it to grant at the root (tenant-wide); pass it on `remove-function` to revoke just that scope. Server returns 400 if the function is collection-agnostic (e.g. `recall`).
+
 ---
 
 ## Tasks: queue + executor lifecycle
@@ -579,9 +581,10 @@ Document collections are tenant-scoped containers that ingest files (PDF, DOCX,
 
 ```bash
 # Collections
-martha documents collections [--inactive] [--limit 50]
+martha documents collections [--inactive] [--limit 50] [--tree]      # --tree renders the parent/child hierarchy as ASCII (#372)
 martha documents collection <id>               # Stats, ingestion status, total size
-martha documents create-collection --name "My Docs" [--description "..."]
+martha documents create-collection --name "My Docs" [--description "..."] [--parent <slug-or-id>]
+martha documents move-collection <id> --parent <slug-or-id> | --root  # Atomic move; server rejects cycles
 
 # Document lifecycle
 martha documents upload <collection-id> <file> [--wait] [--follow]   # --follow streams ingestion progress
@@ -653,11 +656,13 @@ martha clients update <name-or-id> [--name <n>] [--system-prompts '...']
 martha clients delete <name-or-id> [--force] [--yes]                  # --force drops sessions
 
 # Access grants — what definitions this client's sessions can use
-martha clients grant <client> function|workflow|agent <def-name> [--config key=value]
-martha clients revoke <client> function|workflow|agent <def-name>
+martha clients grant <client> function|workflow|agent <def-name> [--config key=value] [--collection <slug-or-id>]
+martha clients revoke <client> function|workflow|agent <def-name> [--collection <slug-or-id>]
 martha clients access <name-or-id>                                    # All grants for this client
 ```
 
+`--collection` is only valid on `function` grants (#372 PR2). The same UUID, slug, or name accepted by `documents move-collection` works here. Granting a scope on a collection-agnostic function (like `recall`) returns 400.
+
 ---
 
 ## Sessions + Chat
@@ -859,6 +864,35 @@ martha integrations specs --json | jq -r '.[] | select(.name == "linear") | .id'
 done
 ```
 
+### Collection hierarchy + scoped grants (#372)
+
+```bash
+# See the tree
+martha documents collections --tree
+
+# Build a hierarchy
+martha documents create-collection --name "Reports"
+martha documents create-collection --name "2026 Reports" --parent reports
+martha documents create-collection --name "Q1 2026" --parent 2026-reports
+
+# Reorganize
+martha documents move-collection q1-2026 --parent reports        # promote a level
+martha documents move-collection 2026-reports --root             # back to top-level
+
+# Scoped grants. Agent only sees docs in /Reports and descendants.
+martha agents add-function planner list_docs --collection reports
+martha agents add-function planner read_doc --collection reports
+
+# Most-specific ancestor wins: an additional grant on a child
+# collection overrides config_overrides for that subtree only.
+martha agents add-function planner list_docs --collection q1-2026 --set max_results=50
+
+# Revoke just one scope; the parent root grant (if any) survives.
+martha agents remove-function planner list_docs --collection q1-2026
+```
+
+`--collection` accepts UUID, slug, or name — same identifier the agent uses. Resolution mirrors the backend.
+
 ---
 
 ## Troubleshooting