@indigoai-us/hq-cli 5.51.0 → 5.52.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.52.0]
+
+### Added
+
+- **`hq members promote <target> <newRole>` (alias `set-role`) — change a
+  member's role from the CLI.** A discoverable runner for role changes via
+  `POST /membership/role`, replacing the undiscoverable, `admin|member`-only
+  `set-role` (now kept as an alias). Supports the full role set
+  (`owner|admin|member|guest`); `<target>` may be an email, a `prs_` personUid,
+  or a full membership key (same resolver as `revoke`). It is a GENERAL role
+  change — it can promote OR demote — and authorization (owner-or-admin; only
+  an owner may set a target to owner or change an owner) is enforced
+  server-side.
+- **`hq files share --full` — glob-safe whole-vault access.** Granting prefixes
+  one at a time hit `PolicyBudgetExceeded` after a few (each prefix is a
+  distinct ARN in the member's DEFLATE-packed inline STS session policy), and
+  the intended single-`*` wildcard escape hatch was unreachable because an
+  unquoted `*` expands to local filenames and fails the one-prefix check.
+  `--full` is a glob-safe flag that performs the coalesced whole-vault wildcard
+  grant in a single policy entry.
+
+## [5.51.0]
+
 ### Fixed
 
 - **`hq secrets exec` / `hq secrets env` load via the batch endpoint, killing

package/dist/commands/files.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bc564dd4-d8c1-5d09-ad49-3bcd9f7328a6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fc999359-c426-5277-ba96-5452ae1ed2e2")}catch(e){}}();
 import chalk from "chalk";
 import open from "open";
 import * as readline from "node:readline";
@@ -99,10 +99,35 @@ export function registerFilesCommand(program) {
         .description("Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
         .option("--with <principal>", "Email address, group id, or '@all' to share with every active company member")
         .option("--permission <level>", "Permission level (only with --with): read | write")
+        .option("--full", "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.")
         .option("--expires <duration>", "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.")
         .option("--no-open", "Print the share-session URL but do not launch the browser")
         .action(async (paths, opts) => {
         try {
+            // Full-vault grant: a glob-safe affordance for "give this person the
+            // whole vault" so admins never have to quote a `*` (an unquoted glob
+            // expands to local filenames and instantly fails the one-prefix
+            // check). Maps to the single `*` wildcard grant, which the server
+            // coalesces to one policy entry — sidestepping the per-prefix STS
+            // session-policy budget. Defaults to write permission.
+            if (opts.full) {
+                if (opts.with === undefined) {
+                    console.error(chalk.red("--full grants whole-vault access to a principal and requires --with <principal>."));
+                    process.exit(1);
+                }
+                if (paths && paths.length > 0) {
+                    console.error(chalk.red("--full grants the entire vault; do not also pass file paths."));
+                    process.exit(1);
+                }
+                await runDirectGrant({
+                    prefix: "*",
+                    principal: opts.with,
+                    permission: opts.permission ?? "write",
+                    companySlug: files.opts().company,
+                    fullVault: true,
+                });
+                return;
+            }
             if (!paths || paths.length === 0) {
                 console.error(chalk.red("usage: hq files share <paths...> [--with <principal>]"));
                 process.exit(1);
@@ -437,7 +462,12 @@ async function runDirectGrant(params) {
     const data = (await res.json());
     const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
     const verb = autoCreated ? "Created ACL and granted" : "Granted";
-    console.log(chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`));
+    if (params.fullVault) {
+        console.log(chalk.green(`${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`));
+    }
+    else {
+        console.log(chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`));
+    }
 }
 async function runShareSession(params) {
     // Normalize every path through the shared prefix helper so a trailing
@@ -682,4 +712,4 @@ export async function runFilesDelete(params, deps = {}) {
     }
 }
 //# sourceMappingURL=files.js.map
-//# debugId=bc564dd4-d8c1-5d09-ad49-3bcd9f7328a6
+//# debugId=fc999359-c426-5277-ba96-5452ae1ed2e2

package/dist/commands/members.d.ts

@@ -149,5 +149,15 @@ export declare function listActiveMembers(token: string, companyUid: string): Pr
  */
 export declare function resolveRevokeTargetToMembershipKey(arg: string, companyUid: string): string;
 export declare function revokeInvite(token: string, tokenOrKey: string, companyUid: string): Promise<void>;
+/**
+ * Change a member's role via `POST /membership/role`, accepting the FULL role
+ * set (owner|admin|member|guest). This is a GENERAL role change — it can promote
+ * OR demote. Authorization (owner-or-admin `changeRoles`, owner-only
+ * promote-to-owner / change-an-owner) is enforced SERVER-side; this function
+ * only validates the role string locally and surfaces the server's error.
+ * Role string is validated BEFORE any network call so callers/tests can rely on
+ * a synchronous-shaped rejection for a bad role.
+ */
+export declare function changeMemberRole(token: string, companyUid: string, membershipKey: string, newRole: Role): Promise<void>;
 export declare function registerMembersCommand(program: Command): void;
 //# sourceMappingURL=members.d.ts.map

package/dist/commands/members.js

@@ -1,12 +1,11 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8244d720-094e-5d4e-b813-75086ed0849d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="83a54ed2-3f52-5b6f-a784-09f78f488ddd")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
-const VALID_MEMBER_SET_ROLES = new Set(["admin", "member"]);
 export function detectTarget(target) {
     if (EMAIL_PATTERN.test(target)) {
         return { type: "email", value: target.trim().toLowerCase() };
@@ -265,9 +264,18 @@ export async function revokeInvite(token, tokenOrKey, companyUid) {
         throw new InviteHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
     }
 }
-async function setMemberRole(token, companyUid, membershipKey, newRole) {
-    if (!VALID_MEMBER_SET_ROLES.has(newRole)) {
-        throw new Error(`Invalid role '${newRole}': must be one of admin, member`);
+/**
+ * Change a member's role via `POST /membership/role`, accepting the FULL role
+ * set (owner|admin|member|guest). This is a GENERAL role change — it can promote
+ * OR demote. Authorization (owner-or-admin `changeRoles`, owner-only
+ * promote-to-owner / change-an-owner) is enforced SERVER-side; this function
+ * only validates the role string locally and surfaces the server's error.
+ * Role string is validated BEFORE any network call so callers/tests can rely on
+ * a synchronous-shaped rejection for a bad role.
+ */
+export async function changeMemberRole(token, companyUid, membershipKey, newRole) {
+    if (!VALID_ROLES.has(newRole)) {
+        throw new Error(`Invalid role '${newRole}': must be one of owner, admin, member, guest`);
     }
     const res = await vaultApiFetch({
         token,
@@ -285,16 +293,29 @@ export function registerMembersCommand(program) {
         .command("members")
         .description("Manage company memberships and invites")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
+    // Canonical role-change command. `promote` is the discoverable verb users
+    // reach for; `set-role` is kept as an alias for the older name. The route is a
+    // GENERAL role change, so the help text and success message are honest that it
+    // can demote as well as promote. Authorization is enforced server-side.
     members
-        .command("set-role <membershipKey> <role>")
-        .description("Change a member or agent role to admin or member")
-        .action(async (membershipKey, role) => {
+        .command("promote <target> <newRole>")
+        .alias("set-role")
+        .description("Change a member's role (owner|admin|member|guest) — promotes OR demotes. " +
+        "<target> may be an email, a prs_ personUid, or a full membership key. " +
+        "Owner-or-admin only; setting a target to owner (or changing an owner) is owner-only. Server-enforced.")
+        .action(async (target, newRole) => {
         try {
+            const role = newRole.trim().toLowerCase();
+            if (!VALID_ROLES.has(role)) {
+                console.error(chalk.red(`Invalid role '${newRole}': must be one of owner, admin, member, guest`));
+                process.exit(1);
+            }
             const token = await ensureCognitoToken();
             const companySlug = members.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
-            await setMemberRole(token, companyUid, membershipKey, role);
-            console.log(chalk.green(`Updated role for '${membershipKey}' to ${role}`));
+            const membershipKey = resolveRevokeTargetToMembershipKey(target, companyUid);
+            await changeMemberRole(token, companyUid, membershipKey, role);
+            console.log(chalk.green(`Updated role for '${target}' to ${role}`));
         }
         catch (err) {
             if (err instanceof InviteHttpError) {
@@ -534,4 +555,4 @@ export function registerMembersCommand(program) {
     });
 }
 //# sourceMappingURL=members.js.map
-//# debugId=8244d720-094e-5d4e-b813-75086ed0849d
+//# debugId=83a54ed2-3f52-5b6f-a784-09f78f488ddd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.51.0",
+  "version": "5.52.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/files.test.ts

@@ -501,6 +501,136 @@ describe("hq files share — direct-grant fork (with --with)", () => {
     expect(errs).toMatch(/--permission is required/);
     expect(fetchSpy).not.toHaveBeenCalled();
   });
+
+  it("--full --with email grants the '*' wildcard at the default write permission (no glob to quote)", async () => {
+    // 1) /membership/me for company resolution
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/acl/grant
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { acl: { path: "*" } }),
+    );
+
+    const program = buildProgram();
+    // No positional path, no --permission — --full supplies prefix '*' and
+    // defaults permission to write.
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com"],
+      { from: "user" },
+    );
+
+    const mintCalls = fetchSpy.mock.calls.filter((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCalls).toHaveLength(0);
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    expect(grantCall).toBeDefined();
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "write",
+    });
+
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/ENTIRE vault/);
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("--full honors an explicit --permission read (read-only full vault)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com", "--permission", "read"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "read",
+    });
+  });
+
+  it("--full composes with @all (whole vault for the whole company → company-wide '*')", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "@all"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "company-wide",
+      granteeId: "",
+      permission: "write",
+    });
+  });
+
+  it("rejects --full without --with (and never calls the network)", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "share", "--full"], { from: "user" }),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/--full.*requires --with/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects --full when file paths are also passed", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "somePath", "--full", "--with", "user@example.com"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/entire vault; do not also pass file paths/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/commands/files.ts

@@ -135,6 +135,10 @@ export function registerFilesCommand(program: Command): Command {
       "Email address, group id, or '@all' to share with every active company member",
     )
     .option("--permission <level>", "Permission level (only with --with): read | write")
+    .option(
+      "--full",
+      "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.",
+    )
     .option(
       "--expires <duration>",
       "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.",
@@ -146,11 +150,45 @@ export function registerFilesCommand(program: Command): Command {
         opts: {
           with?: string;
           permission?: string;
+          full?: boolean;
           expires?: string;
           open: boolean;
         },
       ) => {
         try {
+          // Full-vault grant: a glob-safe affordance for "give this person the
+          // whole vault" so admins never have to quote a `*` (an unquoted glob
+          // expands to local filenames and instantly fails the one-prefix
+          // check). Maps to the single `*` wildcard grant, which the server
+          // coalesces to one policy entry — sidestepping the per-prefix STS
+          // session-policy budget. Defaults to write permission.
+          if (opts.full) {
+            if (opts.with === undefined) {
+              console.error(
+                chalk.red(
+                  "--full grants whole-vault access to a principal and requires --with <principal>.",
+                ),
+              );
+              process.exit(1);
+            }
+            if (paths && paths.length > 0) {
+              console.error(
+                chalk.red(
+                  "--full grants the entire vault; do not also pass file paths.",
+                ),
+              );
+              process.exit(1);
+            }
+            await runDirectGrant({
+              prefix: "*",
+              principal: opts.with,
+              permission: opts.permission ?? "write",
+              companySlug: files.opts().company as string | undefined,
+              fullVault: true,
+            });
+            return;
+          }
+
           if (!paths || paths.length === 0) {
             console.error(
               chalk.red("usage: hq files share <paths...> [--with <principal>]"),
@@ -472,6 +510,12 @@ interface DirectGrantParams {
   principal: string;
   permission: string | undefined;
   companySlug: string | undefined;
+  /**
+   * Set by the `--full` affordance: the grant targets the whole vault (the
+   * `*` wildcard prefix). Only affects the success message wording — the
+   * request shape is identical to any other prefix grant.
+   */
+  fullVault?: boolean;
 }
 
 async function runDirectGrant(params: DirectGrantParams): Promise<void> {
@@ -572,9 +616,17 @@ async function runDirectGrant(params: DirectGrantParams): Promise<void> {
   };
   const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
   const verb = autoCreated ? "Created ACL and granted" : "Granted";
-  console.log(
-    chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
-  );
+  if (params.fullVault) {
+    console.log(
+      chalk.green(
+        `${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`,
+      ),
+    );
+  } else {
+    console.log(
+      chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/members.test.ts

@@ -34,6 +34,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import {
   InviteHttpError,
+  changeMemberRole,
   detectTarget,
   formatInviteHttpError,
   getCallerPersonUid,
@@ -998,6 +999,121 @@ describe("registerMembersCommand set-role", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// changeMemberRole + the unified `promote` command (alias `set-role`)
+// ---------------------------------------------------------------------------
+
+describe("changeMemberRole", () => {
+  it("rejects an invalid role WITHOUT making a network call", async () => {
+    await expect(
+      changeMemberRole(
+        "test-token",
+        "cmp_acme",
+        "prs_x#cmp_acme",
+        "superuser" as never,
+      ),
+    ).rejects.toThrow("must be one of owner, admin, member, guest");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("accepts the full role set and POSTs to /membership/role", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await changeMemberRole("test-token", "cmp_acme", "prs_x#cmp_acme", "guest");
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/role$/);
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "prs_x#cmp_acme",
+      newRole: "guest",
+    });
+  });
+});
+
+describe("registerMembersCommand promote", () => {
+  it("resolves an email target and promotes to a full-set role the old set-role couldn't (admin)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "promote", "alice@example.com", "admin"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/role$/);
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "email:alice@example.com#cmp_acme",
+      newRole: "admin",
+    });
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Updated role for 'alice@example.com' to admin"),
+    );
+  });
+
+  it("forwards a personUid target and the guest role (beyond set-role's admin|member cap)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "promote", "prs_bob", "guest"],
+      { from: "user" },
+    );
+
+    const body = JSON.parse(
+      (fetchSpy.mock.calls[0]?.[1]?.body as string) ?? "{}",
+    );
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "prs_bob#cmp_acme",
+      newRole: "guest",
+    });
+  });
+
+  it("rejects an invalid role at the CLI and exits non-zero without a network call", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+
+    await expect(
+      buildMembersProgram().parseAsync(
+        ["members", "--company", "acme", "promote", "alice@example.com", "wizard"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow("__EXIT__:1");
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("must be one of owner, admin, member, guest"),
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a backend 403 verbatim (server-enforced authorization)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "Only an owner may promote a member to owner" }),
+    );
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.spyOn(console, "log").mockImplementation(() => undefined);
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+
+    await expect(
+      buildMembersProgram().parseAsync(
+        ["members", "--company", "acme", "promote", "prs_bob", "owner"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow("__EXIT__:1");
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Only an owner may promote a member to owner"),
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // resolveRevokeTargetToMembershipKey
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -6,10 +6,8 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
-const VALID_MEMBER_SET_ROLES = new Set(["admin", "member"]);
 
 export type Role = "owner" | "admin" | "member" | "guest";
-type MemberSetRole = "admin" | "member";
 
 export interface PendingInvite {
   membershipKey: string;
@@ -498,15 +496,24 @@ export async function revokeInvite(
   }
 }
 
-async function setMemberRole(
+/**
+ * Change a member's role via `POST /membership/role`, accepting the FULL role
+ * set (owner|admin|member|guest). This is a GENERAL role change — it can promote
+ * OR demote. Authorization (owner-or-admin `changeRoles`, owner-only
+ * promote-to-owner / change-an-owner) is enforced SERVER-side; this function
+ * only validates the role string locally and surfaces the server's error.
+ * Role string is validated BEFORE any network call so callers/tests can rely on
+ * a synchronous-shaped rejection for a bad role.
+ */
+export async function changeMemberRole(
   token: string,
   companyUid: string,
   membershipKey: string,
-  newRole: MemberSetRole,
+  newRole: Role,
 ): Promise<void> {
-  if (!VALID_MEMBER_SET_ROLES.has(newRole)) {
+  if (!VALID_ROLES.has(newRole)) {
     throw new Error(
-      `Invalid role '${newRole}': must be one of admin, member`,
+      `Invalid role '${newRole}': must be one of owner, admin, member, guest`,
     );
   }
 
@@ -532,23 +539,41 @@ export function registerMembersCommand(program: Command): void {
     .description("Manage company memberships and invites")
     .option("--company <slug>", "Company slug (resolves to companyUid)");
 
+  // Canonical role-change command. `promote` is the discoverable verb users
+  // reach for; `set-role` is kept as an alias for the older name. The route is a
+  // GENERAL role change, so the help text and success message are honest that it
+  // can demote as well as promote. Authorization is enforced server-side.
   members
-    .command("set-role <membershipKey> <role>")
-    .description("Change a member or agent role to admin or member")
-    .action(async (membershipKey: string, role: string) => {
+    .command("promote <target> <newRole>")
+    .alias("set-role")
+    .description(
+      "Change a member's role (owner|admin|member|guest) — promotes OR demotes. " +
+        "<target> may be an email, a prs_ personUid, or a full membership key. " +
+        "Owner-or-admin only; setting a target to owner (or changing an owner) is owner-only. Server-enforced.",
+    )
+    .action(async (target: string, newRole: string) => {
       try {
+        const role = newRole.trim().toLowerCase();
+        if (!VALID_ROLES.has(role)) {
+          console.error(
+            chalk.red(
+              `Invalid role '${newRole}': must be one of owner, admin, member, guest`,
+            ),
+          );
+          process.exit(1);
+        }
+
         const token = await ensureCognitoToken();
         const companySlug = members.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
-
-        await setMemberRole(
-          token,
+        const membershipKey = resolveRevokeTargetToMembershipKey(
+          target,
           companyUid,
-          membershipKey,
-          role as MemberSetRole,
         );
+
+        await changeMemberRole(token, companyUid, membershipKey, role as Role);
         console.log(
-          chalk.green(`Updated role for '${membershipKey}' to ${role}`),
+          chalk.green(`Updated role for '${target}' to ${role}`),
         );
       } catch (err) {
         if (err instanceof InviteHttpError) {