@cantinasecurity/apex-cli 0.1.0

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

@@ -0,0 +1,38 @@
+---
+name: apex-cli
+description: Use when a user wants to run Apex scans, inspect findings, export results, bind workspaces, or troubleshoot Apex auth and provider setup. Prefer the Apex MCP tools when they are available, and fall back to the local Apex CLI only when MCP is unavailable.
+---
+
+# Apex CLI
+
+This skill is bundled with Apex CLI and can be installed into the current repository with `apex setup claude`.
+
+## Instructions
+
+Use Apex through the MCP server when the `apex-*` tools are available.
+
+Recommended workflow:
+
+1. Start with `apex-auth-status`.
+2. If Apex is unauthenticated, call `apex-auth-start`, ask the user to approve the device-login URL, then call `apex-auth-wait` with the returned `deviceCode`.
+3. For repository-scoped work, pass `cwd` explicitly.
+4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
+5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
+6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+
+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.
+- 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.
+- `apex-workspace-use` accepts a workspace name, prefix, or ID.
+- Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
+
+## Examples
+
+- Start a scan for the current repository or directory: run `apex-doctor`, bind a workspace if needed, then call `apex-scan`.
+- Check an active scan: call `apex-status`, then `apex-findings` when the scan completes.
+- Export findings for review: call `apex-export-findings` with `format` set to `markdown`, `json`, or `gitlab-sast`.

package/README.md

@@ -0,0 +1,259 @@
+# Apex CLI
+
+Standalone CLI client for Apex.
+
+## Installing And Updating
+
+For a public install, use a global package manager install:
+
+```bash
+npm install -g @cantinasecurity/apex-cli
+# or: pnpm add -g @cantinasecurity/apex-cli
+```
+
+Then run:
+
+```bash
+apex setup
+```
+
+`apex setup` is the lowest-friction path for agent clients. It:
+
+- registers Apex as an MCP server in any installed Codex and Claude Code CLIs
+- installs the Codex skill into `$CODEX_HOME/skills/apex-cli`
+- installs the Claude project skill into `.claude/skills/apex-cli` in the current repository
+
+If you only want one client, run:
+
+```bash
+apex setup codex
+apex setup claude
+```
+
+If one client is not installed yet, `apex setup` skips it automatically. If you target a client explicitly, its CLI must already be installed.
+
+Update a global install with:
+
+```bash
+apex update
+```
+
+You can also update directly with your package manager:
+
+```bash
+npm install -g @cantinasecurity/apex-cli
+# or: pnpm add -g @cantinasecurity/apex-cli
+```
+
+If you are running Apex CLI from a local checkout instead, update it with:
+
+```bash
+git pull --ff-only
+pnpm install
+```
+
+MCP registrations keep working across package updates because they point at the stable `apex-mcp` shim. Re-run `apex setup` after upgrading if you want to refresh copied skill files, and run `apex setup claude` in each repository where you want the Claude project skill.
+
+When `apex` is run in an interactive terminal, it checks for updates periodically and offers to install them.
+
+## Local Development
+
+1. Install dependencies:
+
+```bash
+pnpm install
+```
+
+2. Run the CLI:
+
+```bash
+pnpm apex
+```
+
+By default, the CLI targets `https://ai.cantina.xyz/`.
+
+Use `APEX_BASE_URL` only when testing against a non-production Apex host:
+
+```bash
+APEX_BASE_URL=https://preview.cantina.xyz pnpm apex
+```
+
+## Interactive Shell
+
+Bare `apex` opens the interactive shell:
+
+```text
+$ apex
+
+Apex CLI
+Connected to https://ai.cantina.xyz/
+Type /scan to start a scan for this directory, /workspaces to browse workspace names, /workspace use "<name>" to switch, /help for commands.
+apex>
+```
+
+In interactive terminals, Apex now shows a loading indicator while it resolves workspaces, loads scans, and starts commands.
+
+If Apex asks for a workspace name, that is the Apex workspace name for the current directory. Press Enter to accept the current folder name, or pass `--workspace-name <name>` explicitly.
+
+Supported shell commands:
+
+- `/credits`
+- `/scan [standard|ultra]`
+- `/scans`
+- `/findings [scan-id]`
+- `/export [scan-id]`
+- `/workspaces`
+- `/cancel-scan [scan-id]`
+- `/status`
+- `/doctor`
+- `/update`
+- `/logout`
+- `/repos`
+- `/workspace`
+- `/workspace use <workspace-name|workspace-prefix|workspace-id>`
+- `/workspace name <name>`
+- `/company [id|handle]`
+- `/connect github`
+- `/connect gitlab`
+- `/open`
+- `/clear`
+- `/help`
+- `/exit`
+
+`/workspace use` accepts a workspace name, prefix, or ID. Quote workspace names that contain spaces, for example `/workspace use "Core Platform"`.
+
+## Scripted Commands
+
+- `apex credits`
+- `apex scan`
+- `apex scans`
+- `apex findings [--scan <scan-id>]`
+- `apex export findings [--scan <scan-id>] [--format markdown|json|gitlab-sast] [--output <path>]`
+- `apex workspaces`
+- `apex workspace`
+- `apex workspace use <workspace-name|workspace-prefix|workspace-id>`
+- `apex cancel-scan [scan-id]`
+- `apex status`
+- `apex doctor`
+- `apex login`
+- `apex logout`
+- `apex setup [all|codex|claude]`
+- `apex update`
+- `apex connect github`
+- `apex connect gitlab`
+
+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
+
+## Local Source Scans
+
+`apex scan` now works against any local source root you point it at:
+
+- clean GitHub or GitLab checkouts can stay on the remote-materialization path
+- dirty git worktrees fall back to a local snapshot upload by default
+- plain directories that are not git repositories are scanned through a local snapshot upload
+
+Useful flags:
+
+- `--repo <path>` to scan one or more explicit local roots
+- `--source-mode auto|remote|local` to control remote-first fallback behavior
+
+`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.
+
+## LLM / MCP Usage
+
+The CLI now ships an MCP server so LLM clients can drive Apex directly over stdio.
+
+If Apex is installed globally, prefer:
+
+```bash
+apex setup
+```
+
+That registers Apex for installed Codex and Claude Code clients automatically.
+
+If you want to wire clients manually instead, Apex ships a stable `apex-mcp` binary. For Codex:
+
+```bash
+codex mcp add apex -- apex-mcp
+```
+
+For Claude Code:
+
+```bash
+claude mcp add --scope user apex -- apex-mcp
+```
+
+For any other MCP client, configure it to launch:
+
+```json
+{
+  "mcpServers": {
+    "apex": {
+      "command": "apex-mcp"
+    }
+  }
+}
+```
+
+From a local checkout during development, prefer the repo-local binary so the MCP stream stays clean:
+
+```json
+{
+  "mcpServers": {
+    "apex": {
+      "command": "/path/to/apex-cli/bin/apex-mcp"
+    }
+  }
+}
+```
+
+If you need to launch through `pnpm`, use `--silent`:
+
+```json
+{
+  "mcpServers": {
+    "apex": {
+      "command": "pnpm",
+      "args": ["--silent", "mcp"],
+      "cwd": "/path/to/apex-cli"
+    }
+  }
+}
+```
+
+Do not point an MCP client at plain `pnpm mcp`. `pnpm` writes its script banner to `stdout` before the protocol stream, which can break the `initialize` handshake.
+
+The MCP server exposes Apex-specific tools for:
+
+- auth status and device login
+- doctor, credits, and provider connection URLs
+- workspace inspection and workspace binding
+- scan start, status, cancellation, findings, and findings export
+
+For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
+
+For Codex-style clients, the packaged skill can be installed with `apex setup codex`. The repo-local source lives at `skills/apex-cli/SKILL.md`.
+
+For Claude Code, the packaged project skill can be installed into the current repository with `apex setup claude`. The repo-local source lives at `.claude/skills/apex-cli/SKILL.md`. Anthropic documents project skills as filesystem directories under `.claude/skills/<name>/SKILL.md`, and the Claude Agent SDK uses the same location when the `Skill` tool is enabled.
+
+## 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:
+
+- `~/.config/apex/config.json`
+- `~/.config/apex/credentials.json`
+- `.apex/workspace.json`
+
+If a scan is already running in the current workspace, `apex scan` and `/scan` now require confirmation before starting another one. Scripted usage can opt in explicitly with `--force`.
+
+To move between existing Apex workspaces from the CLI:
+
+1. Run `apex workspaces` to list the workspaces available to your active company.
+2. Run `apex workspace use <workspace-name|workspace-prefix|workspace-id>` to bind the current directory.
+3. If the workspace name contains spaces, quote it, for example `apex workspace use "Core Platform"`.
+4. Use `apex scans`, `apex findings`, and `apex export findings` against that binding.

package/dist/apex.js

@@ -0,0 +1,94 @@
+import { ApexApiClient, formatApiError } from "./api-client.js";
+import { parseArgs } from "./args.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { CLI_HELP_TEXT } from "./help.js";
+import { runMcpServer } from "./mcp.js";
+import { runInteractiveShell } from "./shell.js";
+import { maybePromptForUpdate } from "./update.js";
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.flags.help === true || parsed.command === "help") {
+        process.stdout.write(CLI_HELP_TEXT);
+        return;
+    }
+    if (parsed.command === "mcp") {
+        await runMcpServer();
+        return;
+    }
+    const client = new ApexApiClient();
+    const cwd = process.cwd();
+    if (await maybePromptForUpdate(parsed.flags, parsed.command)) {
+        return;
+    }
+    switch (parsed.command) {
+        case null:
+            await runInteractiveShell(client, cwd, parsed.flags);
+            return;
+        case "scan":
+            await commandScan(client, cwd, parsed.flags);
+            return;
+        case "scans":
+            await commandScans(client, cwd, parsed.flags);
+            return;
+        case "cancel-scan":
+            await commandCancelScan(client, cwd, parsed.flags, parsed.subcommand);
+            return;
+        case "login":
+            await commandLogin(client, parsed.flags);
+            return;
+        case "logout":
+            await commandLogout(client, parsed.flags);
+            return;
+        case "update":
+            await commandUpdate(parsed.flags);
+            return;
+        case "setup":
+            await commandSetup(cwd, parsed.flags, parsed.subcommand);
+            return;
+        case "doctor":
+            await commandDoctor(client, cwd, parsed.flags);
+            return;
+        case "credits":
+            await commandCredits(client, cwd, parsed.flags);
+            return;
+        case "workspaces":
+            await commandWorkspaces(client, cwd, parsed.flags);
+            return;
+        case "workspace":
+            if (parsed.subcommand === "use") {
+                const workspaceRef = parsed.args.join(" ");
+                await commandWorkspaceUse(client, cwd, parsed.flags, workspaceRef);
+                return;
+            }
+            await commandWorkspace(cwd, parsed.flags);
+            return;
+        case "findings":
+            await commandFindings(client, cwd, parsed.flags);
+            return;
+        case "export":
+            if (parsed.subcommand && parsed.subcommand !== "findings") {
+                throw new Error("Usage: apex export [findings]");
+            }
+            await commandExportFindings(client, cwd, parsed.flags);
+            return;
+        case "status":
+            await commandStatus(client, cwd, parsed.flags);
+            return;
+        case "connect":
+            if (parsed.subcommand !== "github" && parsed.subcommand !== "gitlab") {
+                throw new Error("Usage: apex connect <github|gitlab>");
+            }
+            await commandConnect(client, cwd, parsed.flags, parsed.subcommand);
+            return;
+        default:
+            throw new Error(`Unknown command: ${parsed.command}`);
+    }
+}
+main().catch((error) => {
+    if (error instanceof Error && error.reported) {
+        process.exitCode = 1;
+        return;
+    }
+    process.stderr.write(`${formatApiError(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/api-client.js

@@ -0,0 +1,125 @@
+import { clearCredentials, loadConfig, loadCredentials, saveCredentials } from "./config.js";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+function getApiErrorBodyMessage(body) {
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    const error = body.error;
+    return typeof error === "string" && error.trim().length > 0 ? error : null;
+}
+export function formatApiError(error) {
+    if (error instanceof ApiError) {
+        return getApiErrorBodyMessage(error.body) ?? error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function expiresSoon(timestamp) {
+    if (!timestamp)
+        return true;
+    const time = new Date(timestamp).getTime();
+    if (!Number.isFinite(time))
+        return true;
+    return time <= Date.now() + 30_000;
+}
+async function parseResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return response.json().catch(() => null);
+    }
+    return response.text().catch(() => "");
+}
+export class ApexApiClient {
+    async getBaseUrl() {
+        const config = await loadConfig();
+        return config.baseUrl;
+    }
+    async getCredentials() {
+        return loadCredentials();
+    }
+    async clearCredentials() {
+        await clearCredentials();
+    }
+    async refreshIfNeeded() {
+        const credentials = await loadCredentials();
+        if (!credentials)
+            return null;
+        if (!expiresSoon(credentials.accessTokenExpiresAt)) {
+            return credentials;
+        }
+        return this.refreshSession(credentials.refreshToken);
+    }
+    async refreshSession(refreshToken) {
+        const existing = await loadCredentials();
+        const effectiveRefreshToken = refreshToken ?? existing?.refreshToken ?? null;
+        if (!effectiveRefreshToken)
+            return null;
+        const payload = (await this.request("/api/cli/v1/auth/refresh", {
+            method: "POST",
+            auth: false,
+            json: { refreshToken: effectiveRefreshToken },
+            retryOnUnauthorized: false,
+        }));
+        const nextCredentials = {
+            accessToken: payload.accessToken,
+            refreshToken: payload.refreshToken,
+            accessTokenExpiresAt: payload.accessTokenExpiresAt,
+            refreshTokenExpiresAt: payload.refreshTokenExpiresAt,
+        };
+        await saveCredentials(nextCredentials);
+        return nextCredentials;
+    }
+    async request(path, options = {}) {
+        const baseUrl = await this.getBaseUrl();
+        const headers = new Headers(options.headers ?? {});
+        let credentials = options.auth === false ? null : await this.refreshIfNeeded().catch(() => null);
+        if (options.json !== undefined) {
+            headers.set("Content-Type", "application/json");
+        }
+        if (credentials?.accessToken) {
+            headers.set("Authorization", `Bearer ${credentials.accessToken}`);
+        }
+        const response = await fetch(new URL(path, baseUrl), {
+            ...options,
+            headers,
+            body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+        });
+        if (response.status === 401 &&
+            options.auth !== false &&
+            options.retryOnUnauthorized !== false) {
+            credentials = await this.refreshSession();
+            if (credentials?.accessToken) {
+                headers.set("Authorization", `Bearer ${credentials.accessToken}`);
+                const retryResponse = await fetch(new URL(path, baseUrl), {
+                    ...options,
+                    headers,
+                    body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+                });
+                const retryBody = await parseResponse(retryResponse);
+                if (!retryResponse.ok) {
+                    if (retryResponse.status === 401) {
+                        await clearCredentials();
+                    }
+                    throw new ApiError(`Request failed with ${retryResponse.status}`, retryResponse.status, retryBody);
+                }
+                return retryBody;
+            }
+        }
+        const body = await parseResponse(response);
+        if (!response.ok) {
+            if (response.status === 401) {
+                await clearCredentials();
+            }
+            throw new ApiError(`Request failed with ${response.status}`, response.status, body);
+        }
+        return body;
+    }
+}

package/dist/args.js

@@ -0,0 +1,56 @@
+const BOOLEAN_FLAGS = new Set(["force", "non-interactive", "json", "no-open", "help"]);
+export function parseArgs(argv) {
+    const flags = {};
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value.startsWith("--")) {
+            positional.push(value);
+            continue;
+        }
+        const key = value.slice(2);
+        if (BOOLEAN_FLAGS.has(key)) {
+            flags[key] = true;
+            continue;
+        }
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            throw new Error(`Missing value for --${key}`);
+        }
+        if (key === "repo") {
+            const existing = flags[key] ?? [];
+            existing.push(next);
+            flags[key] = existing;
+        }
+        else {
+            flags[key] = next;
+        }
+        index += 1;
+    }
+    return {
+        command: positional[0] ?? null,
+        subcommand: positional[1] ?? null,
+        args: positional.slice(2),
+        flags,
+    };
+}
+export function isJsonMode(flags) {
+    return flags.json === true;
+}
+export function isNonInteractive(flags) {
+    return flags["non-interactive"] === true;
+}
+export function getFlagString(flags, key) {
+    const value = flags[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+export function getFlagList(flags, key) {
+    const value = flags[key];
+    return Array.isArray(value) ? value : [];
+}
+export function withFlag(flags, key, value) {
+    return {
+        ...flags,
+        [key]: value,
+    };
+}