@aiaiai-pt/martha-cli 0.16.1 → 0.19.0

package/dist/index.js

@@ -5,43 +5,25 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-function __accessProp(key) {
-  return this[key];
-}
-var __toESMCache_node;
-var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
-  var canCache = mod != null && typeof mod === "object";
-  if (canCache) {
-    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
-    var cached = cache.get(mod);
-    if (cached)
-      return cached;
-  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
+        get: () => mod[key],
         enumerable: true
       });
-  if (canCache)
-    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1019,7 +1001,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;
@@ -11077,7 +11059,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.16.1";
+var CLI_VERSION = "0.19.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -13577,27 +13559,6 @@ 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) {
@@ -13774,7 +13735,10 @@ 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)").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) => {
+    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>", "REMOVED (#609) — collection access is managed separately; see error").action(async (agent, functionName, opts) => {
+      if (opts.collection) {
+        throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections grant <collection> --to agent:<id>`.", 4 /* Validation */);
+      }
       const ctx = getCtx();
       const body = {
         function_name: functionName
@@ -13782,36 +13746,29 @@ 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;
       }
-      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-      console.log(`Added function '${functionName}' to agent '${agent}'${scopeLabel}`);
+      console.log(`Added function '${functionName}' to agent '${agent}'`);
     });
-    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();
-      let endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
+    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (agent, functionName, opts) => {
       if (opts.collection) {
-        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
-        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+        throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections revoke <collection> --to agent:<id>`.", 4 /* Validation */);
       }
+      const ctx = getCtx();
+      const endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
       await ctx.api.del(endpoint);
       if (isJson()) {
         console.log(JSON.stringify({
           agent,
           function_name: functionName,
-          collection: opts.collection ?? null,
           removed: true
         }));
         return;
       }
-      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-      console.log(`Removed function '${functionName}' from agent '${agent}'${scopeLabel}`);
+      console.log(`Removed function '${functionName}' from agent '${agent}'`);
     });
     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();
@@ -14892,6 +14849,7 @@ function registerApprovalCommands(program2) {
 }
 
 // src/commands/tasks.ts
+import { readFileSync } from "node:fs";
 init_errors();
 var truncate2 = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
 var sleep3 = (ms, signal) => new Promise((resolve) => {
@@ -15332,13 +15290,25 @@ ${items.length} task(s) available`));
       process.off("SIGTERM", onSignal);
     }
   });
-  cmd.command("complete <id>").description("Complete a claimed task with outcome").requiredOption("--outcome <json>", "Outcome data as JSON string").action(async (id, opts) => {
+  cmd.command("complete <id>").description("Complete a claimed task with outcome").option("--outcome <json>", "Outcome data as JSON string").option("--outcome-file <path>", "Read outcome JSON from a file instead of --outcome (for large outcomes)").action(async (id, opts) => {
     const ctx = getCtx();
+    let rawOutcome;
+    if (opts.outcomeFile) {
+      try {
+        rawOutcome = readFileSync(opts.outcomeFile, "utf-8");
+      } catch {
+        throw new CLIError(`--outcome-file could not be read: ${opts.outcomeFile}`, 4 /* Validation */);
+      }
+    } else if (opts.outcome) {
+      rawOutcome = opts.outcome;
+    } else {
+      throw new CLIError("provide --outcome <json> or --outcome-file <path>", 4 /* Validation */);
+    }
     let outcome;
     try {
-      outcome = JSON.parse(opts.outcome);
+      outcome = JSON.parse(rawOutcome);
     } catch {
-      throw new CLIError("--outcome must be valid JSON", 4 /* Validation */);
+      throw new CLIError("outcome must be valid JSON", 4 /* Validation */);
     }
     const result = await ctx.api.post(`/api/tasks/${encodeURIComponent(id)}/complete`, { outcome });
     if (isJson()) {
@@ -17056,7 +17026,10 @@ ${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)").option("--collection <slug-or-id>", "Scope the grant to one collection (function grants only; #372 PR2)").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>", "REMOVED (#609) — collection access is managed separately; see error").action(async (clientNameOrId, type, defName, opts) => {
+    if (opts.collection) {
+      throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections grant <collection> --to client:<id>`.", 4 /* Validation */);
+    }
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
@@ -17084,30 +17057,23 @@ ${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;
     }
-    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'${scopeLabel}`);
+    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'`);
   });
-  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) => {
+  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (clientNameOrId, type, defName, opts) => {
+    if (opts.collection) {
+      throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections revoke <collection> --to client:<id>`.", 4 /* Validation */);
+    }
     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)}`;
@@ -17115,10 +17081,6 @@ ${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()) {
@@ -17126,13 +17088,11 @@ ${clients.length} client(s)`));
         client: clientNameOrId,
         type: accessType,
         name: defName,
-        collection: opts.collection ?? null,
         revoked: true
       }));
       return;
     }
-    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'${scopeLabel}`);
+    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'`);
   });
   const embed = cmd.command("embed").description("Create, configure, and test embeddable chat clients");
   function addEmbedConfigOptions(command) {
@@ -18398,6 +18358,484 @@ function registerPolicyCommands(program2) {
   });
 }
 
+// src/commands/authz.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/lib/authz.ts
+init_errors();
+var EX_UNAVAILABLE = 69;
+var PRINCIPAL_TYPES = ["user", "client", "agent", "group"];
+function parsePrincipal(to) {
+  const idx = to.indexOf(":");
+  if (idx <= 0 || idx === to.length - 1) {
+    throw new CLIError(`Invalid --to '${to}'. Use <type>:<id>, e.g. user:<sub>, client:5, agent:<uuid>, group:<id>.`, 4 /* Validation */);
+  }
+  const type = to.slice(0, idx).trim().toLowerCase();
+  const id = to.slice(idx + 1).trim();
+  switch (type) {
+    case "user":
+      return { granteeType: "user", granteeId: id };
+    case "group":
+      return { granteeType: "group", granteeId: id };
+    case "client":
+      return { granteeType: "application", granteeId: `client_${id}` };
+    case "agent":
+      return { granteeType: "application", granteeId: `agent_${id}` };
+    default:
+      throw new CLIError(`Unknown principal type '${type}'. Use one of: ${PRINCIPAL_TYPES.join(", ")}.`, 4 /* Validation */);
+  }
+}
+function formatPrincipal(granteeType, granteeId) {
+  if (granteeType === "application") {
+    const m = /^(client|agent)_(.+)$/.exec(granteeId);
+    if (m)
+      return `${m[1]}:${m[2]}`;
+    return `application:${granteeId}`;
+  }
+  return `${granteeType}:${granteeId}`;
+}
+async function listGrants(ctx, p) {
+  const params = {
+    entity_type: p.entityType,
+    action: p.action
+  };
+  if (p.granteeType)
+    params.grantee_type = p.granteeType;
+  if (p.granteeId)
+    params.grantee_id = p.granteeId;
+  if (p.objectId)
+    params.object_id = p.objectId;
+  if (p.tenant)
+    params.tenant = p.tenant;
+  return ctx.api.get("/api/admin/authz/grants", { params });
+}
+async function grant(ctx, p) {
+  await ctx.api.post("/api/admin/authz/grants", {
+    grantee_type: p.granteeType,
+    grantee_id: p.granteeId,
+    entity_type: p.entityType,
+    action: p.action,
+    object_id: p.objectId ?? null,
+    tenant: p.tenant
+  });
+}
+async function revoke(ctx, p) {
+  await ctx.api.del("/api/admin/authz/grants", {
+    body: {
+      grantee_type: p.granteeType,
+      grantee_id: p.granteeId,
+      entity_type: p.entityType,
+      action: p.action,
+      object_id: p.objectId ?? null,
+      tenant: p.tenant
+    }
+  });
+}
+async function listGroups(ctx, tenant) {
+  const params = {};
+  if (tenant)
+    params.tenant = tenant;
+  return ctx.api.get("/api/admin/authz/groups", { params });
+}
+async function createGroup(ctx, name, tenant) {
+  return ctx.api.post("/api/admin/authz/groups", { name, tenant });
+}
+async function deleteGroup(ctx, groupId, tenant) {
+  const params = {};
+  if (tenant)
+    params.tenant = tenant;
+  await ctx.api.del(`/api/admin/authz/groups/${encodeURIComponent(groupId)}`, {
+    params
+  });
+}
+async function addMember(ctx, groupId, userSub, tenant) {
+  await ctx.api.post(`/api/admin/authz/groups/${encodeURIComponent(groupId)}/members`, { user_sub: userSub, tenant });
+}
+async function removeMember(ctx, groupId, userSub, tenant) {
+  const params = {};
+  if (tenant)
+    params.tenant = tenant;
+  await ctx.api.del(`/api/admin/authz/groups/${encodeURIComponent(groupId)}/members/${encodeURIComponent(userSub)}`, { params });
+}
+async function listMembers(ctx, groupId, tenant) {
+  const params = {};
+  if (tenant)
+    params.tenant = tenant;
+  return ctx.api.get(`/api/admin/authz/groups/${encodeURIComponent(groupId)}/members`, { params });
+}
+function extractTyped(err) {
+  if (!(err instanceof MarthaAPIError))
+    return null;
+  const body = err.body;
+  const fromObj = (o) => {
+    if (o && typeof o === "object") {
+      const r = o;
+      if (typeof r.code === "string") {
+        return {
+          code: r.code,
+          message: typeof r.message === "string" ? r.message : err.message,
+          hint: typeof r.hint === "string" ? r.hint : "",
+          status: err.status
+        };
+      }
+    }
+    return null;
+  };
+  return fromObj(body?.detail) ?? fromObj(body);
+}
+function emitAuthzError(err, json) {
+  const typed = extractTyped(err);
+  if (typed) {
+    const transient = typed.code === "ums_unavailable" || typed.status >= 500;
+    const exit = transient ? EX_UNAVAILABLE : err.exitCode ?? 1 /* Error */;
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        code: typed.code,
+        message: typed.message,
+        hint: typed.hint
+      }) + `
+`);
+    } else {
+      process.stderr.write(`Error: ${typed.message}
+`);
+      if (typed.hint)
+        process.stderr.write(`
+${typed.hint}
+`);
+      if (transient)
+        process.stderr.write(`
+(transient — safe to retry)
+`);
+    }
+    process.exitCode = exit;
+    return;
+  }
+  if (err instanceof CLIError) {
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        code: "cli_error",
+        message: err.message,
+        hint: err.suggestion ?? ""
+      }) + `
+`);
+      process.exitCode = err.exitCode;
+      return;
+    }
+    throw err;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  if (json) {
+    process.stdout.write(JSON.stringify({ code: "error", message, hint: "" }) + `
+`);
+    process.exitCode = 1 /* Error */;
+    return;
+  }
+  throw err;
+}
+
+// src/commands/authz.ts
+var DEFAULT_ENTITY = "document_collection";
+var DEFAULT_ACTION = "read";
+function registerAuthzCommands(program2) {
+  function getCtx() {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl)
+      ctx.profile.api_url = program2.opts().apiUrl;
+    return ctx;
+  }
+  const isJson = () => !!program2.opts().json;
+  registerCollections(program2, getCtx, isJson);
+  registerAccess(program2, getCtx, isJson);
+  registerGroups(program2, getCtx, isJson);
+}
+function renderGrantsTable(resp) {
+  if (resp.grants.length === 0) {
+    return source_default.dim(`No ${resp.action} grants on ${resp.entity_type} in ${resp.tenant_id}.`);
+  }
+  const lines = resp.grants.map((g) => {
+    const who = formatPrincipal(g.grantee_type, g.grantee_id);
+    const what = g.scope === "root" ? source_default.yellow("(all — see-all root grant)") : g.object_id;
+    return `  ${who.padEnd(28)} ${what}`;
+  });
+  return source_default.bold(`${resp.action} grants on ${resp.entity_type} (${resp.tenant_id}):`) + `
+` + lines.join(`
+`);
+}
+function registerCollections(program2, getCtx, isJson) {
+  const cmd = program2.command("collections").description("Manage who can read a document collection (UMS authz)");
+  cmd.command("grant <collection>").description("Grant read access on a collection to a principal").requiredOption("--to <type:id>", "user|client|agent|group:<id>").option("--action <action>", "Action to grant", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (collection, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const principal = parsePrincipal(opts.to);
+      const objectId = await resolveCollectionIdForGrant(ctx, collection);
+      await grant(ctx, {
+        ...principal,
+        entityType: DEFAULT_ENTITY,
+        action: opts.action,
+        objectId,
+        tenant: opts.tenant
+      });
+      emitOk(json, {
+        status: "granted",
+        entity_type: DEFAULT_ENTITY,
+        action: opts.action,
+        object_id: objectId,
+        grantee: opts.to,
+        text: `Granted ${opts.action} on collection ${collection} to ${opts.to}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("revoke <collection>").description("Revoke a principal's read access on a collection").requiredOption("--to <type:id>", "user|client|agent|group:<id>").option("--action <action>", "Action to revoke", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (collection, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const principal = parsePrincipal(opts.to);
+      const objectId = await resolveCollectionIdForGrant(ctx, collection);
+      await revoke(ctx, {
+        ...principal,
+        entityType: DEFAULT_ENTITY,
+        action: opts.action,
+        objectId,
+        tenant: opts.tenant
+      });
+      emitOk(json, {
+        status: "revoked",
+        object_id: objectId,
+        grantee: opts.to,
+        text: `Revoked ${opts.action} on collection ${collection} from ${opts.to}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("access <collection>").description("Show who can read a collection (by-object)").option("--action <action>", "Action", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (collection, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const objectId = await resolveCollectionIdForGrant(ctx, collection);
+      const resp = await listGrants(ctx, {
+        entityType: DEFAULT_ENTITY,
+        action: opts.action,
+        objectId,
+        tenant: opts.tenant
+      });
+      if (json) {
+        console.log(JSON.stringify(resp, null, 2));
+      } else {
+        console.log(renderGrantsTable(resp));
+      }
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+}
+function registerAccess(program2, getCtx, isJson) {
+  const cmd = program2.command("access").description("Generic two-axis grant management (any entity type)");
+  cmd.command("grant").description("Grant access to a principal on an entity/object").requiredOption("--to <type:id>", "user|client|agent|group:<id>").option("--entity <entity_type>", "Entity type", DEFAULT_ENTITY).option("--object <id>", "Object id (omit for a tenant-root see-all grant)").option("--action <action>", "Action", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const principal = parsePrincipal(opts.to);
+      await grant(ctx, {
+        ...principal,
+        entityType: opts.entity,
+        action: opts.action,
+        objectId: opts.object ?? null,
+        tenant: opts.tenant
+      });
+      emitOk(json, {
+        status: "granted",
+        entity_type: opts.entity,
+        action: opts.action,
+        object_id: opts.object ?? null,
+        grantee: opts.to,
+        text: `Granted ${opts.action} on ${opts.entity}${opts.object ? ` ${opts.object}` : " (all)"} to ${opts.to}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("revoke").description("Revoke a principal's access on an entity/object").requiredOption("--to <type:id>", "user|client|agent|group:<id>").option("--entity <entity_type>", "Entity type", DEFAULT_ENTITY).option("--object <id>", "Object id (omit for the tenant-root grant)").option("--action <action>", "Action", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const principal = parsePrincipal(opts.to);
+      await revoke(ctx, {
+        ...principal,
+        entityType: opts.entity,
+        action: opts.action,
+        objectId: opts.object ?? null,
+        tenant: opts.tenant
+      });
+      emitOk(json, {
+        status: "revoked",
+        entity_type: opts.entity,
+        object_id: opts.object ?? null,
+        grantee: opts.to,
+        text: `Revoked ${opts.action} on ${opts.entity}${opts.object ? ` ${opts.object}` : " (all)"} from ${opts.to}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("list").description("List grants by-principal (--to) or by-object (--object)").option("--to <type:id>", "by-principal: this grantee's grants").option("--object <id>", "by-object: grantees of this object").option("--entity <entity_type>", "Entity type", DEFAULT_ENTITY).option("--action <action>", "Action", DEFAULT_ACTION).option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      if (!opts.to && !opts.object) {
+        throw new CLIError("Provide either --to <type:id> (by-principal) or --object <id> (by-object).", 4 /* Validation */);
+      }
+      const principal = opts.to ? parsePrincipal(opts.to) : undefined;
+      const resp = await listGrants(ctx, {
+        entityType: opts.entity,
+        action: opts.action,
+        granteeType: principal?.granteeType,
+        granteeId: principal?.granteeId,
+        objectId: opts.object,
+        tenant: opts.tenant
+      });
+      if (json) {
+        console.log(JSON.stringify(resp, null, 2));
+      } else {
+        console.log(renderGrantsTable(resp));
+      }
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+}
+function registerGroups(program2, getCtx, isJson) {
+  const cmd = program2.command("groups").description("Manage UMS-native authz groups (#644)");
+  cmd.command("create <name>").description("Create a group").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (name, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const g = await createGroup(ctx, name, opts.tenant);
+      if (json) {
+        console.log(JSON.stringify(g, null, 2));
+      } else {
+        console.log(`Created group ${source_default.bold(g.id)} (${g.name ?? name}).`);
+        console.log(source_default.dim(`Grant it a collection: martha collections grant <col> --to group:${g.id}`));
+      }
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("list").description("List groups in the tenant").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const groups = await listGroups(ctx, opts.tenant);
+      if (json) {
+        console.log(JSON.stringify(groups, null, 2));
+      } else if (groups.length === 0) {
+        console.log(source_default.dim("No groups."));
+      } else {
+        for (const g of groups) {
+          console.log(`${source_default.bold(g.id)}  ${g.name ?? ""}`);
+        }
+      }
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("delete <groupId>").description("Delete a group").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (groupId, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      await deleteGroup(ctx, groupId, opts.tenant);
+      emitOk(json, {
+        status: "deleted",
+        group_id: groupId,
+        text: `Deleted group ${groupId}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("add-member <groupId> <userSub>").description("Add a user to a group").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (groupId, userSub, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      await addMember(ctx, groupId, userSub, opts.tenant);
+      emitOk(json, {
+        status: "member_added",
+        group_id: groupId,
+        user_sub: userSub,
+        text: `Added ${userSub} to group ${groupId}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("remove-member <groupId> <userSub>").description("Remove a user from a group").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (groupId, userSub, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      await removeMember(ctx, groupId, userSub, opts.tenant);
+      emitOk(json, {
+        status: "member_removed",
+        group_id: groupId,
+        user_sub: userSub,
+        text: `Removed ${userSub} from group ${groupId}.`
+      });
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+  cmd.command("members <groupId>").description("List a group's members").option("--tenant <tenant>", "Target tenant (super-admin only)").action(async (groupId, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    try {
+      const members = await listMembers(ctx, groupId, opts.tenant);
+      if (json) {
+        console.log(JSON.stringify(members, null, 2));
+      } else if (members.length === 0) {
+        console.log(source_default.dim("No members."));
+      } else {
+        for (const m of members)
+          console.log(m);
+      }
+    } catch (err) {
+      emitAuthzError(err, json);
+    }
+  });
+}
+function emitOk(json, payload) {
+  if (json) {
+    const rest = { ...payload };
+    delete rest.text;
+    console.log(JSON.stringify(rest, null, 2));
+  } else {
+    console.log(payload.text);
+  }
+}
+
 // src/commands/init.ts
 import readline from "node:readline/promises";
 init_config();
@@ -19197,6 +19635,7 @@ registerModelsCommand(program2);
 registerSessionCommands(program2);
 registerMCPCommands(program2);
 registerPolicyCommands(program2);
+registerAuthzCommands(program2);
 registerInitCommand(program2);
 registerDoctorCommand(program2);
 registerSkillCommand(program2);

package/package.json

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