@cantinasecurity/apex-cli 0.1.35 → 0.1.37

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

@@ -120,3 +120,43 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Use `apex-finding-tickets` to read existing links. CLI fallback: `apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url> --json`, then `apex findings tickets <finding-ref> --json`.
 - Hosted MCP uses `findingId` (UUID) instead of `findingRef`, with no `cwd` or `scanId`. Linking requires explicit `findings:write`; listing requires `findings:read`. Default service-key scopes remain scans:create, scans:read, findings:read. Do not infer write permission from read access.
 - Apex verifies the ticket through the connected integration and records the frontend link; it does not create or modify a provider ticket. Repeating the same association is safe. A different existing link or in-progress export is a conflict: do not replace it or create another ticket as a fallback. For ambiguous Jira sites, use the full issue URL.
+
+### Workspace CVSS configuration
+
+Use `apex workspace use <workspace>` to bind the intended existing workspace, then
+`apex cvss get` to read its configuration and CVSS 3.1 policy template. To update it,
+write a JSON file containing exactly `enabled` (boolean) and `policy` (the edited
+template), then run `apex cvss set --file <configuration.json>`. Both commands emit
+JSON and require an existing device-login account; they never initiate login,
+create a workspace, or start a scan. Guest sessions are denied. `enabled: false`
+disables CVSS scoring while preserving the supplied policy. This configures future
+synthesis; it does not rescore historical findings.
+
+CVSS administration is intentionally scripted CLI only for this release. No shell,
+local MCP, hosted MCP, or organization service-key tool is added. Agents can invoke
+these explicit terminal commands. Server deployment requires Bedrock CVSS API support for CLI bearer authentication.
+
+Example (jq is used only to prepare the JSON file):
+
+```sh
+apex login
+apex workspace use "<workspace name or prefix>"
+apex cvss get > cvss-current.json
+jq '.configuration // {enabled: true, policy: .template}' cvss-current.json > cvss.json
+# Edit cvss.json, then save and verify:
+apex cvss set --file cvss.json
+apex cvss get
+```
+
+Keep `policy.version` at `3.1`. Supply a name, instructions, and all eight metrics
+(AV, AC, PR, UI, S, C, I, A). Each metric has an `options` map with at least one
+allowed value and nonempty guidance for each allowed value. Omit disallowed
+values. If Audit Setup or another workspace update is active, wait for it to
+finish before saving again.
+
+Scan target and recovery rules:
+- CLI `apex scan [target...]` and repeatable `--repo` accept exact files, directories, or HTTPS GitHub/GitLab repository URLs; local MCP uses `repoPaths` for the same selections. No target means `cwd`.
+- A file selection scans only that file, respecting ignore rules. Local snapshots exclude `.apex/` state. Remote URLs use the default branch and cannot fall back to uploading `cwd`; clone locally to choose a branch or commit.
+- Use Standard for local changes, files, plain directories, and public repositories without provider access. Lite and Audit still require connected provider sources; do not silently substitute another mode.
+- Unauthenticated headless CLI commands fail with explicit login guidance; they never start device login. Use the MCP auth tools for explicit MCP login. Retry transient refresh failures without clearing credentials.
+- Audit Setup is an explicit Standard/Audit beta flow using saved workspace repositories and context. It does not preserve local targets. Never automatically substitute setup after `AUDIT_SETUP_REQUIRED`; use the error's selected-workspace command only when that saved scope is intended. Draft operations require the ID returned by preparation; eligible accounts receive setup commands in CLI help. Lite and PR do not use `--setup`.

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.mcp.codex.json

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

package/README.md

@@ -158,30 +158,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.35 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.37 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.35 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.37 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.35 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.37 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.35 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.37 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.35 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.37 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.35 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.37 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.35 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.37 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.
@@ -266,6 +266,8 @@ Supported shell commands:
 - `apex workspaces`
 - `apex workspace`
 - `apex workspace use <workspace-name|workspace-prefix|workspace-id>`
+- `apex cvss get`
+- `apex cvss set --file <configuration.json>`
 - `apex cancel-scan [scan-id]`
 - `apex status [--scan <scan-id>]`
 - `apex doctor`
@@ -464,7 +466,18 @@ Local MCP exposes `apex-finding-link-ticket` with `findingRef`, `provider`, `iss
 
 ## Local Source Scans
 
-`apex scan` now works against any local source root you point it at. By default, that source root is the current working directory:
+`apex scan [target...]` accepts files, directories, and HTTPS GitHub/GitLab repository URLs. With no targets, it scans the current working directory:
+
+```bash
+apex scan . --mode standard
+apex scan ./contracts --mode standard
+apex scan ./contracts/UniswapV2ERC20.sol --mode standard
+apex scan https://github.com/Uniswap/v2-core --mode standard
+```
+
+A file target uploads only that file, never its siblings. Local snapshots include current local changes and honor Git ignore rules and `.apexignore`; Apex state under `.apex/` is excluded. Explicit remote URLs use the default branch and never fall back to uploading the current checkout. Use a local clone to scan a particular remote branch or commit.
+
+Source planning:
 
 - clean GitHub or GitLab checkouts can stay on the remote-materialization path
 - dirty git worktrees fall back to a local snapshot upload by default
@@ -472,18 +485,22 @@ Local MCP exposes `apex-finding-link-ticket` with `findingRef`, `provider`, `iss
 
 Useful flags:
 
-- `--repo <path>` to scan one or more explicit local roots instead of the current directory
+- `--repo <path-or-url>` as a repeatable alternative to positional targets
 - `--source-mode auto|remote|local` to control remote-first fallback behavior
 - `--mode standard|audit|lite|pr` to choose the scan mode
 - `--pr <number>` to select one or more GitHub pull requests for `--mode pr`
 - `--pr <number:path,path>` or `--pr-path <path>` to limit a PR scan to changed paths
 
+Unauthenticated `--json`, `--non-interactive`, and non-TTY commands fail immediately with `apex login` guidance. Run login explicitly before automation. Temporary refresh/network failures preserve credentials; retry after the service recovers. Provider connection commands return URLs without opening browsers in automation.
+
 `auto` is the default. `remote` requires Apex to materialize from a remote repository. `local` forces a local snapshot upload even when a clean remote path is available.
 
 Audit scans use `audit` as the scan mode and still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback. `ultra` remains accepted as a backwards-compatible alias.
 
 Lite scans use `lite` as the scan mode and require the Lite Scan beta feature plus provider-backed GitHub or GitLab repositories that Apex can materialize remotely. Local snapshot uploads are not supported for Lite scans.
 
+If a backend returns `AUDIT_SETUP_REQUIRED`, the error includes a setup command for the selected workspace. This explicit beta workflow uses the workspace's saved repositories and context; it does not preserve positional file or directory selections. Do not automatically substitute it for a local target scan. An explicit Standard source scan requires current CLI and backend versions. Eligible accounts receive setup commands in CLI help; draft operations use the ID returned by preparation. Lite and PR scans do not use `--setup`.
+
 PR scans require exactly one provider-backed GitHub repository. If the current directory resolves to multiple sources, pass `--repo <path>` to select the one that contains the pull request.
 
 CLI and MCP scan results use the public Bedrock `scanId`. Kernel execution IDs are internal implementation details and are neither returned nor accepted as scan aliases.
@@ -667,7 +684,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.35",
+      "cliVersion": "0.1.37",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -698,7 +715,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.35 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.37 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.
 
@@ -735,3 +752,36 @@ To move between existing Apex workspaces from the CLI:
 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 --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.
+
+### Workspace CVSS configuration
+
+Use `apex workspace use <workspace>` to bind the intended existing workspace, then
+`apex cvss get` to read its configuration and CVSS 3.1 policy template. To update it,
+write a JSON file containing exactly `enabled` (boolean) and `policy` (the edited
+template), then run `apex cvss set --file <configuration.json>`. Both commands emit
+JSON and require an existing device-login account; they never initiate login,
+create a workspace, or start a scan. Guest sessions are denied. `enabled: false`
+disables CVSS scoring while preserving the supplied policy. This configures future
+synthesis; it does not rescore historical findings.
+
+CVSS administration is intentionally scripted CLI only for this release. No shell,
+local MCP, hosted MCP, or organization service-key tool is added. Agents can invoke
+these explicit terminal commands. Server deployment requires Bedrock CVSS API support for CLI bearer authentication.
+
+Example (jq is used only to prepare the JSON file):
+
+```sh
+apex login
+apex workspace use "<workspace name or prefix>"
+apex cvss get > cvss-current.json
+jq '.configuration // {enabled: true, policy: .template}' cvss-current.json > cvss.json
+# Edit cvss.json, then save and verify:
+apex cvss set --file cvss.json
+apex cvss get
+```
+
+Keep `policy.version` at `3.1`. Supply a name, instructions, and all eight metrics
+(AV, AC, PR, UI, S, C, I, A). Each metric has an `options` map with at least one
+allowed value and nonempty guidance for each allowed value. Omit disallowed
+values. If Audit Setup or another workspace update is active, wait for it to
+finish before saving again.

package/dist/apex.js

@@ -1,3 +1,4 @@
+import { commandCvss } from "./cvss.js";
 import { commandStartThreatModel, commandThreatModel, hasAuditSetupBeta, threatModelExitCode, terminalText } from "./threat-model.js";
 import { getMe } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
@@ -94,6 +95,11 @@ async function dispatch(parsed) {
         case "workspaces":
             await commandWorkspaces(client, cwd, parsed.flags);
             return;
+        case "cvss":
+            if (parsed.args.length)
+                throw new Error("Unexpected CVSS arguments");
+            await commandCvss(client, cwd, parsed.flags, parsed.subcommand);
+            return;
         case "workspace":
             if (parsed.subcommand === "use") {
                 const workspaceRef = parsed.args.join(" ");

package/dist/api-client.js

@@ -1,9 +1,16 @@
+import { z } from "zod";
 import { bindCredentialIssuerOriginIfCurrent, clearCredentials, clearCredentialsIfRefreshTokenMatches, loadConfig, loadCredentials, saveRefreshedCredentialsIfCurrent, } from "./config.js";
 import { getTelemetryRequestHeaders } from "./telemetry.js";
 import { redactSensitiveText, redactSensitiveValue, } from "./redaction.js";
 export { redactSensitiveText } from "./redaction.js";
 const CREDENTIAL_GENERATION_CHANGED_MESSAGE = "Apex credentials changed while this request was refreshing. The newer credentials were kept; retry the command.";
 const HOSTED_APEX_ORIGIN = "https://ai.cantina.xyz";
+const REFRESH_CREDENTIALS_SCHEMA = z.object({
+    accessToken: z.string().trim().min(1),
+    refreshToken: z.string().trim().min(1),
+    accessTokenExpiresAt: z.string().datetime({ offset: true }),
+    refreshTokenExpiresAt: z.string().datetime({ offset: true }),
+});
 const CREDENTIAL_ORIGIN_MISMATCH_MESSAGE = "Refusing to send stored Apex credentials because their issuer origin does not match the configured APEX_BASE_URL. Restore the origin used to sign in, or run `apex logout` before signing in to this origin.";
 export class CredentialGenerationChangedError extends Error {
     constructor() {
@@ -211,7 +218,11 @@ export class ApexApiClient {
         });
     }
     async clearCredentialsAfterUnauthorized(expectedRefreshToken, error) {
-        if (!expectedRefreshToken) {
+        // Transport errors, rate limits and server failures do not invalidate a
+        // token pair. Keep it recoverable for the next command.
+        const credentialsInvalid = (error instanceof ApiError && error.status === 401) ||
+            isTerminalGuestSessionError(error);
+        if (!expectedRefreshToken || !credentialsInvalid) {
             return;
         }
         await this.clearCredentialsForGeneration(expectedRefreshToken, error);
@@ -244,20 +255,19 @@ export class ApexApiClient {
         const effectiveRefreshToken = refreshToken ?? existing?.refreshToken ?? null;
         if (!effectiveRefreshToken)
             return null;
-        const payload = (await this.request("/api/cli/v1/auth/refresh", {
+        const payload = await this.request("/api/cli/v1/auth/refresh", {
             method: "POST",
             auth: false,
             json: { refreshToken: effectiveRefreshToken },
             retryOnUnauthorized: false,
             telemetryAttribution: false,
             requestBaseUrl: baseUrl,
-        }));
-        const nextCredentials = {
-            accessToken: payload.accessToken,
-            refreshToken: payload.refreshToken,
-            accessTokenExpiresAt: payload.accessTokenExpiresAt,
-            refreshTokenExpiresAt: payload.refreshTokenExpiresAt,
-        };
+        });
+        const parsed = REFRESH_CREDENTIALS_SCHEMA.safeParse(payload);
+        if (!parsed.success) {
+            throw new Error("Apex returned an invalid credential refresh response. Your credentials were kept; retry the command.");
+        }
+        const nextCredentials = parsed.data;
         const persisted = await saveRefreshedCredentialsIfCurrent(effectiveRefreshToken, nextCredentials);
         if (!persisted.saved) {
             throw new CredentialGenerationChangedError();

package/dist/args.js

@@ -94,6 +94,15 @@ export function parseArgs(argv) {
         }
         index += 1;
     }
+    // Scan operands are source targets, never subcommands. Keep them on the
+    // same typed path as --repo so the CLI and MCP share source selection.
+    if (positional[0] === "scan" && positional.length > 1) {
+        if (flags.setup !== undefined) {
+            throw new Error("Audit Setup does not accept scan targets. Use --workspace-ref <workspace>.");
+        }
+        flags.repo = [...(flags.repo ?? []), ...positional.slice(1)];
+        positional.splice(1);
+    }
     return {
         command: positional[0] ?? null,
         subcommand: positional[1] ?? null,
@@ -102,6 +111,9 @@ export function parseArgs(argv) {
     };
 }
 export function validateCommandFlags(parsed) {
+    if (parsed.flags["source-mode"] !== undefined && !["auto", "remote", "local"].includes(String(parsed.flags["source-mode"]))) {
+        throw new Error("--source-mode must be auto, remote, or local.");
+    }
     if (parsed.flags["workspace-ref"] === undefined) {
         return;
     }

package/dist/commands.js

@@ -332,6 +332,8 @@ function formatLiteScanBalance(scanBalance) {
     return `Lite scan credits: ${detailParts.join(", ")}`;
 }
 function normalizeRequestedScanMode(value) {
+    if (value === null || value === "standard")
+        return "standard";
     if (value === "ultra" || value === "audit") {
         return "audit";
     }
@@ -341,7 +343,7 @@ function normalizeRequestedScanMode(value) {
     if (value === "lite") {
         return "lite";
     }
-    return "standard";
+    throw new Error("--mode must be standard, audit, ultra, lite, or pr.");
 }
 function getFlagValues(flags, key) {
     const values = getFlagList(flags, key);
@@ -1074,7 +1076,7 @@ export async function commandConnect(client, cwd, flags, provider) {
     if (!isJsonMode(flags)) {
         logLine(`Connection URL for ${provider}: ${response.url}`, flags);
     }
-    if (flags["no-open"] !== true) {
+    if (flags["no-open"] !== true && canPromptInteractively(flags)) {
         await openInBrowser(response.url);
     }
     if (isJsonMode(flags)) {
@@ -1097,7 +1099,23 @@ export async function commandScan(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const authState = await getCommandAuthState(client, me);
     setTelemetryAuthKind(authState.authKind);
+    if (authState.authKind === "guest" && requestedMode !== "standard") {
+        throw new Error("Guest trials support standard scans only. Use --mode standard, or run `apex claim` before choosing another mode.");
+    }
+    const guestLocalSourceGuidance = "Guest trials require local snapshot uploads. Clone remote repositories locally, then scan a local path without --source-mode remote.";
+    if (authState.authKind === "guest" && getFlagString(flags, "source-mode") === "remote") {
+        throw new Error(guestLocalSourceGuidance);
+    }
     let selection = await selectWorkspaceTarget(cwd, me, flags);
+    if (authState.authKind === "guest" && selection.sources.some((source) => source.absolutePath === null)) {
+        throw new Error(guestLocalSourceGuidance);
+    }
+    const requiresLocalSnapshot = selection.sourceMode === "local" ||
+        selection.sources.some((source) => source.kind !== "git_candidate" ||
+            (selection.sourceMode !== "remote" && source.dirty));
+    if ((requestedMode === "audit" || requestedMode === "lite") && requiresLocalSnapshot) {
+        throw new Error(`${requestedMode === "audit" ? "Audit" : "Lite"} scans require provider-backed repositories without local changes. Use --mode standard for files, directories, or local changes.`);
+    }
     let preparedArchives = null;
     if (authState.authKind === "guest" && requestedMode === "standard") {
         preparedArchives = await withLoadingIndicator("Preparing local source archive...", flags, () => prepareLocalSourceArchives({
@@ -1139,6 +1157,21 @@ export async function commandScan(client, cwd, flags) {
     let workspaceId = resolvedWorkspaceId;
     let scan;
     let prScanSource = null;
+    const requestScanStart = async (endpoint, json) => {
+        try {
+            return normalizeScanStartResponse(await client.request(endpoint, { method: "POST", json }));
+        }
+        catch (error) {
+            if (error instanceof ApiError && getApiErrorCode(error) === "AUDIT_SETUP_REQUIRED") {
+                const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+                const mode = requestedMode === "audit" ? "audit" : "standard";
+                const command = `apex scan --company ${quote(result.company.id)} --workspace-ref ${quote(workspaceId)} --mode ${mode} --setup guided`;
+                const message = `This backend requires Audit Setup. For this workspace's saved repositories, run: ${command}. Setup uses saved workspace sources and does not preserve local target selections. An explicit Standard source scan requires an updated client and backend; contact support if it still returns AUDIT_SETUP_REQUIRED.`;
+                throw new ApiError(message, error.status, { code: "AUDIT_SETUP_REQUIRED", error: message });
+            }
+            throw error;
+        }
+    };
     if (requestedMode === "pr") {
         let legacyResolve = await withLoadingIndicator("Preparing PR scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
         if (!legacyResolve.workspaceId) {
@@ -1161,40 +1194,30 @@ export async function commandScan(client, cwd, flags) {
         const prSource = resolvePrScanSource(legacyResolve.repositories);
         ensurePrSelectionsMatchSource(prSelections, prSource);
         prScanSource = prSource;
-        scan = await withLoadingIndicator("Starting PR scan...", flags, () => client
-            .request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
-            method: "POST",
-            json: {
-                mode: "pr",
-                scanType: "pr",
-                force: forceRestart || flags.force === true,
-                repositories: buildPrScanRepositoriesPayload({
-                    source: prSource,
-                    pullRequests: prSelections,
-                }),
-            },
-        })
-            .then(normalizeScanStartResponse));
+        scan = await withLoadingIndicator("Starting PR scan...", flags, () => requestScanStart(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+            mode: "pr",
+            scanType: "pr",
+            force: forceRestart || flags.force === true,
+            repositories: buildPrScanRepositoriesPayload({
+                source: prSource,
+                pullRequests: prSelections,
+            }),
+        }));
     }
     else if (requestedMode === "audit" || requestedMode === "lite") {
         const modeLabel = requestedMode === "audit" ? "Audit" : "Lite";
         if (!supportsLegacyRemoteFlow(result.resolve.plannedSources)) {
-            throw new Error(`${modeLabel} scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.`);
+            throw new Error(`${modeLabel} scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks. Use --mode standard for local snapshots or public repositories without a provider connection.`);
         }
         const legacyResolve = await withLoadingIndicator(`Preparing ${modeLabel.toLowerCase()} scan...`, flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
         if (!legacyResolve.workspaceId) {
             throw new Error("Workspace resolution did not return a workspaceId.");
         }
         workspaceId = legacyResolve.workspaceId;
-        scan = await withLoadingIndicator(`Starting ${modeLabel.toLowerCase()} scan...`, flags, () => client
-            .request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
-            method: "POST",
-            json: {
-                mode: requestedMode,
-                force: forceRestart || flags.force === true,
-            },
-        })
-            .then(normalizeScanStartResponse));
+        scan = await withLoadingIndicator(`Starting ${modeLabel.toLowerCase()} scan...`, flags, () => requestScanStart(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+            mode: requestedMode,
+            force: forceRestart || flags.force === true,
+        }));
     }
     else {
         try {
@@ -1206,15 +1229,11 @@ export async function commandScan(client, cwd, flags) {
                     detectedSources: result.sources,
                     preparedArchives,
                 });
-                const response = await client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
-                    method: "POST",
-                    json: {
-                        mode: requestedMode,
-                        force: forceRestart || flags.force === true,
-                        scanSources,
-                    },
+                return requestScanStart(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
+                    mode: requestedMode,
+                    force: forceRestart || flags.force === true,
+                    scanSources,
                 });
-                return normalizeScanStartResponse(response);
             });
         }
         finally {

package/dist/cvss.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { getMe } from "./auth.js";
+import { getFlagString } from "./args.js";
+import { printJson } from "./output.js";
+import { loadWorkspaceBinding } from "./workspace-binding.js";
+const inputSchema = z
+    .object({
+    enabled: z.boolean(),
+    policy: z.record(z.string(), z.unknown()),
+})
+    .strict();
+export async function commandCvss(client, cwd, flags, action) {
+    const file = getFlagString(flags, "file");
+    if (!["get", "set"].includes(action ?? "") ||
+        (action === "set" ? !file : file))
+        throw new Error("Usage: apex cvss get | apex cvss set --file <configuration.json>");
+    if (flags.company || flags["workspace-name"] || flags["workspace-ref"])
+        throw new Error("CVSS uses the bound workspace. Run `apex workspace use <workspace>` first.");
+    const binding = await loadWorkspaceBinding(cwd);
+    if (!binding)
+        throw new Error("Run `apex workspace use <workspace>` before configuring CVSS.");
+    let input;
+    if (action === "set") {
+        const raw = await readFile(path.resolve(cwd, file), "utf8");
+        if (Buffer.byteLength(raw) > 128 * 1024)
+            throw new Error("CVSS configuration is too large.");
+        input = inputSchema.parse(JSON.parse(raw));
+    }
+    const me = await getMe(client);
+    if (!me)
+        throw new Error("Run `apex login` before configuring CVSS.");
+    if ((await client.getCredentials())?.guest ||
+        me.user.role?.trim().toLowerCase() === "guest")
+        throw new Error("CVSS configuration requires a signed-in account.");
+    const response = await client.request(`/api/workspaces/${encodeURIComponent(binding.workspaceId)}/cvss`, action === "set" ? { method: "PUT", json: input } : {});
+    const payload = {
+        configuration: response.configuration
+            ? {
+                enabled: response.configuration.enabled,
+                policy: response.configuration.policy,
+            }
+            : null,
+        template: response.template,
+    };
+    printJson(payload);
+    return payload;
+}

package/dist/help.js

@@ -1,7 +1,7 @@
 export const CLI_HELP_TEXT = `Usage:
   apex                              Open the interactive Apex shell
   apex credits                      Show standard, audit, fix review, and Lite scan entitlements for the active company
-  apex scan                         Create or resolve a workspace for this directory and start a scan
+  apex scan [target...]             Create or resolve a workspace for this directory and start a scan
   apex scans                        List scans for the current workspace binding
   apex findings                     List findings for the latest or selected scan
   apex findings --workspace         List findings across the workspace browser scan set
@@ -18,6 +18,8 @@ export const CLI_HELP_TEXT = `Usage:
                                     Start a fix review scan for a Fix PR or current repository
   apex export findings              Export findings for the latest or selected scan
   apex workspaces                   List accessible workspaces for the active company
+  apex cvss get                     Read workspace CVSS configuration and template (JSON)
+  apex cvss set --file <json>        Update the bound workspace CVSS 3.1 rubric
   apex workspace                    Show the workspace currently bound to this directory
   apex workspace use <workspace-name|workspace-prefix|workspace-id>
                                     Bind this directory to an existing Apex workspace
@@ -73,7 +75,7 @@ Flags:
   --source-mode auto|remote|local   Control remote-vs-local source materialization
   --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
+  --repo <path-or-url>              Select a file, directory, or HTTPS repository (repeatable)
   --json                            Print machine-readable JSON output
   --no-open                         Do not open browser flows automatically
   --non-interactive                 Disable prompts and browser-dependent UX
@@ -81,7 +83,9 @@ Flags:
 
 Tips:
   apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
-  apex scan uses the current directory as the default source root unless you pass --repo.
+  apex scan defaults to the current directory; positional targets or --repo select files, directories, or HTTPS GitHub/GitLab repositories.
+  A file target scans only that file. Use --mode standard for local changes and public repositories without a provider connection.
+  Headless and --json commands require an existing session; run apex login explicitly first.
   PR scans require --mode pr and at least one --pr selection for a GitHub repository.
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   Lite scans use --mode lite and require beta access plus provider-backed GitHub or GitLab sources.
@@ -130,6 +134,9 @@ Audit Setup beta:
   --no-feedback-context             Exclude prior feedback from this setup
   --wait                            Wait for the next actionable setup state
   --timeout <seconds>               Bound next --wait (default 60, maximum 3600)
+  Setup uses saved workspace repositories and context, not local target selections.
+  Use the draft ID returned by setup: apex threat-model status --draft <uuid>.
+  Lite and PR scans do not use --setup.
 `;
 export function cliHelpText(auditSetupEnabled) {
     return auditSetupEnabled
@@ -140,7 +147,7 @@ export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common ar
 
 Commands:
   /credits                Show standard, audit, fix review, and Lite scan entitlements for the active company
-  /scan [standard|audit|lite]
+  /scan [standard|audit|lite] [target...]
                            Start a new Apex scan for this workspace
   /scan pr <pr-number>    Start a PR scan for this workspace
   /scans                  List scans for this workspace

package/dist/local-source-scan.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { createReadStream } from "node:fs";
-import { lstat, mkdtemp, readFile, readdir, readlink, rm, stat, } from "node:fs/promises";
+import { lstat, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -11,6 +11,8 @@ const execFileAsync = promisify(execFile);
 const MAX_ARCHIVE_ENTRIES = 100_000;
 const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
 const BUILTIN_IGNORE_PATTERNS = [
+    ".apex",
+    ".apex/**",
     ".git",
     ".git/**",
     "node_modules",
@@ -89,6 +91,9 @@ async function buildIgnoreMatcher(rootPath) {
             throw new Error(".apexignore is not valid UTF-8.");
         }
         matcher.add(decoded);
+        // Local CLI state is never scan input, even when a broad negation in the
+        // user's ignore file re-includes ordinary generated files.
+        matcher.add([".apex", ".apex/**"]);
     }
     catch (error) {
         if (error.code !== "ENOENT") {
@@ -207,10 +212,19 @@ async function collectDirectoryEntries(rootPath, matcher) {
     return entries;
 }
 async function collectArchiveEntries(source) {
+    if (!source.absolutePath) {
+        throw new Error("A remote repository URL cannot use a local snapshot. Connect its provider or clone it locally, then retry.");
+    }
+    const resolvedRoot = await realpath(source.absolutePath);
+    if (resolvedRoot.split(path.sep).some((segment) => segment.toLowerCase() === ".apex")) {
+        throw new Error("Apex local state (.apex) cannot be selected as scan input. Select your source files or repository instead.");
+    }
     const matcher = await buildIgnoreMatcher(source.absolutePath);
     const gitEntries = await collectGitEntries(source.absolutePath);
-    const rawEntries = gitEntries ??
-        await collectDirectoryEntries(source.absolutePath, matcher);
+    const selectedFiles = source.kind === "directory_candidate" ? source.selectedFiles : undefined;
+    const rawEntries = selectedFiles
+        ? selectedFiles.filter((entry) => !gitEntries || gitEntries.includes(entry))
+        : gitEntries ?? await collectDirectoryEntries(source.absolutePath, matcher);
     const fileEntries = new Set();
     let uncompressedBytes = 0;
     for (const entry of rawEntries.sort(compareArchivePaths)) {
@@ -305,7 +319,13 @@ async function inspectCreatedArchive(archivePath, sourceRoot, expectedFiles, dis
     return { entryCount, uncompressedBytes };
 }
 async function createDeterministicArchive(params) {
+    const sourceRoot = params.source.absolutePath;
+    if (!sourceRoot)
+        throw new Error("Remote repository targets require remote materialization.");
     const { files, uncompressedBytes } = await collectArchiveEntries(params.source);
+    if (files.length === 0) {
+        throw new Error(`No scannable files found in ${params.source.displayName}. Check the target and ignore rules.`);
+    }
     if (files.length > MAX_ARCHIVE_ENTRIES) {
         throw new Error(`Apex local snapshots support at most ${MAX_ARCHIVE_ENTRIES.toLocaleString()} entries per source.`);
     }
@@ -313,7 +333,7 @@ async function createDeterministicArchive(params) {
         throw new Error(`Archive for ${params.source.displayName} exceeds the uncompressed upload limit.`);
     }
     await tar.create({
-        cwd: params.source.absolutePath,
+        cwd: sourceRoot,
         file: params.archivePath,
         gzip: true,
         portable: true,
@@ -334,7 +354,7 @@ async function createDeterministicArchive(params) {
             entry.gname = "root";
         },
     }, files);
-    const observedArchive = await inspectCreatedArchive(params.archivePath, params.source.absolutePath, files, params.source.displayName, params.maxUncompressedBytes);
+    const observedArchive = await inspectCreatedArchive(params.archivePath, sourceRoot, files, params.source.displayName, params.maxUncompressedBytes);
     const manifest = await createArchiveManifest(params.archivePath);
     return {
         ...manifest,

package/dist/mcp.js

@@ -27,7 +27,7 @@ Suggested workflow:
 11. 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.
 
 Notes:
-- Pass cwd explicitly for repository-specific operations.
+- Pass cwd explicitly for repository-specific operations. repoPaths accepts exact files, directories, or HTTPS repository URLs; remote URLs never fall back to uploading cwd. Use Standard for local changes and unconnected public repositories.
 - Tool calls are always non-interactive and never auto-open a browser.
 - Finding write tools use the same Apex device-login credentials as read tools. Never ask for browser cookies or CANTINA_AUTH_TOKEN. An error requiring CANTINA_AUTH_TOKEN proves the MCP server is outdated; update Apex CLI, re-run apex setup for this client, restart it, and retry.
 - 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 a prompt or tool argument. A hosted MCP client supplies it only as the HTTP Authorization header.
@@ -42,6 +42,8 @@ const AUDIT_SETUP_MCP_GUIDE = `
 
 Audit Setup beta:
 - Use apex-scan-setup for a configured workspace, then apex-threat-model.
+- Setup uses saved workspace repositories and context, not repoPaths or local file selections. Never substitute setup for an explicit source scan after AUDIT_SETUP_REQUIRED.
+- Use the draft ID returned by setup for apex-threat-model; setup supports Standard and Audit, not Lite or PR.
 - Read the complete model and get explicit approval before approve with the reviewed sha256 and startScan true.
 - These tools use the local device account. Hosted service-key MCP does not expose Audit Setup.`;
 function mcpWorkflowGuide(auditSetupEnabled) {
@@ -540,7 +542,7 @@ function registerTools(server, auditSetupEnabled = false) {
         }, value => `Threat-model draft ${String(value.draftId)}: ${String(value.state)}.`, input));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans, mode lite for beta-gated provider-backed Lite scans, and mode pr for GitHub pull request scans.",
+        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths to select exact files, directories, or HTTPS GitHub/GitLab repository URLs. Remote URLs use the default branch; files never include siblings. Use mode audit for audit scans, mode lite for beta-gated provider-backed Lite scans, and mode pr for GitHub pull request scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),

package/dist/repo-discovery.js

@@ -7,6 +7,8 @@ const execFileAsync = promisify(execFile);
 async function runGit(cwd, args) {
     const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: 30_000,
     });
     return stdout.trim();
 }
@@ -49,18 +51,39 @@ async function chooseRemote(directory) {
         return firstFetch.url;
     return remotes[0]?.url ?? null;
 }
-async function ensureDirectoryCandidate(cwd, directory) {
-    const stats = await lstat(directory).catch(() => null);
-    if (!stats) {
-        throw new Error(`Path does not exist: ${path.relative(cwd, directory) || "."}`);
+function inspectRemoteTarget(value) {
+    if (!/^(?:[a-z][a-z0-9+.-]*:\/\/|git@|(?:github|gitlab)\.com\/)/i.test(value))
+        return null;
+    const target = value.replace(/^(github|gitlab)\.com\//i, "https://$1.com/");
+    let url;
+    try {
+        url = new URL(target);
     }
-    if (stats.isDirectory()) {
-        return directory;
+    catch {
+        throw new Error("Remote scan targets must be HTTPS GitHub or GitLab repository URLs.");
     }
-    if (stats.isFile()) {
-        return path.dirname(directory);
+    const segments = url.pathname.replace(/\/+$/, "").split("/").filter(Boolean);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.port ||
+        !["github.com", "gitlab.com"].includes(url.hostname) || segments.length < 2 ||
+        (url.hostname === "github.com" && segments.length !== 2) || segments.includes("-")) {
+        throw new Error("Remote scan targets must be HTTPS GitHub or GitLab repository URLs without credentials, query strings, or file/tree paths.");
     }
-    throw new Error(`Path is not a directory: ${path.relative(cwd, directory) || "."}`);
+    const metadata = extractCanonicalRepoMetadata(url.href);
+    if (!metadata)
+        throw new Error("Unsupported remote repository target.");
+    return {
+        kind: "git_candidate",
+        path: `remote/${metadata.provider}/${segments.join("/").replace(/\.git$/i, "")}`,
+        absolutePath: null,
+        displayName: metadata.repoName,
+        repoUrl: metadata.repoUrl,
+        provider: metadata.provider,
+        branch: null,
+        commitSha: null,
+        dirty: false,
+        isRoot: false,
+        sourceType: "branch",
+    };
 }
 function normalizeSelectedRoots(cwd, selectedPaths) {
     const resolved = selectedPaths
@@ -86,7 +109,7 @@ async function inspectGitRepository(rootCwd, directory) {
     const metadata = remoteUrl ? extractCanonicalRepoMetadata(remoteUrl) : null;
     const branchName = await runGit(directory, ["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "HEAD");
     const commitSha = await runGit(directory, ["rev-parse", "HEAD"]).catch(() => null);
-    const dirtyOutput = await runGit(directory, ["status", "--porcelain"]).catch(() => "");
+    const dirtyOutput = await runGit(directory, ["status", "--porcelain", "--", ".", ":(exclude).apex"]).catch(() => null);
     const relativePath = path.relative(rootCwd, directory) || ".";
     const detached = !branchName || branchName === "HEAD";
     return {
@@ -98,13 +121,31 @@ async function inspectGitRepository(rootCwd, directory) {
         provider: metadata?.provider ?? null,
         branch: detached ? null : branchName,
         commitSha: commitSha && commitSha.length > 0 ? commitSha : null,
-        dirty: dirtyOutput.length > 0,
+        // Unknown working-tree state must use a snapshot, never assume the remote
+        // commit contains the user's current files.
+        dirty: dirtyOutput === null || dirtyOutput.length > 0,
         isRoot: relativePath === ".",
         sourceType: detached ? "commit" : "branch",
     };
 }
 async function inspectSource(rootCwd, requestedDirectory) {
-    const directory = await ensureDirectoryCandidate(rootCwd, requestedDirectory);
+    const stats = await lstat(requestedDirectory).catch(() => null);
+    const requestedPath = path.relative(rootCwd, requestedDirectory) || ".";
+    if (!stats)
+        throw new Error(`Path does not exist: ${requestedPath}`);
+    if (stats.isFile()) {
+        return {
+            kind: "directory_candidate",
+            path: requestedPath,
+            absolutePath: path.dirname(requestedDirectory),
+            displayName: path.basename(requestedDirectory),
+            isRoot: false,
+            selectedFiles: [path.basename(requestedDirectory)],
+        };
+    }
+    if (!stats.isDirectory())
+        throw new Error(`Path is not a regular file or directory: ${requestedPath}`);
+    const directory = requestedDirectory;
     const relativePath = path.relative(rootCwd, directory) || ".";
     const gitTopLevel = await getGitTopLevel(directory);
     const comparableDirectory = await resolveComparablePath(directory);
@@ -120,10 +161,22 @@ async function inspectSource(rootCwd, requestedDirectory) {
     };
 }
 export async function discoverSources(cwd, selectedPaths = []) {
-    const discoveredRoots = selectedPaths.length > 0
-        ? normalizeSelectedRoots(cwd, selectedPaths)
-        : [cwd];
-    const sources = await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)));
+    const remoteSources = [];
+    const localPaths = [];
+    for (const target of selectedPaths) {
+        const remote = inspectRemoteTarget(target);
+        if (remote) {
+            if (!remoteSources.some((source) => source.path === remote.path))
+                remoteSources.push(remote);
+        }
+        else
+            localPaths.push(target);
+    }
+    const discoveredRoots = selectedPaths.length === 0 ? [cwd] : normalizeSelectedRoots(cwd, localPaths);
+    const sources = [...remoteSources, ...await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)))];
+    if (new Set(sources.map((source) => source.path)).size !== sources.length) {
+        throw new Error("Scan targets have conflicting source paths. Select them in separate scans.");
+    }
     sources.sort((left, right) => left.path.localeCompare(right.path));
     return { sources, scanned: discoveredRoots };
 }

package/dist/session.js

@@ -98,9 +98,16 @@ function selectBindingForWorkspaceName(flags, binding, workspaceName) {
 }
 function getSourceMode(flags) {
     const value = getFlagString(flags, "source-mode");
-    return value === "remote" || value === "local" ? value : "auto";
+    if (value === null || value === "auto")
+        return "auto";
+    if (value === "remote" || value === "local")
+        return value;
+    throw new Error("--source-mode must be auto, remote, or local.");
 }
 function buildFallbackLocalArchivePlan(source, sourceMode) {
+    if (!source.absolutePath) {
+        throw new Error("A remote repository URL cannot use a local snapshot. Connect its provider or clone it locally, then retry.");
+    }
     const reason = sourceMode === "local"
         ? "user_requested_local_snapshot"
         : source.kind === "directory_candidate"
@@ -136,6 +143,11 @@ function buildFallbackLocalArchivePlan(source, sourceMode) {
 }
 function ensurePlannedSources(selection, resolve) {
     if (resolve.plannedSources.length > 0) {
+        for (const source of selection.sources) {
+            if (!source.absolutePath && !resolve.plannedSources.some((plan) => plan.path === source.path && plan.sourceKind === "remote_repo")) {
+                throw new Error("The remote repository is not accessible. Connect its provider or clone it locally, then retry.");
+            }
+        }
         return resolve;
     }
     if (selection.sourceMode === "remote") {
@@ -172,6 +184,9 @@ export async function ensureAuthenticated(client, flags) {
     if (isClaimProofAvailable(credentials)) {
         throw new Error("Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` to keep the trial results.");
     }
+    if (!canPromptInteractively(flags)) {
+        throw new Error("Apex is not authenticated. Run `apex login` explicitly, then retry this command.");
+    }
     return login(client, {
         noOpen: flags["no-open"] === true,
         quiet: isJsonMode(flags),
@@ -182,16 +197,21 @@ export async function resolveWorkspace(client, cwd, me, flags) {
     return resolveWorkspaceSelection(client, selection);
 }
 export async function selectWorkspaceTarget(cwd, me, flags) {
+    const sourceMode = getSourceMode(flags);
     const loadedBinding = await loadWorkspaceBinding(cwd);
     const company = await chooseCompany(me, flags, loadedBinding);
-    const workspaceNameSelection = await chooseWorkspaceName(cwd, flags, loadedBinding);
+    const companyBinding = loadedBinding?.companyId === company.id ? loadedBinding : null;
+    const workspaceNameSelection = await chooseWorkspaceName(cwd, flags, companyBinding);
     const workspaceName = workspaceNameSelection.workspaceName;
-    const binding = selectBindingForWorkspaceName(flags, loadedBinding, workspaceName);
+    const binding = selectBindingForWorkspaceName(flags, companyBinding, workspaceName);
     const sourceSelection = getFlagList(flags, "repo");
     const discovered = await discoverSources(cwd, sourceSelection);
     if (discovered.sources.length === 0) {
         throw new Error("No local sources were found.");
     }
+    if (sourceMode === "local" && discovered.sources.some((source) => source.absolutePath === null)) {
+        throw new Error("Remote repository URLs cannot use --source-mode local. Clone the repository locally first.");
+    }
     return {
         company,
         workspaceName,
@@ -199,7 +219,7 @@ export async function selectWorkspaceTarget(cwd, me, flags) {
         binding,
         sources: discovered.sources,
         legacyRepositories: extractLegacyRepositories(discovered.sources),
-        sourceMode: getSourceMode(flags),
+        sourceMode,
     };
 }
 export async function resolveWorkspaceSelection(client, selection) {

package/dist/shell.js

@@ -206,11 +206,8 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandClaim(client, cwd, shellFlags);
             return false;
         case "scan": {
-            const mode = parsed.args[0];
-            if (mode && !["standard", "audit", "ultra", "lite", "pr"].includes(mode)) {
-                process.stderr.write("Usage: /scan [standard|audit|ultra|lite|pr] [pr-number]\n");
-                return {};
-            }
+            const first = parsed.args[0];
+            const mode = first && ["standard", "audit", "ultra", "lite", "pr"].includes(first) ? first : null;
             const prNumber = mode === "pr" ? parsed.args[1] : null;
             if (mode === "pr" && !prNumber) {
                 process.stderr.write("Usage: /scan pr <pr-number>\n");
@@ -220,11 +217,15 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
                 process.stderr.write("Usage: /scan pr <pr-number>\n");
                 return {};
             }
-            const commandFlags = mode === "pr" && prNumber
+            let commandFlags = mode === "pr" && prNumber
                 ? withFlag(withFlag(shellFlags, "mode", mode), "pr", [prNumber])
                 : mode
                     ? withFlag(shellFlags, "mode", mode)
                     : shellFlags;
+            const targets = parsed.args.slice(mode ? 1 : 0);
+            if (mode !== "pr" && targets.length > 0) {
+                commandFlags = withFlag(commandFlags, "repo", targets);
+            }
             if (commandFlags.setup !== undefined) {
                 await commandStartThreatModel(client, cwd, commandFlags);
                 return {};

package/dist/threat-model.js

@@ -314,7 +314,18 @@ async function interactiveAnswers(state) {
     };
 }
 export async function commandThreatModel(client, cwd, flags, action, supplied, emit = true) {
-    const draftId = uuid.parse(required(flags, "draft"));
+    const selectedDraft = getFlagString(flags, "draft");
+    if (!selectedDraft) {
+        const binding = await loadWorkspaceBinding(cwd);
+        const setupCommand = binding
+            ? "apex scan --mode standard --setup guided"
+            : "apex workspaces";
+        throw new ThreatModelUsageError(`Select --draft <id> from the setup response. To create a draft, run ${setupCommand}${binding ? "" : ", bind the intended workspace with apex workspace use <ref>, then run apex scan --mode standard --setup guided"}. Setup uses the workspace's saved repositories and context, not local file selections.`);
+    }
+    const parsedDraft = uuid.safeParse(selectedDraft);
+    if (!parsedDraft.success)
+        throw new ThreatModelUsageError("--draft must be a valid draft ID from the setup response.");
+    const draftId = parsedDraft.data;
     requireAuditSetupBeta(await requireAccount(client));
     let state;
     if (action === "status" || action === "next") {
@@ -368,8 +379,15 @@ export async function commandThreatModel(client, cwd, flags, action, supplied, e
     return state;
 }
 export async function commandStartThreatModel(client, cwd, flags, emit = true) {
-    const setup = z.enum(["guided", "auto"]).parse(required(flags, "setup"));
-    const mode = z.enum(["standard", "audit"]).parse(required(flags, "mode"));
+    const setup = getFlagString(flags, "setup");
+    if (setup !== "guided" && setup !== "auto") {
+        throw new ThreatModelUsageError("--setup must be guided or auto.");
+    }
+    const requestedMode = getFlagString(flags, "mode");
+    const mode = requestedMode === "ultra" ? "audit" : requestedMode;
+    if (mode !== "standard" && mode !== "audit") {
+        throw new ThreatModelUsageError("Audit Setup supports --mode standard or --mode audit. Lite and PR scans do not use --setup; remove it and retry the intended scan mode.");
+    }
     if (["repo", "pr", "pr-path", "source-mode", "force", "workspace-name"].some((key) => flags[key] !== undefined))
         throw new ThreatModelUsageError("Audit Setup uses the configured workspace repositories and context; local source and force flags are not supported");
     const me = await requireAccount(client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",
@@ -27,18 +27,19 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ignore": "^7.0.5",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "ignore": "^7.0.12",
     "proper-lockfile": "^4.1.2",
-    "tar": "^7.4.3",
-    "zod": "^4.3.6"
+    "tar": "^7.5.22",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^22.18.6",
+    "@types/node": "^22.20.5",
     "@types/proper-lockfile": "^4.1.4",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vite": "^6.4.4",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "apex": "tsx src/apex.ts",

package/skills/apex-cli/SKILL.md

@@ -120,3 +120,43 @@ verify `apex-credits` without printing the credential.
 - Use `apex-finding-tickets` to read existing links. CLI fallback: `apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url> --json`, then `apex findings tickets <finding-ref> --json`.
 - Hosted MCP uses `findingId` (UUID) instead of `findingRef`, with no `cwd` or `scanId`. Linking requires explicit `findings:write`; listing requires `findings:read`. Default service-key scopes remain scans:create, scans:read, findings:read. Do not infer write permission from read access.
 - Apex verifies the ticket through the connected integration and records the frontend link; it does not create or modify a provider ticket. Repeating the same association is safe. A different existing link or in-progress export is a conflict: do not replace it or create another ticket as a fallback. For ambiguous Jira sites, use the full issue URL.
+
+### Workspace CVSS configuration
+
+Use `apex workspace use <workspace>` to bind the intended existing workspace, then
+`apex cvss get` to read its configuration and CVSS 3.1 policy template. To update it,
+write a JSON file containing exactly `enabled` (boolean) and `policy` (the edited
+template), then run `apex cvss set --file <configuration.json>`. Both commands emit
+JSON and require an existing device-login account; they never initiate login,
+create a workspace, or start a scan. Guest sessions are denied. `enabled: false`
+disables CVSS scoring while preserving the supplied policy. This configures future
+synthesis; it does not rescore historical findings.
+
+CVSS administration is intentionally scripted CLI only for this release. No shell,
+local MCP, hosted MCP, or organization service-key tool is added. Agents can invoke
+these explicit terminal commands. Server deployment requires Bedrock CVSS API support for CLI bearer authentication.
+
+Example (jq is used only to prepare the JSON file):
+
+```sh
+apex login
+apex workspace use "<workspace name or prefix>"
+apex cvss get > cvss-current.json
+jq '.configuration // {enabled: true, policy: .template}' cvss-current.json > cvss.json
+# Edit cvss.json, then save and verify:
+apex cvss set --file cvss.json
+apex cvss get
+```
+
+Keep `policy.version` at `3.1`. Supply a name, instructions, and all eight metrics
+(AV, AC, PR, UI, S, C, I, A). Each metric has an `options` map with at least one
+allowed value and nonempty guidance for each allowed value. Omit disallowed
+values. If Audit Setup or another workspace update is active, wait for it to
+finish before saving again.
+
+Scan target and recovery rules:
+- CLI `apex scan [target...]` and repeatable `--repo` accept exact files, directories, or HTTPS GitHub/GitLab repository URLs; local MCP uses `repoPaths` for the same selections. No target means `cwd`.
+- A file selection scans only that file, respecting ignore rules. Local snapshots exclude `.apex/` state. Remote URLs use the default branch and cannot fall back to uploading `cwd`; clone locally to choose a branch or commit.
+- Use Standard for local changes, files, plain directories, and public repositories without provider access. Lite and Audit still require connected provider sources; do not silently substitute another mode.
+- Unauthenticated headless CLI commands fail with explicit login guidance; they never start device login. Use the MCP auth tools for explicit MCP login. Retry transient refresh failures without clearing credentials.
+- Audit Setup is an explicit Standard/Audit beta flow using saved workspace repositories and context. It does not preserve local targets. Never automatically substitute setup after `AUDIT_SETUP_REQUIRED`; use the error's selected-workspace command only when that saved scope is intended. Draft operations require the ID returned by preparation; eligible accounts receive setup commands in CLI help. Lite and PR do not use `--setup`.