quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/role.js

@@ -0,0 +1,286 @@
+/**
+ * Role commands: org custom roles (RBAC) + agent/tool permission rules
+ *
+ * quox role list|get|create|delete
+ * quox role capability add|remove
+ * quox role agent list|set|clear
+ * quox role tool list|set|clear
+ *
+ * Backend: services/auth/routes/customRoles.js, mounted at plain `/api`
+ * (org-scoped IN the URL: /api/orgs/:orgId/custom-roles...). Enterprise-tier
+ * + ORG_MANAGE_ROLES gated — expect 402/403 on non-enterprise orgs.
+ *
+ * Capability grants are subject to a server-side privilege-escalation
+ * guard: for capabilities in the known Capabilities enum, the caller must
+ * already hold the capability themselves or the grant is rejected with
+ * `forbidden_escalation` (customRoles.js:166-188). Free-form custom
+ * capability strings bypass this check (org-defined extensions).
+ */
+
+import { formatOutput, formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerRoleCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const role = program
+    .command('role')
+    .description('Manage org custom roles (enterprise — RBAC)');
+
+  // ── role list ────────────────────────────────────────────────────────────────
+
+  role
+    .command('list')
+    .description('List custom roles for the active org')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('custom-roles.list', { orgId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = data.roles || data || [];
+
+      formatOutput({
+        columns: ['id', 'slug', 'name', 'description', 'created_at'],
+        headers: ['ID', 'Slug', 'Name', 'Description', 'Created'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No custom roles configured.' });
+    });
+
+  // ── role get ─────────────────────────────────────────────────────────────────
+
+  role
+    .command('get')
+    .description('Show a custom role and its granted capabilities')
+    .argument('<roleId>', 'role ID')
+    .action(async (roleId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('custom-roles.get', { orgId, roleId });
+      const data = await client.get(ep.path, { service: ep.service });
+
+      formatDetail(data.role || {}, {
+        format: program.opts().output,
+        title: `Role: ${data.role?.name || roleId}`,
+        fields: ['id', 'slug', 'name', 'description', 'created_at'],
+      });
+      const capabilities = data.capabilities || [];
+      if (program.opts().output !== 'json') {
+        formatOutput({
+          columns: ['capability', 'scope_id'],
+          headers: ['Capability', 'Scope'],
+          rows: capabilities,
+        }, { format: program.opts().output, emptyMessage: 'No capabilities granted.' });
+      }
+    });
+
+  // ── role create ──────────────────────────────────────────────────────────────
+
+  role
+    .command('create')
+    .description('Create a custom role')
+    .requiredOption('--slug <slug>', 'unique role slug')
+    .requiredOption('--name <name>', 'role name')
+    .option('--description <text>', 'role description')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { slug: options.slug, name: options.name };
+      if (options.description) body.description = options.description;
+
+      const ep = resolveEndpoint('custom-roles.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Role "${options.name}" created.`);
+      formatDetail(data.role || data, { format: program.opts().output });
+    });
+
+  // ── role delete ──────────────────────────────────────────────────────────────
+
+  role
+    .command('delete')
+    .description('Delete a custom role')
+    .argument('<roleId>', 'role ID')
+    .option('--force', 'skip confirmation')
+    .action(async (roleId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      if (!options.force && !program.opts().yes) {
+        const { default: inquirer } = await import('inquirer');
+        const ans = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirm',
+          message: `Delete role ${roleId}? Members assigned this role lose its capabilities immediately.`,
+          default: false,
+        }]);
+        if (!ans.confirm) {
+          printInfo('Cancelled.');
+          return;
+        }
+      }
+
+      const ep = resolveEndpoint('custom-roles.delete', { orgId, roleId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Role deleted.');
+    });
+
+  // ── role capability ─────────────────────────────────────────────────────────
+
+  const capability = role
+    .command('capability')
+    .description('Manage capability grants on a role');
+
+  capability
+    .command('add')
+    .description('Grant a capability to a role')
+    .argument('<roleId>', 'role ID')
+    .argument('<capability>', 'capability string (e.g. "agents.manage")')
+    .option('--scope-id <scopeId>', 'restrict the grant to a specific scope')
+    .action(async (roleId, cap, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { capability: cap };
+      if (options.scopeId) body.scope_id = options.scopeId;
+
+      const ep = resolveEndpoint('custom-roles.capabilities.add', { orgId, roleId });
+      await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`Capability "${cap}" granted.`);
+    });
+
+  capability
+    .command('remove')
+    .description('Revoke a capability from a role')
+    .argument('<roleId>', 'role ID')
+    .argument('<capability>', 'capability string')
+    .option('--scope-id <scopeId>', 'scope ID (must match the grant\'s scope)')
+    .action(async (roleId, cap, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { capability: cap };
+      if (options.scopeId) query.scope_id = options.scopeId;
+
+      const ep = resolveEndpoint('custom-roles.capabilities.remove', { orgId, roleId });
+      await client.delete(ep.path, { service: ep.service, query });
+      printSuccess(`Capability "${cap}" revoked.`);
+    });
+
+  // ── role agent ───────────────────────────────────────────────────────────────
+
+  const agent = role
+    .command('agent')
+    .description('Manage agent access rules on a role');
+
+  agent
+    .command('list')
+    .description('List agent access rules for a role')
+    .argument('<roleId>', 'role ID')
+    .action(async (roleId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('custom-roles.agents.list', { orgId, roleId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = data.permissions || data || [];
+
+      formatOutput({
+        columns: ['agent_id', 'scope_id', 'allowed'],
+        headers: ['Agent ID', 'Scope', 'Allowed'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No agent access rules set for this role.' });
+    });
+
+  agent
+    .command('set')
+    .description('Set (allow or deny) a role\'s access to an agent')
+    .argument('<roleId>', 'role ID')
+    .argument('<agentId>', 'agent ID')
+    .requiredOption('--allowed <bool>', 'true|false')
+    .option('--scope-id <scopeId>', 'restrict the rule to a specific scope')
+    .action(async (roleId, agentId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      if (options.allowed !== 'true' && options.allowed !== 'false') {
+        throw new Error('--allowed must be "true" or "false".');
+      }
+      const body = { agent_id: agentId, allowed: options.allowed === 'true' };
+      if (options.scopeId) body.scope_id = options.scopeId;
+
+      const ep = resolveEndpoint('custom-roles.agents.set', { orgId, roleId });
+      await client.put(ep.path, { service: ep.service, body });
+      printSuccess(`Agent access rule set (${body.allowed ? 'allowed' : 'denied'}).`);
+    });
+
+  agent
+    .command('clear')
+    .description('Remove an agent access rule from a role')
+    .argument('<roleId>', 'role ID')
+    .argument('<agentId>', 'agent ID')
+    .option('--scope-id <scopeId>', 'scope ID (must match the rule\'s scope)')
+    .action(async (roleId, agentId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { agent_id: agentId };
+      if (options.scopeId) query.scope_id = options.scopeId;
+
+      const ep = resolveEndpoint('custom-roles.agents.clear', { orgId, roleId });
+      await client.delete(ep.path, { service: ep.service, query });
+      printSuccess('Agent access rule cleared.');
+    });
+
+  // ── role tool ────────────────────────────────────────────────────────────────
+
+  const tool = role
+    .command('tool')
+    .description('Manage tool access rules on a role');
+
+  tool
+    .command('list')
+    .description('List tool access rules for a role')
+    .argument('<roleId>', 'role ID')
+    .action(async (roleId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('custom-roles.tools.list', { orgId, roleId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = data.permissions || data || [];
+
+      formatOutput({
+        columns: ['tool_id', 'allowed'],
+        headers: ['Tool ID', 'Allowed'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No tool access rules set for this role.' });
+    });
+
+  tool
+    .command('set')
+    .description('Set (allow or deny) a role\'s access to a tool')
+    .argument('<roleId>', 'role ID')
+    .argument('<toolId>', 'tool ID')
+    .requiredOption('--allowed <bool>', 'true|false')
+    .action(async (roleId, toolId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      if (options.allowed !== 'true' && options.allowed !== 'false') {
+        throw new Error('--allowed must be "true" or "false".');
+      }
+      const body = { tool_id: toolId, allowed: options.allowed === 'true' };
+
+      const ep = resolveEndpoint('custom-roles.tools.set', { orgId, roleId });
+      await client.put(ep.path, { service: ep.service, body });
+      printSuccess(`Tool access rule set (${body.allowed ? 'allowed' : 'denied'}).`);
+    });
+
+  tool
+    .command('clear')
+    .description('Remove a tool access rule from a role')
+    .argument('<roleId>', 'role ID')
+    .argument('<toolId>', 'tool ID')
+    .action(async (roleId, toolId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = { tool_id: toolId };
+
+      const ep = resolveEndpoint('custom-roles.tools.clear', { orgId, roleId });
+      await client.delete(ep.path, { service: ep.service, query });
+      printSuccess('Tool access rule cleared.');
+    });
+}

package/lib/commands/run.js

@@ -0,0 +1,132 @@
+/**
+ * Run commands: list, get, create, cancel, resume
+ */
+
+import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/output.js';
+import { resolveOrgId, parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerRunCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const run = program
+    .command('run')
+    .description('Manage workflow runs');
+
+  // fleet #465: runs live in two stores. The engine (quoxflow) is the
+  // execution store `workflow run`/apply-triggered runs actually land in;
+  // the auth-service 'runs.*' store is a separate model quoxflow never
+  // writes to. `list`/`get` below try the engine FIRST and fall back to the
+  // auth-service store, labeling which store answered.
+
+  run
+    .command('list')
+    .description('List runs')
+    .option('--status <status>', 'filter by status')
+    .option('--workflow <id>', 'filter by workflow')
+    .option('--limit <n>', 'max results', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      let rows, source;
+      try {
+        const ep = resolveEndpoint('executions.list');
+        const data = await client.get(ep.path, { service: ep.service });
+        const items = data.data || data.items || (Array.isArray(data) ? data : []);
+        rows = items.map((item) => ({ ...item, source: 'engine' }));
+        source = 'engine';
+      } catch (err) {
+        printWarning(`Engine (quoxflow) execution list failed, falling back to the auth-service store: ${err.message}`);
+        const query = { limit: options.limit };
+        if (options.status) query.status = options.status;
+        if (options.workflow) query.workflow_id = options.workflow;
+        const ep = resolveEndpoint('runs.list', { orgId });
+        const data = await client.get(ep.path, { service: ep.service, query });
+        const items = data.items || data.runs || (Array.isArray(data) ? data : []);
+        rows = items.map((item) => ({ ...item, source: 'auth' }));
+        source = 'auth';
+      }
+
+      formatOutput({
+        // fleet #392: runs table has finished_at, not completed_at.
+        columns: ['id', 'workflow_name', 'status', 'source', 'started_at', 'finished_at'],
+        headers: ['ID', 'Workflow', 'Status', 'Source', 'Started', 'Completed'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: `No results (${source} store).` });
+    });
+
+  run
+    .command('get')
+    .description('Get run details')
+    .argument('<runId>', 'run ID')
+    .action(async (runId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+
+      let data, source;
+      try {
+        const ep = resolveEndpoint('executions.get', { executionId: runId });
+        const res = await client.get(ep.path, { service: ep.service });
+        data = res.data || res;
+        source = 'engine';
+      } catch (err) {
+        if (err.status !== 404) throw err;
+        try {
+          const ep = resolveEndpoint('runs.get', { orgId, pollRunId: runId });
+          const res = await client.get(ep.path, { service: ep.service });
+          data = res.run || res;
+          source = 'auth';
+        } catch (err2) {
+          if (err2.status !== 404) throw err2;
+          throw new Error(
+            `Run "${runId}" was not found in either the engine (quoxflow) execution store or the auth-service run store.`
+          );
+        }
+      }
+
+      formatDetail({ ...data, source }, { format: program.opts().output });
+    });
+
+  run
+    .command('create')
+    .description('Start a new workflow run')
+    .requiredOption('--workflow <id>', 'workflow ID')
+    .option('--input <json>', 'input data as JSON')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = { workflow_id: options.workflow };
+      if (options.input) body.context = parseJSON(options.input, '--input');
+      const data = await client.post(resolveEndpoint('runs.create', { orgId }).path, { service: resolveEndpoint('runs.create', { orgId }).service, body });
+      printSuccess(`Run started: ${data.run?.id || data.id || 'ok'}`);
+    });
+
+  run
+    .command('cancel')
+    .description('Cancel a running workflow')
+    .argument('<runId>', 'run ID')
+    .option('--reason <text>', 'cancellation reason')
+    .action(async (runId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {};
+      if (options.reason) body.reason = options.reason;
+      await client.post(resolveEndpoint('runs.cancel', { orgId, runId }).path, { service: resolveEndpoint('runs.cancel', { orgId, runId }).service, body });
+      printSuccess('Run cancelled.');
+    });
+
+  run
+    .command('resume')
+    .description('Resume a paused run')
+    .argument('<runId>', 'run ID')
+    .option('--response <json>', 'human response payload as JSON')
+    .action(async (runId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {};
+      if (options.response) body.response = parseJSON(options.response, '--response');
+      await client.post(resolveEndpoint('runs.resume', { orgId, runId }).path, { service: resolveEndpoint('runs.resume', { orgId, runId }).service, body });
+      printSuccess('Run resumed.');
+    });
+}

package/lib/commands/safety.js

@@ -0,0 +1,107 @@
+/**
+ * Safety commands: kill switch (per-agent E-STOP) + instance DEFCON.
+ *
+ * quox safety status              org halt state: DEFCON + active E-STOPs
+ * quox safety gate <agentId>      the enforcement verdict a dispatcher sees
+ * quox safety estop <agentId>     activate the per-agent kill switch
+ * quox safety release <agentId>   release it
+ * quox safety defcon <LEVEL>      set instance DEFCON (GREEN..RED)
+ * quox safety history             append-only audit trail of every flip
+ *
+ * Backend: collector routes/safetyGate.js (quox#503, PR #505; dispatch
+ * chokepoint coverage quox#506). Mutations REQUIRE a human admin login:
+ * the server rejects agent/resident/service tokens by design, so if
+ * `estop`/`release`/`defcon` return 403 admin_required under a resident
+ * profile, that is the governance boundary working: log in as a human
+ * (`quox login`), do not look for a bypass.
+ *
+ * Closes the quox#507 parity gap: the 2026-09-02 live E-STOP proof drive
+ * had to be scripted with raw curl because these verbs did not exist.
+ */
+
+import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerSafetyCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const safety = program
+    .command('safety')
+    .description('Kill switch (per-agent E-STOP) and instance DEFCON (human-admin gated mutations)');
+
+  safety
+    .command('status')
+    .description('Org halt state: DEFCON level + active per-agent E-STOPs')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.status');
+      const data = await client.get(ep.path, { service: ep.service });
+      formatDetail(data, { format: program.opts().output });
+    });
+
+  safety
+    .command('gate')
+    .description('The enforcement verdict a dispatcher gets for this agent right now')
+    .argument('<agentId>', 'agent id, e.g. quox, sentinel')
+    .action(async (agentId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.gate', { agentId });
+      const data = await client.get(ep.path, { service: ep.service });
+      formatDetail(data, { format: program.opts().output });
+      if (data.blocked) printWarning(`Dispatch for ${agentId} is BLOCKED: ${data.reason}`);
+    });
+
+  safety
+    .command('estop')
+    .description('Activate the per-agent kill switch (HUMAN admin only, enforced server-side)')
+    .argument('<agentId>', 'agent id to halt')
+    .option('--reason <text>', 'why (lands in the audit trail)')
+    .action(async (agentId, options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.estop', { agentId });
+      const data = await client.post(ep.path, { service: ep.service, body: { reason: options.reason || null } });
+      printSuccess(`E-STOP ACTIVE for ${agentId}${data.was_active ? ' (was already active)' : ''}: new dispatch is blocked at every chokepoint; live loop sessions end at the next turn boundary.`);
+    });
+
+  safety
+    .command('release')
+    .description('Release a per-agent kill switch (HUMAN admin only, enforced server-side)')
+    .argument('<agentId>', 'agent id to release')
+    .action(async (agentId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.release', { agentId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess(`E-STOP released for ${agentId}.`);
+    });
+
+  safety
+    .command('defcon')
+    .description('Set instance DEFCON: GREEN | BLUE | AMBER | ORANGE (escalate) | RED (full halt)')
+    .argument('<level>', 'GREEN, BLUE, AMBER, ORANGE or RED')
+    .option('--reason <text>', 'why (lands in the audit trail)')
+    .action(async (level, options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.defcon');
+      const data = await client.post(ep.path, { service: ep.service, body: { level: level.toUpperCase(), reason: options.reason || null } });
+      printSuccess(`DEFCON ${data.old_level} -> ${data.new_level}.`);
+    });
+
+  safety
+    .command('history')
+    .description('Append-only audit trail of every E-STOP and DEFCON change')
+    .option('--agent <agentId>', 'filter to one agent')
+    .option('--limit <n>', 'max rows', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('safety.history');
+      const qs = new URLSearchParams();
+      if (options.agent) qs.set('agent_id', options.agent);
+      qs.set('limit', options.limit);
+      const data = await client.get(`${ep.path}?${qs}`, { service: ep.service });
+      formatOutput({
+        columns: ['created_at', 'scope', 'action', 'agent_id', 'new_value', 'actor_label', 'reason'],
+        headers: ['At', 'Scope', 'Action', 'Agent', 'Value', 'Actor', 'Reason'],
+        rows: data.history || [],
+      }, { format: program.opts().output, emptyMessage: 'No safety state changes recorded.' });
+    });
+}

package/lib/commands/scim.js

@@ -0,0 +1,88 @@
+/**
+ * SCIM commands: org SCIM bearer tokens (IdP-driven directory sync auth)
+ *
+ * quox scim tokens list|create|delete
+ *
+ * Backend: services/auth/routes/webhooks.js, mounted at plain `/api`
+ * (org-scoped IN the URL: /api/orgs/:orgId/scim/tokens...). Enterprise-tier
+ * + ORG_MANAGE_SETTINGS gated — expect 402/403 on non-enterprise orgs.
+ *
+ * The plaintext bearer token is returned ONLY on create — it is never
+ * retrievable again after that response (only its SHA-256 is stored). We
+ * print it prominently and warn the user to record it now.
+ */
+
+import { formatOutput, printSuccess, printWarning } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+function printToken(token) {
+  printWarning('Record this bearer token now — it will not be shown again:');
+  console.log(`  ${token}`);
+}
+
+export function registerScimCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const scim = program
+    .command('scim')
+    .description('Manage org SCIM bearer tokens (enterprise — IdP directory sync)');
+
+  const tokens = scim
+    .command('tokens')
+    .description('Manage SCIM bearer tokens');
+
+  // ── scim tokens list ────────────────────────────────────────────────────────
+
+  tokens
+    .command('list')
+    .description('List SCIM tokens for the active org')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('scim.tokens.list', { orgId });
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = data.tokens || data || [];
+
+      formatOutput({
+        columns: ['id', 'label', 'created_at', 'last_used_at', 'revoked_at'],
+        headers: ['ID', 'Label', 'Created', 'Last Used', 'Revoked'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No SCIM tokens configured.' });
+    });
+
+  // ── scim tokens create ──────────────────────────────────────────────────────
+
+  tokens
+    .command('create')
+    .description('Create a SCIM bearer token')
+    .option('--label <label>', 'human-readable label')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {};
+      if (options.label) body.label = options.label;
+
+      const ep = resolveEndpoint('scim.tokens.create', { orgId });
+      // NOTE: the backend response here is the raw `{ id, token }` shape,
+      // not wrapped under a named key like every other create route in
+      // this CLI — see endpoints/scim.js's header note.
+      const data = await client.post(ep.path, { service: ep.service, body });
+      printSuccess(`SCIM token created (id: ${data.id}).`);
+      if (data.token) printToken(data.token);
+    });
+
+  // ── scim tokens delete ──────────────────────────────────────────────────────
+
+  tokens
+    .command('delete')
+    .description('Revoke a SCIM token')
+    .argument('<tokenId>', 'token ID')
+    .action(async (tokenId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('scim.tokens.delete', { orgId, tokenId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('SCIM token revoked.');
+    });
+}

package/lib/commands/scope.js

@@ -0,0 +1,58 @@
+/**
+ * Scope commands
+ *
+ * quox scope list
+ *
+ * Scopes are read-only projections of the org/division/department/team
+ * hierarchy — there is no backend write route for scopes. To create,
+ * update, or delete a scope, use `quox org`, `quox division`,
+ * `quox department`, or `quox team` instead.
+ */
+
+import { formatOutput } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerScopeCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const scope = program
+    .command('scope')
+    .description('View scopes (read-only — use `quox org`/`quox division`/`quox team` to manage)');
+
+  scope
+    .command('list')
+    .description('List scopes')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // fleet #392: the route returns a nested {tree} unless flat=true is
+      // sent, and it was never sent — so `data.scopes` was undefined,
+      // `data` fell through as the object {tree: ...}, and `.map()` threw
+      // TypeError. This command crashed rather than merely showing dashes.
+      // Columns also renamed to the real ones (name_cache/scope_type);
+      // `resources` has no counterpart at all, so `path` and `depth` are
+      // shown instead of inventing a zero.
+      const data = await client.get(resolveEndpoint('scopes.list', { orgId }).path, {
+        service: resolveEndpoint('scopes.list', { orgId }).service,
+        query: { flat: 'true' },
+      });
+      const scopes = Array.isArray(data.scopes) ? data.scopes : [];
+      // fleet #399.3: `depth` is a scope-TYPE ordinal (services/auth/
+      // migrations/000-baseline.sql: "0=org, 1=division, 2=department,
+      // 3=team"), not a count of path segments below root. A team can
+      // legitimately show Depth 3 while its `path` reads only two levels
+      // deep. Header made self-explanatory rather than recomputing depth.
+      formatOutput({
+        columns: ['id', 'name', 'type', 'path', 'depth'],
+        headers: ['ID', 'Name', 'Type', 'Path', 'Depth (0=org,1=div,2=dept,3=team)'],
+        rows: scopes.map(s => ({
+          id: s.id,
+          name: s.name_cache,
+          type: s.scope_type,
+          path: s.path,
+          depth: s.depth,
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No scopes found.' });
+    });
+}