@cantinasecurity/apex-cli 0.1.0 → 0.1.1

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

@@ -25,9 +25,11 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Prefer scripted commands over the interactive shell.
 - Use `--non-interactive` and `--no-open` for automation-friendly CLI calls.
 - Use `--json` whenever structured output is helpful.
+- `apex credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
 - Work from the target repository directory so Apex can resolve `.apex/workspace.json`.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Plain local directories and dirty git worktrees can scan through local snapshot uploads without provider access.
+- Audit scans use `--mode audit` in user-facing CLI calls. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 

package/README.md

@@ -98,7 +98,7 @@ If Apex asks for a workspace name, that is the Apex workspace name for the curre
 Supported shell commands:
 
 - `/credits`
-- `/scan [standard|ultra]`
+- `/scan [standard|audit]`
 - `/scans`
 - `/findings [scan-id]`
 - `/export [scan-id]`
@@ -147,6 +147,8 @@ Helpful workspace flags:
 - `--company <id-or-handle>` to choose the Apex company when more than one is available
 - `--workspace-name <name>` to set the Apex workspace name for this directory
 
+`apex credits` shows standard scan credits plus audit scan entitlements when the server returns them.
+
 ## Local Source Scans
 
 `apex scan` now works against any local source root you point it at:
@@ -159,10 +161,11 @@ Useful flags:
 
 - `--repo <path>` to scan one or more explicit local roots
 - `--source-mode auto|remote|local` to control remote-first fallback behavior
+- `--mode standard|audit` to choose the scan mode
 
 `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.
 
-Ultra scans still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback.
+Audit scans 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 for the audit scan mode.
 
 ## LLM / MCP Usage
 
@@ -243,7 +246,7 @@ For Claude Code, the packaged project skill can be installed into the current re
 
 ## Development Notes
 
-The CLI uses the Apex `/api/cli/v2/**` local-source routes for scan planning and snapshot uploads, with legacy `/api/cli/v1/**` routes still used for provider-backed flows such as ultra scans. Local state is stored under:
+The CLI uses the Apex `/api/cli/v2/**` local-source routes for scan planning and snapshot uploads, with legacy `/api/cli/v1/**` routes still used for provider-backed flows such as audit scans. Local state is stored under:
 
 - `~/.config/apex/config.json`
 - `~/.config/apex/credentials.json`

package/dist/commands.js

@@ -36,6 +36,37 @@ function getSuggestedWorkspaceRef(workspace) {
 function formatWorkspaceUseCommand(workspace) {
     return `apex workspace use ${formatCommandArgument(getSuggestedWorkspaceRef(workspace))}`;
 }
+function getOptionalCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : null;
+}
+function formatAuditScanBalance(scanBalance) {
+    const purchased = getOptionalCount(scanBalance.auditPurchased);
+    const used = getOptionalCount(scanBalance.auditUsed);
+    const remaining = getOptionalCount(scanBalance.auditRemaining);
+    const available = getOptionalCount(scanBalance.auditAvailable) ??
+        remaining ??
+        (purchased !== null && used !== null ? Math.max(0, purchased - used) : null);
+    if (purchased === null && used === null && available === null) {
+        return null;
+    }
+    const detailParts = [];
+    if (purchased !== null) {
+        detailParts.push(`${purchased} purchased`);
+    }
+    if (used !== null) {
+        detailParts.push(`${used} used`);
+    }
+    if (available !== null) {
+        const detailSuffix = detailParts.length ? ` (${detailParts.join(", ")})` : "";
+        return `Audit scans: ${available} available${detailSuffix}`;
+    }
+    return `Audit scans: ${detailParts.join(", ")}`;
+}
+function normalizeRequestedScanMode(value) {
+    return value === "ultra" || value === "audit" ? "ultra" : "standard";
+}
 async function requireWorkspaceBinding(cwd) {
     const binding = await loadWorkspaceBinding(cwd);
     if (binding) {
@@ -144,7 +175,15 @@ export async function commandCredits(client, cwd, flags) {
         return payload;
     }
     logLine(`Company: ${payload.company.handle ?? payload.company.id}`, flags);
-    logLine(`Credits: ${payload.scanBalance.remaining} remaining (${payload.scanBalance.purchased} purchased, ${payload.scanBalance.used} used)`, flags);
+    logLine(`Standard credits: ${payload.scanBalance.remaining} remaining (${payload.scanBalance.purchased} purchased, ${payload.scanBalance.used} used)`, flags);
+    const auditBalance = formatAuditScanBalance(payload.scanBalance);
+    if (auditBalance) {
+        logLine(auditBalance, flags);
+    }
+    const redeemableAuditScans = getOptionalCount(payload.scanBalance.auditRedeemableFromCredits);
+    if (redeemableAuditScans && redeemableAuditScans > 0) {
+        logLine(`Redeemable audit scans from standard credits: ${redeemableAuditScans}`, flags);
+    }
     logLine(`Scans enabled: ${payload.scansEnabled ? "yes" : "no"}`, flags);
     return payload;
 }
@@ -244,7 +283,7 @@ export async function commandScan(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const selection = await selectWorkspaceTarget(cwd, me, flags);
     const result = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelection(client, selection));
-    const requestedMode = getFlagString(flags, "mode") === "ultra" ? "ultra" : "standard";
+    const requestedMode = normalizeRequestedScanMode(getFlagString(flags, "mode"));
     if (!result.resolve.workspaceId) {
         throw new Error("Workspace resolution did not return a workspaceId.");
     }
@@ -255,14 +294,14 @@ export async function commandScan(client, cwd, flags) {
     let scan;
     if (requestedMode === "ultra") {
         if (!supportsLegacyRemoteFlow(result.resolve.plannedSources)) {
-            throw new Error("Ultra scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.");
+            throw new Error("Audit scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.");
         }
-        const legacyResolve = await withLoadingIndicator("Preparing ultra scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
+        const legacyResolve = await withLoadingIndicator("Preparing audit 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 ultra scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+        scan = await withLoadingIndicator("Starting audit scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
             method: "POST",
             json: {
                 mode: requestedMode,

package/dist/help.js

@@ -1,6 +1,6 @@
 export const CLI_HELP_TEXT = `Usage:
   apex                              Open the interactive Apex shell
-  apex credits                      Show scan credits for the active company
+  apex credits                      Show scan credits and audit scan entitlements for the active company
   apex scan                         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
@@ -28,7 +28,7 @@ Flags:
                                     Choose the export format for findings
   --output <path>                   Write exported findings to this file path
   --limit <count>                   Limit the number of findings returned
-  --mode standard|ultra             Choose the scan mode
+  --mode standard|audit             Choose the scan mode
   --source-mode auto|remote|local   Control remote-vs-local source materialization
   --force                           Start a new scan even if another scan is active
   --repo <path>                     Include one or more explicit local source roots
@@ -39,6 +39,7 @@ Flags:
 
 Tips:
   apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
+  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   apex workspace use accepts a workspace name, prefix, or ID.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
@@ -46,8 +47,8 @@ Tips:
 export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common arguments.
 
 Commands:
-  /credits                Show scan credits for the active company
-  /scan [standard|ultra]  Start a new Apex scan for this workspace
+  /credits                Show scan credits and audit scan entitlements for the active company
+  /scan [standard|audit]  Start a new Apex scan for this workspace
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
   /export [scan-id]       Export findings for the latest or selected scan
@@ -70,6 +71,7 @@ Commands:
   /exit                   Exit Apex
 
 Tips:
+  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   /workspace use accepts a workspace name, prefix, or ID.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;

package/dist/mcp.js

@@ -19,6 +19,7 @@ Suggested workflow:
 Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
+- Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias.
 - Doctor reports whether Apex will use remote materialization or a local snapshot upload for each source.`;
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const MISSING_PROVIDER_CONNECTIONS_ERROR = "Missing provider connections. Re-run interactively or pre-connect providers.";
@@ -248,7 +249,7 @@ function registerTools(server) {
     }, (value) => `Apex doctor completed for ${String(value.cwd)}.`));
     server.registerTool("apex-credits", {
         title: "Get Apex Credits",
-        description: "Show scan credits for the active or selected company.",
+        description: "Show scan credits and audit scan entitlements for the active or selected company.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
@@ -320,13 +321,13 @@ function registerTools(server) {
     }, (value) => `Bound ${String(value.cwd)} to an Apex workspace.`));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for any local repository or directory. Pass cwd explicitly for reliable workspace resolution.",
+        description: "Start a new Apex scan for any local repository or directory. Pass cwd explicitly for reliable workspace resolution. Use mode audit for audit scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
             workspaceName: z.string().optional(),
             repoPaths: z.array(z.string()).optional(),
-            mode: z.enum(["standard", "ultra"]).optional(),
+            mode: z.enum(["standard", "audit", "ultra"]).optional(),
             sourceMode: z.enum(["auto", "remote", "local"]).optional(),
             force: z.boolean().optional(),
         },

package/dist/scan.js

@@ -30,6 +30,10 @@ function readNumber(...values) {
     }
     return null;
 }
+function readScanMode(...values) {
+    const mode = readString(...values);
+    return mode === "ultra" ? "audit" : mode;
+}
 function getScanListItems(payload) {
     if (Array.isArray(payload)) {
         return payload;
@@ -63,7 +67,7 @@ function normalizeScanRecord(payload) {
         displayName: readString(record.displayName, record.display_name, record.name),
         sequenceNumber: readNumber(record.sequenceNumber, record.sequence_number),
         status: readString(record.status) ?? "unknown",
-        mode: readString(record.mode, record.scanType, record.scan_type),
+        mode: readScanMode(record.mode, record.scanType, record.scan_type),
         scanUrl: readString(record.scanUrl, record.url, record.scan_url),
         createdAt: readTimestamp(record, "createdAt", "created_at"),
         startedAt: readTimestamp(record, "startedAt", "started_at"),

package/dist/shell.js

@@ -6,7 +6,7 @@ import { readLine } from "./prompt.js";
 import { formatApiError } from "./api-client.js";
 const SHELL_COMPLETIONS = [
     { command: "credits" },
-    { command: "scan", args: ["standard", "ultra"] },
+    { command: "scan", args: ["standard", "audit", "ultra"] },
     { command: "scans" },
     { command: "findings" },
     { command: "export" },
@@ -178,8 +178,8 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             return {};
         case "scan": {
             const mode = parsed.args[0];
-            if (mode && !["standard", "ultra"].includes(mode)) {
-                process.stderr.write("Usage: /scan [standard|ultra]\n");
+            if (mode && !["standard", "audit", "ultra"].includes(mode)) {
+                process.stderr.write("Usage: /scan [standard|audit|ultra]\n");
                 return {};
             }
             const result = await commandScan(client, cwd, mode ? withFlag(shellFlags, "mode", mode) : shellFlags);

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -21,8 +21,10 @@ Workflow:
 Guidelines:
 
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
+- `apex-credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
+- Audit scans use `mode: "audit"` in user-facing instructions. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - `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.