@cantinasecurity/apex-cli 0.1.22 → 0.1.24

package/.claude/skills/apex-cli/SKILL.md

@@ -37,7 +37,7 @@ Recommended workflow:
 4. For repository-scoped work, pass `cwd` explicitly.
 5. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 6. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
-7. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle. Use `apex-workspace-findings` for the cross-scan workspace browser view.
+7. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle. Use `apex-workspace-findings` for the cross-scan workspace browser view. To review unresolved findings across any accessible workspace, first call `apex-workspaces` with the company, then call `apex-workspace-findings` with `company`, `workspaceRef`, and `findingState: "open"`; this does not change the local binding.
 8. For Lite scans, call `apex-scan` with `mode: "lite"` only when the company has Lite Scan beta access and the sources are provider-backed.
 9. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
 10. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
@@ -69,7 +69,8 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - When checking a scan that is not the workspace binding's latest scan, pass `scanId` to `apex-status`; use `apex scans` or `apex-scans` first if you need to discover scan IDs.
-- Use `apex-workspace-findings` when the user asks for findings across a workspace instead of one scan. Pass `filters: ["status:open"]` for all open findings; supported filter facets are `severity`, `scan`, `status`, `validation`, and `visibility`, and a leading `!` negates a filter. In CLI-only flows, use `apex findings --workspace --filter status:open`.
+- Use `apex-workspace-findings` when the user asks for findings across a workspace instead of one scan. Set `findingState: "open"` for findings needing review; open excludes fixed, invalid, dismissed, and duplicate findings and is not `status:open`. Pass `company` plus a workspace name, prefix, or ID as `workspaceRef` to avoid relying on or mutating a local binding. In CLI-only flows, use `apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open`.
+- Workspace finding responses expose the web UI lifecycle fields `status`, `validity`, `reviewState`, `isDuplicate`, `duplicateOfId`, `repository`, and `sourceFile`. Supported filter facets are `severity`, `scan`, `repo`, `review`, `impact`, `likelihood`, `status`, `validation`, `visibility`, `duplicate`, and `source`; a leading `!` negates a filter.
 - Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status`, check `apex-trial-status`, and complete `apex-auth-start` / `apex-auth-wait` only when no unexpired local claim proof is available. Never ask for browser cookies or `CANTINA_AUTH_TOKEN`; an error requiring that variable proves the MCP server is outdated, so update Apex CLI, re-run `apex setup <client>`, restart the client, and retry.
 - Anonymous telemetry records only sanitized command/tool metadata such as command names, enum modes, counts, durations, success/failure categories, CLI version, and client integration. It must not include raw repository paths, scan IDs, finding IDs, comments, file paths, PR URLs, trial codes, claim tokens, onboarding fingerprints, or bearer tokens.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
@@ -85,6 +86,6 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Start a PR scan: call `apex-scan` with `mode: "pr"` and `pullRequests`.
 - Check an active scan: call `apex-status`, passing `scanId` when the scan is not the latest binding, then `apex-findings` when the scan completes.
 - Export findings for review: call `apex-export-findings` with `format` set to `markdown`, `json`, or `gitlab-sast`.
-- Review all open workspace findings: call `apex-workspace-findings` with `filters: ["status:open"]`.
+- Review all open workspace findings: call `apex-workspaces` with the company, then call `apex-workspace-findings` with the selected `workspaceRef` and `findingState: "open"`.
 - Leave review feedback: call `apex-finding-comment` to add a note, or `apex-finding-feedback` with `status` set to `valid` or `invalid`.
 - Run a Fix PR review: call `apex-finding-fix-review` with `fixPrUrls`, optionally after recording fixed feedback with `apex-finding-feedback`.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.22"
+    "version": "0.1.24"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.22"
+        "version": "0.1.24"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.22",
+      "version": "0.1.24",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.22",
+        "@cantinasecurity/apex-cli@0.1.24",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.22",
+      "@cantinasecurity/apex-cli@0.1.24",
       "apex-mcp"
     ],
     "env": {

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.22 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.24 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -145,30 +145,30 @@ unclaimed local trial proof so `apex claim` can still use it.
 Agent-safe copy/paste prompt (substitute the issued code):
 
 ```text
-Install and run Cantina Apex CLI 0.1.22 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.24 to start one free standard security scan of this repository immediately.
 
 Use this trial code only where <TRIAL_CODE> appears below: SPBT-DEVREL-XXXXXXXX
 
 Run the commands yourself from the repository root; do not stop after setup or only explain the steps. Use terminal CLI commands only. Do not use an Apex MCP tool or run `apex setup`, `apex mcp`, `apex login`, `apex-auth-start`, or `apex-auth-wait`. Never use `--replace` or `--force`.
 
 Use this exact command prefix for every Apex command:
-  npx -y -p @cantinasecurity/apex-cli@0.1.22 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.24 apex
 
 1. Before redeeming, confirm every command will use the same persistent, user-accessible machine or container, HOME, filesystem, and repository root. Confirm Node.js 20+ and npx are available. If `APEX_BASE_URL` is set, continue only when its origin is `https://ai.cantina.xyz`. Run the exact prefix with `--help` and continue only if help lists both `redeem` and `claim`. If any check fails, STOP before sending the code; do not install system packages.
 2. Redeem, with at most one response-loss recovery retry:
-     npx -y -p @cantinasecurity/apex-cli@0.1.22 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.24 apex redeem <TRIAL_CODE> --json
    This terminal command is the only allowed tool call containing the code. Never echo or restate the code, store it in a file or environment variable, put it in a URL or MCP call, or include it in your response. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. If and only if the first attempt ends with an ambiguous transport/connection failure or an interrupted/missing response and no typed server error code, retry this exact same command once on the same machine, HOME, and repository root. Never retry a typed server rejection and never make more than one recovery retry. If the allowed retry does not return a successful JSON outcome, STOP.
 3. Immediately start exactly one scan; do not wait for another instruction:
-     npx -y -p @cantinasecurity/apex-cli@0.1.22 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.24 apex scan --mode standard --non-interactive --no-open --json
    On any error or nonzero exit, STOP. After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired. Otherwise capture `binding.lastScanId` from the JSON as <SCAN_ID>; if it is absent, STOP.
 4. About every 60 seconds, poll that exact scan:
-     npx -y -p @cantinasecurity/apex-cli@0.1.22 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.24 apex status --scan <SCAN_ID> --json
    Read `progress.progress.status`. Wait while it is `created`, `pending`, `queued`, `starting`, `running`, `in_progress`, or `processing`. Continue on `completed`. STOP on `failed`, `cancelled`, a missing or unknown status, or a command failure.
 5. Fetch that exact scan's findings:
-     npx -y -p @cantinasecurity/apex-cli@0.1.22 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.24 apex findings --scan <SCAN_ID> --json
    On success, summarize findings by severity, most severe first, including identifier, title, status, and confidence. This command does not return file locations, so do not invent them. On failure, STOP.
 6. Do not claim automatically. Tell me the claim deadline from step 2 and remind me to run this exact command myself from the same repository root, machine, and HOME:
-     npx -y -p @cantinasecurity/apex-cli@0.1.22 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.24 apex claim
    It may open a browser so I can create or sign in to a Cantina account and keep the results. Claim moves the trial into the currently selected Cantina workspace when I can run scans there, or into my existing personal workspace. If the selected workspace cannot run scans, tell me to switch to one that can and retry before the claim deadline.
 
 Never paste raw command transcripts. For any failure, report only the step, exit code, and sanitized error. Redact the trial code and every `apex_at_`, `apex_rt_`, or `apex_ct_` value from all reports.
@@ -239,7 +239,7 @@ Supported shell commands:
 - `apex scan --mode pr --pr <number> [--pr <number>] [--pr-path <path>]`
 - `apex scans`
 - `apex findings [--scan <scan-id>]`
-- `apex findings --workspace [--filter <[!]facet:value>]`
+- `apex findings --workspace [--company <handle>] [--workspace-ref <name|prefix|id>] [--finding-state all|open] [--filter <[!]facet:value>]`
 - `apex findings comment <finding-id|finding-identifier> --content <markdown> [--parent-comment <comment-id>] [--scan <scan-id>]`
 - `apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant] [--label acknowledged|fixed] [--fix-pr-url <github-pr-url>]`
 - `apex findings fix-review <finding-id|finding-identifier> [--scan <scan-id>] [--review-target pull-request|repository-current] [--fix-pr-url <github-pr-url>]`
@@ -421,12 +421,19 @@ codex mcp add apex \
 For Claude Code:
 
 ```bash
-claude mcp add --scope user \
+claude mcp add apex \
+  --scope user \
   -e APEX_MCP_CLIENT=claude \
   -e APEX_CLIENT_INTEGRATION=claude \
-  -- apex apex-mcp
+  -- apex-mcp
 ```
 
+`apex setup claude` uses Claude's name-first stdio command syntax and checks
+whether the installed Claude CLI supports `--scope user`. If a Claude build
+omits that option or advertises it but rejects it at runtime, setup safely
+merges the same user-level `mcpServers.apex` entry into `~/.claude.json`
+without replacing other settings or servers.
+
 For GitHub Copilot CLI:
 
 ```bash
@@ -494,7 +501,7 @@ The MCP server exposes Apex-specific tools for:
 - doctor, credits, and provider connection URLs
 - workspace inspection and workspace binding
 - scan start, status, cancellation, findings, and findings export
-- cross-scan workspace findings through `apex-workspace-findings`, with filters such as `status:open` and `!validation:invalid`
+- cross-scan workspace findings through `apex-workspace-findings`, including direct workspace selection, first-class open state, web UI lifecycle fields, and server-side filters
 - Lite scan start by calling `apex-scan` with `mode: "lite"`
 - PR scan start by calling `apex-scan` with `mode: "pr"` and `pullRequests`
 - finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
@@ -504,7 +511,28 @@ The MCP server does not expose trial redemption, trial claim, or service-key cre
 
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 
-Use `apex-workspace-findings` when an agent needs the same cross-scan finding set as the workspace browser. For example, pass `filters: ["status:open"]` to retrieve all open findings without enumerating scans. Repeated filters in one facet are ORed; filters across different facets are ANDed. Supported facets are `severity`, `scan`, `status`, `validation`, and `visibility`.
+Use `apex-workspace-findings` when an agent needs the same cross-scan finding
+set as the workspace browser. Pass `company`, `workspaceRef`, and
+`findingState: "open"` to select any accessible workspace without changing the
+local binding and return only findings that still need review:
+
+```json
+{
+  "company": "apex-internal",
+  "workspaceRef": "BEDR9",
+  "findingState": "open"
+}
+```
+
+Open state excludes fixed, invalid, dismissed, and duplicate findings. It is a
+first-class selection, not `status:open`; actual finding status values are
+`proposed`, `partially_valid`, `valid`, `invalid`, and `duplicate`. The
+response includes `status`, `validity`, `reviewState`, duplicate metadata,
+repository, and source file fields used by the web UI. Supported filter facets
+are `severity`, `scan`, `repo`, `review`, `impact`, `likelihood`, `status`,
+`validation`, `visibility`, `duplicate`, and `source`. Repeated filters in one
+facet are ORed; filters across different facets are ANDed, and a leading `!`
+negates a filter.
 
 For Codex-style clients, the packaged skill can be installed with `apex setup codex`. For GitHub Copilot CLI, the same skill is installed into `~/.copilot/skills/apex-cli` with `apex setup copilot`. The repo-local source lives at `skills/apex-cli/SKILL.md`.
 
@@ -541,7 +569,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.22",
+      "cliVersion": "0.1.24",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -572,7 +600,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.claude-plugin/plugin.json` and `.mcp.claude.json` for Claude Code plugin installs
 - `.claude-plugin/marketplace.json` for a Claude marketplace entry backed by the public npm package
 
-These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.22 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.24 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
 
 The repository also includes `.agents/plugins/marketplace.json` for local Codex marketplace testing from a checkout.
 
@@ -608,4 +636,4 @@ To move between existing Apex workspaces from the CLI:
 2. Run `apex workspace use <workspace-name|workspace-prefix|workspace-id>` to bind the current directory.
 3. If the workspace name contains spaces, quote it, for example `apex workspace use "Core Platform"`.
 4. Use `apex scans`, `apex status --scan <scan-id>`, `apex findings`, and `apex export findings` against that binding.
-5. Use `apex findings --workspace --filter status:open` for the workspace browser's cross-scan open-findings view.
+5. Use `apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open` for the workspace browser's cross-scan findings that still need review, without changing the local binding.

package/dist/commands.js

@@ -1442,8 +1442,35 @@ export async function commandWorkspaceFindings(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const authState = await getCommandAuthState(client, me);
     setTelemetryAuthKind(authState.authKind);
-    const binding = await requireWorkspaceBinding(cwd);
-    const response = await withLoadingIndicator("Loading workspace findings...", flags, () => fetchWorkspaceFindings(client, binding.workspaceId, getFlagList(flags, "filter")));
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const workspaceRef = getFlagString(flags, "workspace-ref");
+    if (getFlagString(flags, "company") && !workspaceRef) {
+        throw new Error("--company requires --workspace-ref for workspace findings so the selected company cannot be confused with the local binding.");
+    }
+    let workspaceId;
+    let binding;
+    if (workspaceRef) {
+        const company = await chooseCompany(me, flags, currentBinding);
+        const workspaces = await withLoadingIndicator("Loading workspaces...", flags, () => fetchCompanyWorkspaces(client, company.id));
+        const workspace = findWorkspaceByRef(workspaces.workspaces, workspaceRef);
+        if (!workspace) {
+            throw new Error(`Could not find a workspace matching "${workspaceRef}". ${WORKSPACE_SELECTION_GUIDANCE}`);
+        }
+        workspaceId = workspace.workspaceId;
+        binding =
+            currentBinding?.workspaceId === workspace.workspaceId
+                ? currentBinding
+                : null;
+    }
+    else {
+        binding = requireLoadedWorkspaceBinding(currentBinding);
+        workspaceId = binding.workspaceId;
+    }
+    const requestedState = getFlagString(flags, "finding-state") ?? "all";
+    if (requestedState !== "all" && requestedState !== "open") {
+        throw new Error("Workspace finding state must be all or open.");
+    }
+    const response = await withLoadingIndicator("Loading workspace findings...", flags, () => fetchWorkspaceFindings(client, workspaceId, getFlagList(flags, "filter"), requestedState));
     const payload = {
         ...response,
         binding,
@@ -1453,6 +1480,7 @@ export async function commandWorkspaceFindings(client, cwd, flags) {
         return payload;
     }
     logLine(`Workspace: ${response.workspace.name}`, flags);
+    logLine(`Finding state: ${response.state}`, flags);
     if (response.filters.length > 0) {
         logLine(`Filters: ${response.filters.join(", ")}`, flags);
     }
@@ -1463,7 +1491,7 @@ export async function commandWorkspaceFindings(client, cwd, flags) {
     }
     for (const finding of response.findings) {
         const identifier = finding.findingIdentifier ?? finding.id;
-        logLine(`${finding.severity.toUpperCase()} ${identifier} ${finding.title} (${finding.status})`, flags);
+        logLine(`${finding.severity.toUpperCase()} ${identifier} ${finding.title} (${finding.status}, ${finding.reviewState}, ${finding.validity})`, flags);
         if (finding.findingUrl) {
             logLine(`View: ${finding.findingUrl}`, flags);
         }

package/dist/findings.js

@@ -1,7 +1,7 @@
 import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
 import { ApiError, CredentialGenerationChangedError, isTerminalGuestSessionError, } from "./api-client.js";
 const FINDING_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const WORKSPACE_FINDING_FILTER_PATTERN = /^!?(severity|scan|status|validation|visibility):[^:]+$/;
+const WORKSPACE_FINDING_FILTER_PATTERN = /^!?(severity|scan|repo|review|impact|likelihood|status|validation|visibility|duplicate|source):[^:]+$/;
 const MAX_WORKSPACE_FINDING_FILTERS = 50;
 const MAX_WORKSPACE_FINDING_FILTER_LENGTH = 128;
 const CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
@@ -185,16 +185,21 @@ export function normalizeWorkspaceFindingFilters(filters) {
     }
     return filters.map((filter) => {
         const normalized = filter.trim();
+        const normalizedStatusFilter = normalized
+            .replace(/^!/, "")
+            .toLowerCase();
         if (normalized.length === 0 ||
             normalized.length > MAX_WORKSPACE_FINDING_FILTER_LENGTH ||
-            !WORKSPACE_FINDING_FILTER_PATTERN.test(normalized)) {
-            throw new Error("Invalid workspace finding filter. Use [!]severity|scan|status|validation|visibility:<value>, for example status:open or !validation:invalid.");
+            !WORKSPACE_FINDING_FILTER_PATTERN.test(normalized) ||
+            normalizedStatusFilter === "status:open") {
+            throw new Error("Invalid workspace finding filter. Use a supported web-UI facet such as severity:high, review:unreviewed, duplicate:unique, or !validation:invalid. `open` is a finding state, not a status filter.");
         }
         return normalized;
     });
 }
-export async function fetchWorkspaceFindings(client, workspaceId, filters) {
+export async function fetchWorkspaceFindings(client, workspaceId, filters, state = "all") {
     const params = new URLSearchParams();
+    params.set("state", state);
     for (const filter of normalizeWorkspaceFindingFilters(filters)) {
         params.append("filter", filter);
     }

package/dist/help.js

@@ -43,6 +43,8 @@ Flags:
   --workspace-name <name>           Set the Apex workspace name for this directory
   --scan <scan-id>                  Select a specific scan for status, findings, or export
   --workspace                       Use the cross-scan workspace findings view
+  --workspace-ref <name|prefix|id>  Select a workspace without changing the local binding
+  --finding-state all|open          Select all findings or only findings needing review
   --filter <[!]facet:value>         Filter workspace findings; repeat for multiple filters
   --status valid|invalid            Set the finding feedback status explicitly
   --content <markdown>              Supply comment content for apex findings comment
@@ -92,7 +94,9 @@ Tips:
   Invalid finding feedback requires --dismissal-reason.
   Fix review scans use saved or supplied Fix PR URLs when present; otherwise they review the current repository when Bedrock has original scan repository context.
   Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
-  Use apex findings --workspace --filter status:open to retrieve all open findings across the workspace browser scan set.
+  Use apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open to retrieve findings needing review without changing the local binding.
+  Open excludes fixed, invalid, dismissed, and duplicate findings. It is a finding state, not a status filter.
+  Workspace filters match the web UI facets: severity, scan, repo, review, impact, likelihood, status, validation, visibility, duplicate, and source.
   Anonymous usage telemetry helps Apex understand CLI, MCP, Codex, Claude, and Copilot usage. Disable it with apex telemetry disable or APEX_TELEMETRY_DISABLED=1.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
@@ -107,7 +111,7 @@ Commands:
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
   /findings workspace [filter...]
-                          List workspace findings; for example status:open
+                          List workspace findings; for example review:unreviewed
   /findings comment <finding-ref> <comment>
                           Add a comment or note to a finding
   /findings feedback <finding-ref> valid [comment]
@@ -154,7 +158,8 @@ Tips:
   Lite scans require beta access plus provider-backed GitHub or GitLab sources.
   /workspace use accepts a workspace name, prefix, or ID.
   /findings comment, /findings feedback, and /findings fix-review use the current Apex login.
-  /findings workspace status:open returns all open findings in the workspace browser scan set.
+  For first-class open state or a workspace that is not locally bound, use scripted
+  apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open.
   /claim is the only onboarding command that may open a browser. Trial redemption stays scripted-only and is not exposed through MCP.
   /claim moves trial results into the selected Cantina workspace when you can run scans there, or into your existing personal workspace.
   Service-key commands automatically use your company when only one is available. With multiple companies, choose one interactively or pass --company.

package/dist/mcp.js

@@ -18,8 +18,8 @@ Suggested workflow:
 3. If the user supplied a Cantina trial code, run \`apex redeem <code>\` in a terminal instead of starting device login. Never put the code in an MCP tool call.
 4. Only when Apex is unauthenticated and no unexpired claim proof or trial code is available, call apex-auth-start and ask the user to approve the device login URL, then call apex-auth-wait with both the returned deviceCode and credentialGeneration.
 5. Call apex-doctor for the target repository cwd.
-6. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
-7. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings. Use apex-workspace-findings for the cross-scan workspace view.
+6. If a repository operation needs a different local binding, call apex-workspaces and apex-workspace-use.
+7. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings. For cross-scan review queues, call apex-workspace-findings with company, workspaceRef, and findingState "open"; this direct selection does not require or change a local binding.
 8. For PR scans, call apex-scan with mode "pr" and one or more pullRequests.
 9. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
 10. To review a fix, call apex-finding-fix-review. Pass fixPrUrls for PR-based fix reviews, or omit them to review the current repository state when Bedrock has original scan repository context.
@@ -52,6 +52,12 @@ function buildFlags(options) {
     if (options.workspaceName) {
         flags["workspace-name"] = options.workspaceName;
     }
+    if (options.workspaceRef) {
+        flags["workspace-ref"] = options.workspaceRef;
+    }
+    if (options.findingState) {
+        flags["finding-state"] = options.findingState;
+    }
     if (options.scanId) {
         flags.scan = options.scanId;
     }
@@ -617,21 +623,29 @@ function registerTools(server) {
     }));
     server.registerTool("apex-workspace-findings", {
         title: "List Apex Workspace Findings",
-        description: "List findings across the current Apex workspace using the same non-archived scan set as the web findings browser. Pass filters such as status:open or !validation:invalid; repeated filters in one facet are ORed and different facets are ANDed.",
+        description: "List findings across all scans in an Apex workspace with web-UI lifecycle fields and filter values. Pass company plus workspaceRef to select any accessible workspace without a local binding. Set findingState to open to exclude fixed, invalid, dismissed, and duplicate findings; open is not a status filter.",
         inputSchema: {
             cwd: z.string().optional(),
+            company: z.string().optional(),
+            workspaceRef: z.string().min(1).optional(),
+            findingState: z.enum(["all", "open"]).optional(),
             filters: z.array(z.string().min(1).max(128)).max(50).optional(),
         },
-    }, async ({ cwd, filters }) => runTool("apex-workspace-findings", async () => {
+    }, async ({ cwd, company, workspaceRef, findingState, filters }) => runTool("apex-workspace-findings", async () => {
         const client = new ApexApiClient();
         await requireAuthenticated(client);
         const targetCwd = resolveCwd(cwd);
-        const payload = await commandWorkspaceFindings(client, targetCwd, buildFlags({ filters }));
+        const payload = await commandWorkspaceFindings(client, targetCwd, buildFlags({
+            company,
+            workspaceRef,
+            findingState,
+            filters,
+        }));
         return {
             cwd: targetCwd,
             ...payload,
         };
-    }, (value) => `Fetched Apex workspace findings for ${String(value.cwd)}.`, { cwd, filters }));
+    }, (value) => `Fetched Apex workspace findings for ${String(value.cwd)}.`, { cwd, company, workspaceRef, findingState, filters }));
     server.registerTool("apex-finding-comment", {
         title: "Add Apex Finding Comment",
         description: "Add a comment or note to an Apex finding using the current Apex login.",

package/dist/setup.js

@@ -1,5 +1,6 @@
 import { execFile as execFileCallback } from "node:child_process";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -54,6 +55,20 @@ async function tryExecText(command, args, cwd) {
         return null;
     }
 }
+function isUnknownClaudeScopeOption(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const processError = error;
+    const output = [
+        processError.message,
+        processError.stdout,
+        processError.stderr,
+    ]
+        .filter((value) => typeof value === "string")
+        .join("\n");
+    return /(?:unknown|unrecognized) option(?::)?\s+['"]?--scope['"]?/i.test(output);
+}
 async function resolveMcpLaunchSpec(packageRoot = PACKAGE_ROOT) {
     const repoLocalBinary = path.join(packageRoot, "bin", "apex-mcp");
     if ((await pathExists(path.join(packageRoot, ".git"))) &&
@@ -189,6 +204,72 @@ async function readClaudeUserMcpConfig() {
         return null;
     }
 }
+async function claudeSupportsUserScope() {
+    const help = await tryExecText("claude", ["mcp", "add", "--help"]);
+    if (!help) {
+        return null;
+    }
+    return /(?:^|\s)--scope(?:\s|,|$)/m.test(`${help.stdout}\n${help.stderr}`);
+}
+async function writeClaudeUserMcpConfig(launch) {
+    const configPath = path.join(os.homedir(), ".claude.json");
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            raw = null;
+        }
+        else {
+            throw new Error(`Cannot update ${configPath}: the existing Claude Code config could not be read.`, { cause: error });
+        }
+    }
+    let document = {};
+    if (raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Cannot update ${configPath}: the existing Claude Code config is not valid JSON.`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error(`Cannot update ${configPath}: the existing Claude Code config must be a JSON object.`);
+        }
+        document = parsed;
+    }
+    const currentServers = document.mcpServers &&
+        typeof document.mcpServers === "object" &&
+        !Array.isArray(document.mcpServers)
+        ? document.mcpServers
+        : {};
+    document.mcpServers = {
+        ...currentServers,
+        [MCP_SERVER_NAME]: {
+            type: "stdio",
+            command: launch.command,
+            args: launch.args,
+            env: mcpClientEnv("claude"),
+        },
+    };
+    const configDirectory = path.dirname(configPath);
+    const temporaryPath = path.join(configDirectory, `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`);
+    await mkdir(configDirectory, { recursive: true, mode: 0o700 });
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(document, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await chmod(temporaryPath, 0o600);
+        await rename(temporaryPath, configPath);
+        await chmod(configPath, 0o600);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 async function readCopilotUserMcpConfig() {
     const configPath = path.join(getCopilotHome(), "mcp-config.json");
     const raw = await readTextFile(configPath);
@@ -247,29 +328,54 @@ async function configureCodex(launch) {
 async function configureClaude(cwd, launch) {
     const existing = await readClaudeUserMcpConfig();
     const env = mcpClientEnv("claude");
+    const supportsUserScope = await claudeSupportsUserScope();
+    let usedConfigFallback = supportsUserScope === false;
     const mcpStatus = existing === null
         ? "installed"
         : claudeConfigMatches(existing, launch)
             ? "unchanged"
             : "updated";
-    if (existing) {
-        await execText("claude", ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]);
+    if (usedConfigFallback) {
+        await writeClaudeUserMcpConfig(launch);
+    }
+    else {
+        try {
+            if (existing) {
+                await execText("claude", [
+                    "mcp",
+                    "remove",
+                    MCP_SERVER_NAME,
+                    "--scope",
+                    "user",
+                ]);
+            }
+            // Keep the server name before `--`, which separates Claude options from
+            // the stdio command and its arguments.
+            await execText("claude", [
+                "mcp",
+                "add",
+                MCP_SERVER_NAME,
+                "--scope",
+                "user",
+                "-e",
+                `${MCP_CLIENT_ENV_NAME}=${env[MCP_CLIENT_ENV_NAME]}`,
+                "-e",
+                `${MCP_CLIENT_INTEGRATION_ENV_NAME}=${env[MCP_CLIENT_INTEGRATION_ENV_NAME]}`,
+                "--",
+                launch.command,
+                ...launch.args,
+            ]);
+        }
+        catch (error) {
+            if (!isUnknownClaudeScopeOption(error)) {
+                throw error;
+            }
+            // Some Claude Code builds advertise --scope in help but reject it when
+            // the command runs. Preserve the user-level registration directly.
+            await writeClaudeUserMcpConfig(launch);
+            usedConfigFallback = true;
+        }
     }
-    // Claude's variadic --env option consumes later tokens until `--`.
-    await execText("claude", [
-        "mcp",
-        "add",
-        "--scope",
-        "user",
-        "-e",
-        `${MCP_CLIENT_ENV_NAME}=${env[MCP_CLIENT_ENV_NAME]}`,
-        "-e",
-        `${MCP_CLIENT_INTEGRATION_ENV_NAME}=${env[MCP_CLIENT_INTEGRATION_ENV_NAME]}`,
-        "--",
-        MCP_SERVER_NAME,
-        launch.command,
-        ...launch.args,
-    ]);
     const skillSource = path.join(PACKAGE_ROOT, ".claude", "skills", CODEX_SKILL_NAME, "SKILL.md");
     const skillTarget = path.join(cwd, ".claude", "skills", CODEX_SKILL_NAME, "SKILL.md");
     const skillContent = await readFile(skillSource, "utf8");
@@ -280,7 +386,9 @@ async function configureClaude(cwd, launch) {
             kind: "mcp",
             status: mcpStatus,
             path: path.join(os.homedir(), ".claude.json"),
-            detail: `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config`,
+            detail: usedConfigFallback
+                ? `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config (CLI compatibility fallback)`
+                : `Registered ${MCP_SERVER_NAME} -> ${launch.label} in Claude Code user config`,
         },
         {
             client: "claude",

package/dist/telemetry.js

@@ -19,6 +19,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "force",
     "format",
     "filter",
+    "finding-state",
     "help",
     "json",
     "label",
@@ -40,6 +41,7 @@ const KNOWN_CLI_FLAG_NAMES = [
     "status",
     "suggested-severity",
     "workspace-name",
+    "workspace-ref",
     "workspace",
 ];
 const KNOWN_CLI_COMMANDS = [
@@ -230,6 +232,7 @@ function sanitizeCliFlags(flags) {
         workspaceFindings: boolFlag(flags, "workspace"),
         companyProvided: stringFlag(flags, "company") !== null,
         workspaceNameProvided: stringFlag(flags, "workspace-name") !== null,
+        workspaceRefProvided: stringFlag(flags, "workspace-ref") !== null,
         nameProvided: stringFlag(flags, "name") !== null,
         expiresAtProvided: stringFlag(flags, "expires-at") !== null,
         scanIdProvided: stringFlag(flags, "scan") !== null,
@@ -247,6 +250,7 @@ function sanitizeCliFlags(flags) {
         sourceMode: safeEnum(stringFlag(flags, "source-mode"), ["auto", "remote", "local"]),
         format: safeEnum(stringFlag(flags, "format"), ["markdown", "json", "gitlab-sast"]),
         feedbackStatus: safeEnum(stringFlag(flags, "status"), ["valid", "invalid"]),
+        findingState: safeEnum(stringFlag(flags, "finding-state"), ["all", "open"]),
         fixReviewTarget: safeFixReviewTarget(stringFlag(flags, "review-target")),
         dismissalReason: safeEnum(stringFlag(flags, "dismissal-reason"), [
             "false-positive",
@@ -408,6 +412,7 @@ export function sanitizeMcpInput(input = {}) {
         companyProvided: typeof input.company === "string" && input.company.trim().length > 0,
         workspaceNameProvided: typeof input.workspaceName === "string" && input.workspaceName.trim().length > 0,
         workspaceRefProvided: typeof input.workspaceRef === "string" && input.workspaceRef.trim().length > 0,
+        findingState: safeEnum(typeof input.findingState === "string" ? input.findingState : null, ["all", "open"]),
         scanIdProvided: typeof input.scanId === "string" && input.scanId.trim().length > 0,
         findingRefProvided: typeof input.findingRef === "string" && input.findingRef.trim().length > 0,
         outputProvided: typeof input.output === "string" && input.output.trim().length > 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -37,7 +37,7 @@ Workflow:
 4. For repository work, pass `cwd` explicitly.
 5. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 6. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
-7. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle. Use `apex-workspace-findings` for the cross-scan workspace browser view.
+7. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle. Use `apex-workspace-findings` for the cross-scan workspace browser view. To review unresolved findings across any accessible workspace, first call `apex-workspaces` with the company, then call `apex-workspace-findings` with `company`, `workspaceRef`, and `findingState: "open"`; this does not change the local binding.
 8. For Lite scans, call `apex-scan` with `mode: "lite"` only when the company has Lite Scan beta access and the sources are provider-backed.
 9. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
 10. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
@@ -74,7 +74,8 @@ Guidelines:
 - Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
 - When checking a scan that is not the workspace binding's latest scan, pass `scanId` to `apex-status`; use `apex-scans` first if you need to discover scan IDs.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
-- Use `apex-workspace-findings` when the user asks for findings across a workspace instead of one scan. Pass `filters: ["status:open"]` for all open findings; supported filter facets are `severity`, `scan`, `status`, `validation`, and `visibility`, and a leading `!` negates a filter.
+- Use `apex-workspace-findings` when the user asks for findings across a workspace instead of one scan. Set `findingState: "open"` for findings needing review; open excludes fixed, invalid, dismissed, and duplicate findings and is not `status:open`. Pass `company` plus a workspace name, prefix, or ID as `workspaceRef` to avoid relying on or mutating a local binding.
+- Workspace finding responses expose the web UI lifecycle fields `status`, `validity`, `reviewState`, `isDuplicate`, `duplicateOfId`, `repository`, and `sourceFile`. Supported filter facets are `severity`, `scan`, `repo`, `review`, `impact`, `likelihood`, `status`, `validation`, `visibility`, `duplicate`, and `source`; a leading `!` negates a filter.
 - Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status`, check `apex-trial-status`, and complete `apex-auth-start` / `apex-auth-wait` only when no unexpired local claim proof is available. Never ask for browser cookies or `CANTINA_AUTH_TOKEN`; an error requiring that variable proves the MCP server is outdated, so update Apex CLI, re-run `apex setup <client>`, restart the client, and retry.
 - Anonymous telemetry records only sanitized command/tool metadata such as command names, enum modes, counts, durations, success/failure categories, CLI version, and client integration. It must not include raw repository paths, scan IDs, finding IDs, comments, file paths, PR URLs, trial codes, claim tokens, onboarding fingerprints, or bearer tokens.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.