@cantinasecurity/apex-cli 0.1.25 → 0.1.26

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

@@ -57,8 +57,8 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - 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.
-- For a headless HTTP adapter, read the service key from a secret-backed environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch MCP from the adapter.
-- Hosted API v1 requires the GitHub repository to be linked to an active Apex workspace. It never creates or mutates workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors.
+- 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 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.
 - Use `--json` whenever structured output is helpful.

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.25",
+      "@cantinasecurity/apex-cli@0.1.26",
       "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.25 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.26 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.25 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.26 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.25 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.26 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.
@@ -270,6 +270,8 @@ Supported shell commands:
 - `apex connect github`
 - `apex connect gitlab`
 
+`--workspace-ref` is scoped to `apex findings --workspace`. For `apex scans` or `apex export findings`, bind the intended workspace first with `apex workspace use <name|prefix|id>`; unsupported or unknown flags fail instead of falling back to the local binding.
+
 Helpful workspace flags:
 
 - `--company <id-or-handle>` to choose the Apex company when more than one is available
@@ -307,6 +309,8 @@ apex service-key revoke <key-id>
 
 Service-key management is intentionally available only through the scripted CLI. It is not exposed as an MCP tool or interactive-shell command, which keeps raw secrets out of model tool results and transcripts. The CLI requires an existing device-login bearer session, never initiates login from these commands, and never stores a created service key locally.
 
+`APEX_SERVICE_KEY` authenticates the hosted REST API only; it does not authenticate CLI commands or replace `apex login`. When `apex doctor` finds a service key but no active device-login session, it reports that split before starting a login flow. `APEX_API_KEY` is also recognized for this diagnostic so older integrations receive migration guidance, but `APEX_SERVICE_KEY` is the documented REST variable.
+
 Use the service key as a bearer token with the hosted scan lifecycle:
 
 ```bash
@@ -329,7 +333,9 @@ curl \
   https://ai.cantina.xyz/api/apex/v1/scans/$SCAN_ID/findings
 ```
 
-In v1, the GitHub repository must already be linked to an active Apex workspace. The hosted API never creates, binds, or mutates workspaces. Apex selects the workspace automatically when exactly one active workspace matches the repository; pass the optional `workspaceId` to disambiguate multiple matches. Zero matches, or multiple matches without a valid `workspaceId`, return HTTP `409`.
+For a remote GitHub scan, the repository must already be linked to an active Apex workspace. This remote-repository flow never creates, binds, or mutates workspaces. Apex selects the workspace automatically when exactly one active workspace matches the repository; pass the optional `workspaceId` to disambiguate multiple matches. Zero matches, or multiple matches without a valid `workspaceId`, return HTTP `409`.
+
+For a local or non-Git checkout, use the service API's source-upload flow instead. It can create or reuse a workspace, uploads a `tar.gz` archive, and starts the scan with a `local_archive` source. A newly created local workspace has no threat model to reuse, so its first scan must send `generateThreatModel: true`. See the [Apex service API guide](https://ai.cantina.xyz/docs/apex-api) for the current request schemas and limits.
 
 The optional `paths` array is a set of best-effort focus hints, not a hard repository boundary. Apex may inspect or report code outside those paths. Version one does not yet provide strict path isolation.
 
@@ -576,7 +582,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.25",
+      "cliVersion": "0.1.26",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -607,7 +613,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.25 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.26 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.
 

package/dist/apex.js

@@ -1,5 +1,5 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
-import { parseArgs } from "./args.js";
+import { parseArgs, validateCommandFlags } from "./args.js";
 import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogin, commandLogout, commandRedeem, commandScan, commandScans, commandServiceKeyCreate, commandServiceKeyList, commandServiceKeyRevoke, commandSetup, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, getRedeemExitCode, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { runMcpServer } from "./mcp.js";
@@ -154,6 +154,7 @@ async function dispatch(parsed) {
 }
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
+    validateCommandFlags(parsed);
     const invocation = createCliTelemetryInvocation(parsed);
     emitInvocationStarted(invocation);
     await withTelemetryContext(invocation, async () => {

package/dist/args.js

@@ -1,3 +1,39 @@
+export const KNOWN_CLI_FLAG_NAMES = [
+    "comment",
+    "company",
+    "content",
+    "dismissal-reason",
+    "expires-at",
+    "fix-pr-url",
+    "force",
+    "format",
+    "filter",
+    "finding-state",
+    "help",
+    "json",
+    "label",
+    "limit",
+    "mode",
+    "name",
+    "no-open",
+    "non-interactive",
+    "output",
+    "parent-comment",
+    "pr",
+    "pr-path",
+    "replace",
+    "repo",
+    "review-target",
+    "scan",
+    "scope",
+    "source-mode",
+    "status",
+    "suggested-severity",
+    "workspace-name",
+    "workspace-ref",
+    "workspace",
+];
+const KNOWN_CLI_FLAGS = new Set(KNOWN_CLI_FLAG_NAMES);
 const BOOLEAN_FLAGS = new Set([
     "force",
     "non-interactive",
@@ -25,6 +61,9 @@ export function parseArgs(argv) {
             continue;
         }
         const key = value.slice(2);
+        if (!KNOWN_CLI_FLAGS.has(key)) {
+            throw new Error(`Unknown flag: --${key}`);
+        }
         if (BOOLEAN_FLAGS.has(key)) {
             flags[key] = true;
             continue;
@@ -50,6 +89,17 @@ export function parseArgs(argv) {
         flags,
     };
 }
+export function validateCommandFlags(parsed) {
+    if (parsed.flags["workspace-ref"] === undefined) {
+        return;
+    }
+    const isWorkspaceFindings = parsed.command === "findings" &&
+        parsed.subcommand === null &&
+        parsed.flags.workspace === true;
+    if (!isWorkspaceFindings) {
+        throw new Error("--workspace-ref is only supported with `apex findings --workspace`. To change the local workspace used by scans or exports, run `apex workspace use <workspace-ref>` first.");
+    }
+}
 export function isJsonMode(flags) {
     return flags.json === true;
 }

package/dist/commands.js

@@ -11,6 +11,7 @@ import { claimOnboardingSession, isProofOnlyOnboardingCredentials, redeemOnboard
 import { confirm } from "./prompt.js";
 import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
 import { createServiceApiKey, isServiceApiScope, listServiceApiKeys, revokeServiceApiKey, SERVICE_API_SCOPES, } from "./service-keys.js";
+import { getServiceKeyCliAuthGuidance } from "./service-key-environment.js";
 import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, planGuestWorkspaceSelection, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
@@ -985,10 +986,15 @@ export async function commandTelemetry(flags, target) {
     return payload;
 }
 export async function commandDoctor(client, cwd, flags) {
-    const me = await ensureAuthenticated(client, flags);
-    const authState = await getCommandAuthState(client, me);
-    setTelemetryAuthKind(authState.authKind);
     try {
+        const serviceKeyGuidance = getServiceKeyCliAuthGuidance();
+        const existingMe = serviceKeyGuidance ? await getMe(client) : null;
+        if (serviceKeyGuidance && !existingMe) {
+            throw new Error(serviceKeyGuidance);
+        }
+        const me = existingMe ?? (await ensureAuthenticated(client, flags));
+        const authState = await getCommandAuthState(client, me);
+        setTelemetryAuthKind(authState.authKind);
         const result = await withLoadingIndicator("Inspecting this directory and checking Apex setup...", flags, async () => {
             if (authState.authKind === "guest") {
                 const selection = await selectWorkspaceTarget(cwd, me, flags);

package/dist/help.js

@@ -43,7 +43,7 @@ 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
+  --workspace-ref <name|prefix|id>  Select a workspace for apex findings --workspace only
   --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
@@ -90,6 +90,7 @@ Tips:
   After a guest scan, run apex claim on the same machine within the displayed claim deadline to keep the results.
   Claim moves trial results into the selected Cantina workspace when you can run scans there, or into your existing personal workspace.
   Service-key commands require an existing login; run apex login first when needed.
+  APEX_SERVICE_KEY authenticates the hosted REST API only; it does not replace apex login for CLI commands.
   Apex automatically selects your company when only one is available. With multiple companies, choose one interactively or pass --company.
   Service-key creation also requires --name and reveals the secret only once; omit --scope to grant all hosted API scopes.
   Service-key management is available only in the scripted CLI, not the interactive shell or MCP server.
@@ -97,6 +98,7 @@ Tips:
   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 --company <handle> --workspace-ref <ref> --finding-state open to retrieve findings needing review without changing the local binding.
+  To run scans or exports against a different workspace, bind it first with apex workspace use <ref>.
   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.

package/dist/service-key-environment.js

@@ -0,0 +1,22 @@
+const APEX_SERVICE_KEY_PREFIX = "apex_sk_";
+export function detectApexServiceKeyEnvironment(env = process.env) {
+    for (const variableName of ["APEX_SERVICE_KEY", "APEX_API_KEY"]) {
+        const value = env[variableName]?.trim();
+        if (value?.startsWith(APEX_SERVICE_KEY_PREFIX)) {
+            return variableName;
+        }
+    }
+    return null;
+}
+export function getServiceKeyCliAuthGuidance(env = process.env) {
+    const variableName = detectApexServiceKeyEnvironment(env);
+    if (!variableName) {
+        return null;
+    }
+    const legacyVariableGuidance = variableName === "APEX_API_KEY"
+        ? " For REST API examples, rename APEX_API_KEY to APEX_SERVICE_KEY."
+        : "";
+    return (`Apex service key detected in ${variableName}, but service keys authenticate the hosted REST API, not the Apex CLI. ` +
+        "Use `apex login` for CLI device authentication, or use the REST API for a headless/service-account integration: https://ai.cantina.xyz/docs/apex-api." +
+        legacyVariableGuidance);
+}

package/dist/telemetry.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { KNOWN_CLI_FLAG_NAMES, } from "./args.js";
 import { loadConfig, updateConfig } from "./config.js";
 import { containsSensitiveText } from "./redaction.js";
 import { APEX_CLI_VERSION } from "./version.js";
@@ -9,41 +10,6 @@ const TELEMETRY_ENDPOINT_PATH = "/api/cli/v1/telemetry/events";
 const TELEMETRY_SESSION_ID = randomUUID();
 const TELEMETRY_TIMEOUT_MS = 750;
 const telemetryContext = new AsyncLocalStorage();
-const KNOWN_CLI_FLAG_NAMES = [
-    "comment",
-    "company",
-    "content",
-    "dismissal-reason",
-    "expires-at",
-    "fix-pr-url",
-    "force",
-    "format",
-    "filter",
-    "finding-state",
-    "help",
-    "json",
-    "label",
-    "limit",
-    "mode",
-    "name",
-    "no-open",
-    "non-interactive",
-    "output",
-    "parent-comment",
-    "pr",
-    "pr-path",
-    "replace",
-    "repo",
-    "review-target",
-    "scan",
-    "scope",
-    "source-mode",
-    "status",
-    "suggested-severity",
-    "workspace-name",
-    "workspace-ref",
-    "workspace",
-];
 const KNOWN_CLI_COMMANDS = [
     "cancel-scan",
     "connect",

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -62,8 +62,8 @@ Guidelines:
 - 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.
-- For a headless HTTP adapter, read the service key from a secret-backed environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch MCP from the adapter.
-- Hosted API v1 requires the GitHub repository to be linked to an active Apex workspace. It never creates or mutates workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors.
+- 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 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.
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.