@cantinasecurity/apex-cli 0.1.26 → 0.1.27

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

@@ -56,8 +56,9 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - After a guest scan, tell the user to run `apex claim` on the same machine before that returned claim deadline. If the deadline is unavailable or uncertain, do not guess or start a replacement login; run `apex claim` and let the server validate the proof.
 - Claim moves the guest workspace, scans, and findings into the currently selected Cantina workspace when the account can run scans there. Personal workspace owners receive the trial in their existing workspace instead of a duplicate. If the selected workspace cannot run scans, tell the user to switch to one that can and retry before the claim deadline.
 - Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
-- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
+- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
 - For a headless HTTP adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. A service key does not authenticate CLI or MCP commands; those use device login. Do not shell out to `apex` or launch MCP from the adapter.
+- Hosted API integrations can call `GET /api/apex/v1/credits` with `scans:create` scope to inspect the organization's current standard, audit, and Lite balances and effective scan-type availability. Treat the response as a point-in-time snapshot; scan creation remains authoritative.
 - Hosted API v1 remote-repository scans require the GitHub repository to be linked to an active Apex workspace and do not create or mutate workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors. Local or non-Git scans use the documented source-upload flow, which can create or reuse a workspace; send `generateThreatModel: true` for the first scan of a newly created local workspace.
 - Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - Use `--non-interactive` and `--no-open` for automation-friendly CLI calls.
@@ -70,6 +71,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Audit scans use `--mode audit` in user-facing CLI calls and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - Lite scans use `--mode lite` in CLI calls or `mode: "lite"` in MCP, require Lite Scan beta access, and require provider-backed GitHub or GitLab sources without local snapshot fallback.
 - PR scans use `--mode pr --pr <number>` in CLI calls, or `mode: "pr"` with `pullRequests` in MCP. They require one provider-backed GitHub repository.
+- Starting a PR scan may run alongside active workspace scans and does not require `--force` or `force: true`. Starting any non-PR scan still treats every active scan, including a PR scan, as a blocker; use force only when the user explicitly wants that overlap.
 - `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.

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "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.26",
+  "version": "0.1.27",
   "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.26",
+        "@cantinasecurity/apex-cli@0.1.27",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.26",
+      "@cantinasecurity/apex-cli@0.1.27",
       "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.26 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.27 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -152,30 +152,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.26 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.27 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.26 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.27 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.26 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.27 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. Parse the JSON from stdout only; do not merge stderr into stdout, because npm may write warnings to stderr. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. `idempotent` means the existing guest session resumed and it may already own a workspace. 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.26 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.27 apex scan --mode standard --non-interactive --no-open --json
    The CLI validates the complete guest local archive before it reserves a workspace. An unbound renamed checkout may recover only the sole empty guest workspace when no explicit workspace name was supplied. 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.26 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.27 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.26 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.27 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.26 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.27 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.
@@ -296,7 +296,7 @@ The CLI automatically uses your company when only one is available. If you belon
 
 The secret is returned only by `create` and cannot be retrieved later. Store it directly in a secret manager and do not put it in source control, prompts, chat messages, or logs. `--json` also includes the shown-once secret so it can be captured programmatically; handle that output as a credential.
 
-Service keys are organization-level credentials. Grant only the scopes the integration needs: `scans:create` triggers scans, `scans:read` polls status, and `findings:read` retrieves findings. Omit `--scope` to grant all three scopes. For a P1-only adapter that reads manually started scans, create a read-only key with `--scope scans:read,findings:read`.
+Service keys are organization-level credentials. Grant only the scopes the integration needs: `scans:create` reads credit availability and triggers scans, `scans:read` polls status, and `findings:read` retrieves findings. Omit `--scope` to grant all three scopes. For a P1-only adapter that reads manually started scans, create a read-only key with `--scope scans:read,findings:read`.
 
 A key with `findings:read` can retrieve unpublished draft findings for scans in its organization so an external hub can perform triage. Give the key only to systems that are allowed to handle those drafts.
 
@@ -314,6 +314,10 @@ Service-key management is intentionally available only through the scripted CLI.
 Use the service key as a bearer token with the hosted scan lifecycle:
 
 ```bash
+curl \
+  -H "Authorization: Bearer $APEX_SERVICE_KEY" \
+  https://ai.cantina.xyz/api/apex/v1/credits
+
 curl -X POST https://ai.cantina.xyz/api/apex/v1/scans \
   -H "Authorization: Bearer $APEX_SERVICE_KEY" \
   -H "Idempotency-Key: $APEX_IDEMPOTENCY_KEY" \
@@ -582,7 +586,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.26",
+      "cliVersion": "0.1.27",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -613,7 +617,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.26 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.27 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.
 
@@ -641,7 +645,7 @@ The CLI uses the Apex `/api/cli/v2/**` local-source routes for scan planning and
 - `~/.config/apex/credentials.json`
 - `.apex/workspace.json`
 
-If a scan is already running in the current workspace, `apex scan` and `/scan` now require confirmation before starting another one. Scripted usage can opt in explicitly with `--force`. Active-looking workspace scan rows are checked against the scan progress endpoint before the CLI treats them as blockers, so stale list entries do not hide terminal states such as `cancelled`.
+When starting a non-PR scan, any active workspace scan (including a PR scan) requires confirmation. Scripted usage can opt in explicitly with `--force`. Starting a PR scan skips that client preflight and may run alongside active workspace scans without `--force`, matching Bedrock's one-directional scan concurrency contract. Active-looking workspace scan rows are checked against the scan progress endpoint before the CLI treats them as blockers, so stale list entries do not hide terminal states such as `cancelled`.
 
 To move between existing Apex workspaces from the CLI:
 

package/dist/commands.js

@@ -1115,8 +1115,11 @@ export async function commandScan(client, cwd, flags) {
                 throw new Error("Workspace resolution did not return a workspaceId.");
             }
             const resolvedWorkspaceId = result.resolve.workspaceId;
-            const activeScan = await withLoadingIndicator("Checking for existing scans...", flags, () => findActiveWorkspaceScan(client, resolvedWorkspaceId, result.binding));
-            const forceRestart = await ensureScanRestartConfirmed(flags, activeScan);
+            let forceRestart = false;
+            if (requestedMode !== "pr") {
+                const activeScan = await withLoadingIndicator("Checking for existing scans...", flags, () => findActiveWorkspaceScan(client, resolvedWorkspaceId, result.binding));
+                forceRestart = await ensureScanRestartConfirmed(flags, activeScan);
+            }
             return {
                 selection: resolved.selection,
                 result,

package/dist/help.js

@@ -66,7 +66,7 @@ Flags:
   --pr <number[:path,path]>         Select a GitHub pull request for --mode pr
   --pr-path <path>                  Limit a single-PR scan to a changed file path
   --source-mode auto|remote|local   Control remote-vs-local source materialization
-  --force                           Start an overlapping scan, or confirm destructive guest logout
+  --force                           Start an overlapping non-PR scan, or confirm destructive guest logout
   --replace                         Revoke and replace an existing guest trial session
   --repo <path>                     Include one or more explicit local source roots
   --json                            Print machine-readable JSON output

package/dist/mcp.js

@@ -31,6 +31,7 @@ Notes:
 - Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into an MCP prompt or tool call.
 - HTTP-only serverless and cron integrations should use the hosted API documented at https://ai.cantina.xyz/docs/apex-api instead of launching this stdio server.
 - Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "lite" only for beta-enabled provider-backed Lite scans, and mode "pr" for GitHub pull request scans.
+- Starting a PR scan may run alongside active workspace scans and does not require force. Starting any non-PR scan still treats every active scan, including a PR scan, as a blocker; use force only when the user explicitly wants that overlap.
 - Doctor is read-only for guest sessions and reports the local snapshot plan without reserving a workspace.
 - Guest standard scans validate the complete local archive before resolving or reserving a workspace. For an unbound renamed checkout, Apex may recover only the sole empty guest workspace when no explicit workspace name was supplied.
 - When terminal redemption returns JSON, parse stdout only and keep stderr warnings separate. An idempotent outcome resumes the existing guest session, which may already own a workspace.`;

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -61,8 +61,9 @@ Guidelines:
 - The MCP-only `apex-trial-status` tool may report local guest and claim deadlines, but it must never return a trial code or claim token. `claimAvailable` becomes false at a known passed deadline; missing or invalid local deadline metadata remains conservative and server-authoritative. There is intentionally no MCP redemption or claim tool.
 - When MCP remains available after a guest scan, remind the user to run `apex claim` on the same machine while `claimAvailable` is true; after a known passed deadline, continue with normal account login.
 - Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
-- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
+- If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
 - For a headless HTTP adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. A service key does not authenticate CLI or MCP commands; those use device login. Do not shell out to `apex` or launch MCP from the adapter.
+- Hosted API integrations can call `GET /api/apex/v1/credits` with `scans:create` scope to inspect the organization's current standard, audit, and Lite balances and effective scan-type availability. Treat the response as a point-in-time snapshot; scan creation remains authoritative.
 - Hosted API v1 remote-repository scans require the GitHub repository to be linked to an active Apex workspace and do not create or mutate workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors. Local or non-Git scans use the documented source-upload flow, which can create or reuse a workspace; send `generateThreatModel: true` for the first scan of a newly created local workspace.
 - Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - `apex-credits` reports standard credits plus audit, fix review, and Lite scan entitlements when Bedrock returns those balances.
@@ -72,9 +73,9 @@ Guidelines:
 - Audit scans use `mode: "audit"` in user-facing instructions and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - Lite scans use `mode: "lite"`, require Lite Scan beta access, and require provider-backed GitHub or GitLab sources without local snapshot fallback.
 - PR scans use `mode: "pr"` and require one provider-backed GitHub repository plus one or more `pullRequests`.
+- Starting a PR scan may run alongside active workspace scans and does not require `force`. Starting any non-PR scan still treats every active scan, including a PR scan, as a blocker; use `force: true` only when the user explicitly wants that overlap.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
-- 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. 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.