unbound-cli 1.16.19 → 1.16.21

package/README.md

@@ -32,7 +32,7 @@ unbound setup cursor
 
 ## Onboarding (one command)
 
-For new users, the fastest path from install to a fully-configured device is the `onboard` command. It logs you in, installs the default tool bundle (Cursor, Claude Code hooks, Codex hooks), and runs device discovery — all in one step.
+For new users, the fastest path from install to a fully-configured device is the `onboard` command. It logs you in, installs the default tool bundle (Cursor, Claude Code hooks, Codex hooks), and runs device discovery — all in one step. Pi Coding Agent is also set up, after the bundle, when pi is already installed on the device, and is skipped otherwise (`unbound setup pi` sets it up regardless). A failed Pi setup does not stop discovery.
 
 ```bash
 # End user
@@ -242,6 +242,28 @@ Alias: `unbound groups` works the same as `unbound user-groups`.
 
 Supported tool types: `CLAUDE_CODE`, `CURSOR`, `COPILOT`, `AUGMENT_CODE`, `ROO_CODE`, `CLINE`, `GEMINI_CLI`, `CODEX`, `KILO_CODE`, `CUSTOM_ACCESS`
 
+### Flags and False Positives
+
+Listing needs Admin, Manager or Analytics Viewer. `mark-fp` needs Admin.
+
+| Command | Description |
+|---------|-------------|
+| `unbound flags terminal` | Terminal runs that a tool policy flagged (block, approval, warn, audit) |
+| `unbound flags terminal mark-fp <id> --risk-score <n>` | Reject the run's risk score as a false positive |
+| `unbound flags data-security` | PII and secrets a guardrail found (values masked; `--reveal` shows them) |
+| `unbound flags data-security mark-fp <action-id>` | Mark a detection as a false positive |
+| `unbound trace <trace-id>` | The log, terminal runs and data security detections for one trace ID (prompts and values hidden; `--reveal` shows them) |
+
+```bash
+unbound flags terminal --action block,warn --time-window SEVEN_DAYS
+unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Our build script"
+unbound flags data-security --guardrail Secrets --findings all
+unbound flags data-security mark-fp 5521
+unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --json
+```
+
+Terminal `mark-fp` records the same feedback as rejecting a risk score in the dashboard. It does not hide the run. Data security `mark-fp` moves the detection to `--findings false-positive`, and the gateway then skips that value for the organization.
+
 ## Configuration
 
 Config is stored in `~/.unbound/config.json`. For tenant deployments, point the CLI at your own hosts in one command (recommended for new installs):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.16.19",
+  "version": "1.16.21",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/commands/flags.js

@@ -0,0 +1,253 @@
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+const { buildQueryString, TIME_WINDOWS, DEFAULT_TIME_WINDOW } = require('../lib/analytics-query');
+const {
+  DATA_SECURITY_ACTIONS,
+  DATA_SECURITY_HEADERS,
+  FINDINGS,
+  TERMINAL_ACTIONS,
+  TERMINAL_HEADERS,
+  buildDataSecurityQuery,
+  buildTerminalQuery,
+  dataSecurityRows,
+  redactDataSecurityLog,
+  resolveGuardrailIds,
+  terminalRows,
+} = require('../lib/flags');
+
+const TERMINAL_PATH = '/api/v1/analytics/terminal_commands/';
+const DATA_SECURITY_PATH = '/api/v1/analytics/guardrails/';
+const GUARDRAIL_FILTERS_PATH = '/api/v1/analytics/guardrails/filters/';
+const FEEDBACK_PATH = '/api/v1/analytics/feedback/';
+const MARK_FP_PATH = '/api/v1/analytics/guardrails/mark_false_positive/';
+
+const WINDOW_HELP = `
+TIME RANGE
+  --time-window <w>   ${TIME_WINDOWS.join(' | ')}
+                      Default ${DEFAULT_TIME_WINDOW}.
+  --start, --end      Custom range as YYYY-MM-DD (max 90 days). Not with --time-window.
+`;
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    throw new Error('Not logged in. Run `unbound login` first.');
+  }
+}
+
+async function run(fn) {
+  try {
+    requireLogin();
+    await fn();
+  } catch (err) {
+    output.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+function addWindowOptions(command) {
+  return command
+    .option('--time-window <window>', `Preset window (default ${DEFAULT_TIME_WINDOW})`)
+    .option('--start <date>', 'Custom range start, YYYY-MM-DD (use with --end)')
+    .option('--end <date>', 'Custom range end, YYYY-MM-DD (use with --start)');
+}
+
+function pageFooter(page, totalPages, total, noun, hasMore) {
+  console.log('');
+  if (total !== undefined) {
+    output.info(`Page ${page} of ${Math.max(totalPages || 1, 1)} (${Number(total).toLocaleString()} ${noun}).`);
+  }
+  if (hasMore) output.info(`Next page: --page ${page + 1}`);
+}
+
+function parsePositiveInt(flag, value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`Invalid ${flag} "${value}". Must be a positive integer.`);
+  return n;
+}
+
+async function listTerminal(opts) {
+  const query = buildTerminalQuery(opts);
+  const data = await api.get(`${TERMINAL_PATH}?${buildQueryString(query)}`);
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  const rows = data.terminal_commands || [];
+  if (rows.length === 0) {
+    output.info('No flagged terminal runs for this window and filter set.');
+    return;
+  }
+  output.logTable(TERMINAL_HEADERS, terminalRows(rows, { wide: Boolean(opts.wide) }), { wide: Boolean(opts.wide) });
+  pageFooter(query.page, data.total_pages, data.total_count, 'flagged runs', data.has_more);
+  output.info('Mark one as a false positive: unbound flags terminal mark-fp <ID> --risk-score <Risk>');
+}
+
+async function markTerminalFalsePositive(id, opts) {
+  const riskScore = Number(opts.riskScore);
+  if (!Number.isInteger(riskScore) || riskScore < 1 || riskScore > 10) {
+    throw new Error(`Invalid --risk-score "${opts.riskScore}". Must be an integer from 1 to 10 (the Risk column).`);
+  }
+  const body = {
+    prompt_analytics_id: parsePositiveInt('ID', id),
+    analytics_type: 'terminal_command',
+    feedback_type: 'reject',
+    risk_score: riskScore,
+  };
+  if (opts.comment !== undefined) body.comment = opts.comment;
+  const data = await api.post(FEEDBACK_PATH, { body });
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  output.success(`Terminal run ${id} marked as a false positive (feedback ${data.action || 'saved'}).`);
+}
+
+async function listDataSecurity(opts) {
+  let guardrailIds = [];
+  if (opts.guardrail) {
+    const filters = await api.get(GUARDRAIL_FILTERS_PATH);
+    guardrailIds = resolveGuardrailIds(opts.guardrail, filters.guardrails);
+  }
+  const query = buildDataSecurityQuery(opts, guardrailIds);
+  const data = await api.get(`${DATA_SECURITY_PATH}?${buildQueryString(query)}`);
+  const logs = (data.logs && data.logs.data) || [];
+  if (opts.json) {
+    const payload = opts.reveal ? data : { ...data, logs: { ...data.logs, data: logs.map(redactDataSecurityLog) } };
+    output.json(payload);
+    return;
+  }
+  if (logs.length === 0) {
+    output.info('No data security flags for this window and filter set.');
+    return;
+  }
+  output.logTable(DATA_SECURITY_HEADERS, dataSecurityRows(logs, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    { wide: Boolean(opts.wide) });
+  const totalPages = data.logs.total_pages;
+  pageFooter(query.page, totalPages, data.logs.total_items, 'flagged requests', query.page < (totalPages || 0));
+  if (!opts.reveal) output.info('Detected values are masked. Use --reveal to show them.');
+  output.info('Mark one as a false positive: unbound flags data-security mark-fp <Action ID>');
+}
+
+async function markDataSecurityFalsePositive(id, opts) {
+  const data = await api.post(MARK_FP_PATH, { body: { guardrail_action_id: parsePositiveInt('Action ID', id) } });
+  if (opts.json) {
+    output.json(data);
+    return;
+  }
+  output.success(`Data security detection ${id} marked as a false positive.`);
+}
+
+function register(program) {
+  const flags = program
+    .command('flags')
+    .description('Review what your policies flagged, and mark false positives.')
+    .addHelpText('after', `
+KINDS
+  terminal        Terminal commands that matched a tool policy (block, approval, warn, audit)
+  data-security   Prompts where a data security guardrail found PII or a secret
+
+Examples:
+  $ unbound flags terminal
+  $ unbound flags terminal --action block --time-window SEVEN_DAYS
+  $ unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Expected cleanup script"
+  $ unbound flags data-security --guardrail Secrets
+  $ unbound flags data-security mark-fp 5521
+
+  Search every source for one trace ID with \`unbound trace <trace-id>\`.
+`);
+
+  const terminal = flags
+    .command('terminal')
+    .description('List terminal runs that a tool policy flagged (Analytics > Tool Use > Terminal Runs).')
+    .option('--action <actions>', `Policy outcome, comma-separated: ${TERMINAL_ACTIONS.join(', ')} (default: all)`)
+    .option('--policy <ids>', 'Tool policy IDs, comma-separated (see `unbound policy tool list`)')
+    .option('--trace <trace-id>', 'Only the run with this gateway trace ID')
+    .option('--tool <types>', 'AI tool type, comma-separated, e.g. CLAUDE_CODE,CURSOR')
+    .option('--family <families>', 'Command family, comma-separated')
+    .option('--page <n>', 'Page number (10 runs per page)')
+    .option('--json', 'Output the raw JSON response')
+    .option('--wide', 'Print full values instead of clipping to terminal width');
+  addWindowOptions(terminal)
+    .addHelpText('after', `
+Columns:
+  ID        The run's ID. Pass it to \`mark-fp\`.
+  Outcome   The strongest action across the matched policies.
+  Risk      The risk score. \`mark-fp\` records it with the dispute.
+  Feedback  Your earlier feedback on this run, if any.
+${WINDOW_HELP}
+Examples:
+  $ unbound flags terminal
+  $ unbound flags terminal --action block,warn --policy 12
+  $ unbound flags terminal --trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c
+  $ unbound flags terminal --page 2 --json
+
+Admin, Manager or Analytics Viewer.
+`)
+    .action((opts) => run(() => listTerminal(opts)));
+
+  terminal
+    .command('mark-fp <id>')
+    .description('Mark a flagged terminal run as a false positive (reject its risk score).')
+    .requiredOption('--risk-score <n>', 'The Risk value shown for the run (1-10)')
+    .option('--comment <text>', 'Why this run is a false positive')
+    .option('--json', 'Output the raw JSON response')
+    .addHelpText('after', `
+Records your feedback that the run was not risky. This is the same feedback as
+rejecting a risk score in the dashboard. It does not hide the run or change the
+policy. Running it again updates your earlier feedback.
+
+Examples:
+  $ unbound flags terminal mark-fp 81234 --risk-score 8
+  $ unbound flags terminal mark-fp 81234 --risk-score 8 --comment "Our build script"
+
+Admin only.
+`)
+    .action((id, opts) => run(() => markTerminalFalsePositive(id, opts)));
+
+  const dataSecurity = flags
+    .command('data-security')
+    .description('List prompts where a data security guardrail found PII or a secret (Analytics > Data Security).')
+    .option('--guardrail <names>', 'Guardrail names or IDs, comma-separated, e.g. PII,Secrets')
+    .option('--action <actions>', `Action taken, comma-separated: ${DATA_SECURITY_ACTIONS.join(', ')}`)
+    .option('--findings <which>', `${Object.keys(FINDINGS).join(' | ')} (default real)`)
+    .option('--trace <trace-id>', 'Only the request with this gateway trace ID (default --findings all)')
+    .option('--reveal', 'Show detected values and prompts in clear text')
+    .option('--page <n>', 'Page number (10 requests per page)')
+    .option('--json', 'Output the JSON response (values masked unless --reveal)')
+    .option('--wide', 'Print full values instead of clipping to terminal width');
+  addWindowOptions(dataSecurity)
+    .addHelpText('after', `
+Columns:
+  Action ID  The detection's ID. Pass it to \`mark-fp\`.
+  Value      The detected value, masked unless --reveal.
+${WINDOW_HELP}
+Examples:
+  $ unbound flags data-security
+  $ unbound flags data-security --guardrail Secrets --action block
+  $ unbound flags data-security --findings false-positive
+  $ unbound flags data-security --trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --reveal
+
+Admin, Manager or Analytics Viewer.
+`)
+    .action((opts) => run(() => listDataSecurity(opts)));
+
+  dataSecurity
+    .command('mark-fp <action-id>')
+    .description('Mark a data security detection as a false positive.')
+    .option('--json', 'Output the raw JSON response')
+    .addHelpText('after', `
+The detection moves to --findings false-positive. The gateway then skips the
+same value for everyone in your organization.
+
+Examples:
+  $ unbound flags data-security mark-fp 5521
+
+Admin only.
+`)
+    .action((id, opts) => run(() => markDataSecurityFalsePositive(id, opts)));
+
+  return flags;
+}
+
+module.exports = { register };

package/src/commands/onboard.js

@@ -3,8 +3,9 @@ const config = require('../config');
 const output = require('../output');
 const telemetry = require('../telemetry');
 const { ensureLoggedIn, fetchDeviceOwnerKey } = require('../auth');
-const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, elevated, scopeNotice, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
+const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, elevated, scopeNotice, ALL_TOOLS, MDM_ALL_TOOLS, SETUP_TOOL_MAP, MDM_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
+const toolDetect = require('../toolDetect');
 
 /**
  * Builds the recovery-command suffix for partial-failure hints.
@@ -17,6 +18,34 @@ function domainHintSuffix(domain) {
   return ` --domain ${domain}`;
 }
 
+/**
+ * Whether onboarding should also set up Pi: only when pi is present on the
+ * device. Pi is the one tool onboarding installs only where it is already in
+ * use. A check that could not be completed counts as detected, so a device is
+ * never left ungoverned because the check itself broke.
+ */
+function shouldSetUpPi(label, { allUsers }) {
+  let detected;
+  try {
+    detected = toolDetect.detectInstalledTools(['pi'], { allUsers }).detected.includes('pi');
+  } catch (err) {
+    telemetry.captureError(err, { tags: { flow: 'onboard-detect' } });
+    output.warn(`Could not check whether ${label} is installed — setting it up anyway.`);
+    return true;
+  }
+  if (!detected) {
+    console.log(output.colors.dim(`  ${label} not detected — skipped (run \`unbound setup pi\` to set it up regardless)`));
+    return false;
+  }
+  output.info(`${label} detected — setting it up after the bundle`);
+  return true;
+}
+
+/** The command that retries a failed Pi setup in this scope. */
+function piRetryCommand(isMdm) {
+  return isMdm ? elevated('unbound setup --api-key <ADMIN_KEY> pi') : 'unbound setup pi';
+}
+
 function register(program) {
   const onboard = program
     .command('onboard')
@@ -39,6 +68,8 @@ Runs the full onboarding flow, auto-detecting scope from your privileges:
   With sudo, installs the MDM tool bundle (${MDM_ALL_TOOLS.join(', ')}) and scans
   every user on the device. Without sudo, installs the user bundle
   (${ALL_TOOLS.join(', ')}) and scans just the current user.
+  Pi Coding Agent (pi) is also set up, after the bundle, only when pi is detected
+  on the device; use \`unbound setup pi\` to set it up regardless.
 
   1. Logs in / resolves the API key (or reuses a stored \`unbound login\` key
      when --api-key is omitted).
@@ -82,6 +113,7 @@ Examples:
       let discoverySucceeded = false;
       let discoveryDomain;
       let skippedTools;
+      let piFailed = false;
       let mdmScanKey;  // device-owner key resolved from the serial (MDM scope only)
       try {
         // Persist URLs first, then login, then setup — order matters so the
@@ -120,6 +152,7 @@ Examples:
 
           console.log('');
           output.info('Step 1/2: Installing MDM tool bundle (all users)');
+          const setUpPi = shouldSetUpPi(MDM_TOOLS.pi.label, { allUsers: true });
           const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
@@ -128,6 +161,14 @@ Examples:
           // non-zero exit explicit here so onboard never returns 0 on failure.
           if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
+          // Pi runs on its own so a failure there cannot cost the device its
+          // bundle, its discovery scan or its scheduled run.
+          if (setUpPi) {
+            const pi = await runMdmSetupAllBundle(adminApiKey, {
+              backendUrl, frontendUrl, gatewayUrl, tools: ['pi'],
+            });
+            piFailed = !pi.ok;
+          }
 
           console.log('');
           output.info('Step 2/2: Running device discovery');
@@ -145,6 +186,7 @@ Examples:
 
           console.log('');
           output.info('Step 1/2: Installing tool bundle');
+          const setUpPi = shouldSetUpPi(SETUP_TOOL_MAP.pi.label, { allUsers: false });
           const { ok, skipped } = await runSetupAllBundle(apiKey, {
             backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
           });
@@ -153,6 +195,14 @@ Examples:
           // non-zero exit explicit here so onboard never returns 0 on failure.
           if (!ok) { process.exitCode = 1; return; }
           setupSucceeded = true;
+          // Pi runs on its own so a failure there cannot cost the device its
+          // bundle, its discovery scan or its scheduled run.
+          if (setUpPi) {
+            const pi = await runSetupAllBundle(apiKey, {
+              backendUrl, frontendUrl, gatewayUrl, tools: ['pi'],
+            });
+            piFailed = !pi.ok;
+          }
 
           console.log('');
           output.info('Step 2/2: Running device discovery');
@@ -195,6 +245,12 @@ Examples:
         }
 
         console.log('');
+        if (piFailed) {
+          // Everything else is done, but a failed setup must NOT report onboarding success.
+          output.error(`Onboarding finished, but ${SETUP_TOOL_MAP.pi.label} setup failed (see above). Retry it with: ${piRetryCommand(isMdm)}`);
+          process.exitCode = 1;
+          return;
+        }
         output.success(skippedTools && skippedTools.length
           ? 'Onboarding complete — tools managed by MDM were skipped (see above)'
           : 'Onboarding complete');
@@ -209,20 +265,29 @@ Examples:
           // step failed. Retry just the cron: under sudo the scheduled job is a
           // discovery-only scan, so point at `discover --set-cron`; in user
           // scope it re-runs the full onboard (the bundle reinstall is intended).
-          console.error('  Setup and discovery completed successfully — only scheduled-run setup failed.');
+          console.error(piFailed
+            ? '  The tool bundle and discovery completed — scheduled-run setup failed.'
+            : '  Setup and discovery completed successfully — only scheduled-run setup failed.');
           if (isMdm) {
             console.error(`  Re-run with: ${elevated(`unbound onboard --api-key <ADMIN_KEY> --set-cron${suffix}`)}`);
           } else {
             console.error(`  Re-run cron setup with: unbound onboard --api-key <KEY> --set-cron${suffix}`);
           }
         } else if (setupSucceeded && !discoverySucceeded) {
-          console.error('  Tool setup completed successfully — only discovery failed.');
+          console.error(piFailed
+            ? '  The tool bundle is set up — discovery failed.'
+            : '  Tool setup completed successfully — only discovery failed.');
           if (isMdm) {
             console.error(`  Re-run onboarding with: ${elevated(`unbound onboard --api-key <ADMIN_KEY>${suffix}`)}`);
           } else {
             console.error(`  Re-run discovery only with: unbound discover --api-key <KEY>${suffix}`);
           }
         }
+        // A later failure must not bury an earlier one: the hints above retry
+        // discovery or the schedule, and neither of those retries Pi.
+        if (piFailed) {
+          console.error(`  ${SETUP_TOOL_MAP.pi.label} setup also failed (see above). Retry it with: ${piRetryCommand(isMdm)}`);
+        }
         process.exitCode = 1;
       }
     }));

package/src/commands/setup.js

@@ -1289,12 +1289,13 @@ Examples:
 }
 
 /**
- * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks, Copilot hooks) with spinners.
+ * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks, Copilot hooks) with spinners,
+ * or just `tools` when the caller has narrowed it.
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
-  const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false, tools = ALL_TOOLS } = {}) {
+  const resolvedTools = tools.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
   if (backfill) {
     for (const tool of resolvedTools) {
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
@@ -1315,12 +1316,13 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
 }
 
 /**
- * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks, Copilot hooks) with spinners.
+ * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks, Copilot hooks) with spinners,
+ * or just `tools` when the caller has narrowed it.
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
-  const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false, tools = MDM_ALL_TOOLS } = {}) {
+  const resolvedTools = tools.map(name => ({ name, ...MDM_TOOLS[name] }));
   if (backfill) {
     for (const tool of resolvedTools) {
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);

package/src/commands/trace.js

@@ -0,0 +1,158 @@
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+const { buildQueryString } = require('../lib/analytics-query');
+const {
+  DATA_SECURITY_HEADERS,
+  FINDINGS,
+  LOG_HEADERS,
+  TERMINAL_HEADERS,
+  dataSecurityRows,
+  logRows,
+  redactDataSecurityLog,
+  redactLog,
+  resolveTraceId,
+  terminalRows,
+} = require('../lib/flags');
+
+// The widest preset the analytics endpoints accept; Logs takes no window.
+const TRACE_WINDOW = 'THREE_MONTHS';
+
+// One trace rarely fills a page; past this cap the result is reported as incomplete.
+const MAX_PAGES = 10;
+
+const sameTrace = (value, trace) => String(value || '').toLowerCase() === trace;
+
+const SOURCES = [
+  {
+    key: 'logs',
+    title: 'Logs',
+    path: (trace, page) => `/api/v1/logs/prompts/?${buildQueryString({ search: trace, page })}`,
+    // Logs search also matches the text of a prompt, so keep only the exact trace.
+    rows: (data, trace) => (data.prompts || []).filter((p) => sameTrace(p.traceId, trace)),
+    more: (data, page) => page < (data.total_pages || 0),
+    headers: LOG_HEADERS,
+    toTable: (rows, opts) => logRows(rows, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    redact: (rows) => rows.map(redactLog),
+  },
+  {
+    key: 'terminal_runs',
+    title: 'Terminal Runs',
+    path: (trace, page) => `/api/v1/analytics/terminal_commands/?${buildQueryString({ search: trace, time_window: TRACE_WINDOW, page })}`,
+    // The other sources match the trace exactly today; the filter guards an older backend that ignores search.
+    rows: (data, trace) => (data.terminal_commands || []).filter((r) => sameTrace(r.trace_id, trace)),
+    more: (data) => Boolean(data.has_more),
+    headers: TERMINAL_HEADERS,
+    toTable: (rows, opts) => terminalRows(rows, { wide: Boolean(opts.wide) }),
+  },
+  {
+    key: 'data_security',
+    title: 'Data Security',
+    path: (trace, page) => `/api/v1/analytics/guardrails/?${buildQueryString({ search: trace, time_window: TRACE_WINDOW, findings: FINDINGS.all, page })}`,
+    rows: (data, trace) => ((data.logs && data.logs.data) || []).filter((l) => sameTrace(l.trace_id, trace)),
+    more: (data, page) => page < ((data.logs && data.logs.total_pages) || 0),
+    headers: DATA_SECURITY_HEADERS,
+    toTable: (rows, opts) => dataSecurityRows(rows, { reveal: Boolean(opts.reveal), wide: Boolean(opts.wide) }),
+    redact: (rows) => rows.map(redactDataSecurityLog),
+  },
+];
+
+async function fetchAll(source, trace) {
+  const rows = [];
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    const data = await api.get(source.path(trace, page));
+    rows.push(...source.rows(data, trace));
+    if (!source.more(data, page)) return { source, rows, incomplete: false };
+  }
+  return { source, rows, incomplete: true };
+}
+
+async function lookup(trace) {
+  return Promise.all(SOURCES.map(async (source) => {
+    try {
+      return await fetchAll(source, trace);
+    } catch (err) {
+      return { source, error: err.message };
+    }
+  }));
+}
+
+function printJson(trace, results, opts) {
+  const payload = { trace_id: trace };
+  for (const { source, rows, error, incomplete } of results) {
+    if (error) {
+      payload[source.key] = { error };
+    } else {
+      payload[source.key] = { rows: source.redact && !opts.reveal ? source.redact(rows) : rows };
+      if (incomplete) payload[source.key].incomplete = true;
+    }
+  }
+  output.json(payload);
+}
+
+function printTables(trace, results, opts) {
+  for (const { source, rows, error, incomplete } of results) {
+    console.log('');
+    console.log(output.colors.bold(`${source.title}`));
+    if (error) {
+      output.warn(`${source.title} lookup failed: ${error}`);
+    } else if (rows.length === 0) {
+      output.info(`No ${source.title} entries for trace ${trace}.`);
+    } else {
+      output.logTable(source.headers, source.toTable(rows, opts), { wide: Boolean(opts.wide) });
+    }
+    if (incomplete) output.warn(`${source.title}: more than ${MAX_PAGES} pages matched. Only the first ${MAX_PAGES} are shown.`);
+  }
+  if (!opts.reveal) {
+    console.log('');
+    output.info('Prompts and detected values are hidden. Use --reveal to show them.');
+  }
+}
+
+async function runTrace(value, opts) {
+  try {
+    if (!config.isLoggedIn()) throw new Error('Not logged in. Run `unbound login` first.');
+    const trace = resolveTraceId(value);
+    const results = await lookup(trace);
+    if (opts.json) {
+      printJson(trace, results, opts);
+    } else {
+      printTables(trace, results, opts);
+    }
+    // A failed or cut-off source means the answer is incomplete, so scripts must not read it as complete.
+    if (results.some((r) => r.error || r.incomplete)) process.exitCode = 1;
+  } catch (err) {
+    output.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
+function register(program) {
+  program
+    .command('trace <trace-id>')
+    .description('Find everything recorded for one gateway trace ID: the log, terminal runs and data security flags.')
+    .option('--json', 'Output one JSON object with a key per source')
+    .option('--reveal', 'Show prompts and detected data security values in clear text')
+    .option('--wide', 'Print full values instead of clipping to terminal width')
+    .addHelpText('after', `
+The trace ID is the UUID shown to a user under a blocked or warned action.
+
+Sources:
+  Logs           The request and its prompt (any age)
+  Terminal Runs  Tool calls on the request, flagged or not (last 3 months)
+  Data Security  PII or secret detections on the request (last 3 months)
+
+Prompts and detected values are hidden unless --reveal is given.
+
+The exit code is 1 when a source cannot be read, for example because your
+role cannot see it, or when a source has more than ${MAX_PAGES} pages. The
+other sources still print.
+
+Examples:
+  $ unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c
+  $ unbound trace 3f2a6c1e-8b7d-4e2f-9a1c-5d6e7f8a9b0c --json | jq '.terminal_runs.rows[0]'
+`)
+    .action(runTrace);
+}
+
+module.exports = { register, SOURCES };

package/src/index.js

@@ -164,6 +164,15 @@ ANALYTICS (Admin/Analytics Viewer only, for listing as well as CSV export)
   csv exports every matching row, not just the page.
   See "unbound analytics tool-use --help" for the JSON contract used by agents.
 
+FLAGS AND FALSE POSITIVES (Admin/Analytics Viewer/Manager; mark-fp is Admin only)
+  $ unbound flags terminal                 Terminal runs a tool policy flagged
+  $ unbound flags terminal mark-fp <id> --risk-score <n>
+                                           Mark a flagged run as a false positive
+  $ unbound flags data-security            PII and secrets a guardrail found (values masked)
+  $ unbound flags data-security mark-fp <action-id>
+                                           Mark a detection as a false positive
+  $ unbound trace <trace-id>               Log, terminal runs and data security for one trace ID
+
 CHAT (Admin/Analytics Viewer/Manager)
   $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
   $ unbound chat -m "show cost by provider for the last 30 days"
@@ -206,6 +215,8 @@ require('./commands/users').register(program);
 require('./commands/user-groups').register(program);
 require('./commands/tools').register(program);
 require('./commands/analytics').register(program);
+require('./commands/flags').register(program);
+require('./commands/trace').register(program);
 require('./commands/download').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);