Just want to connect your agent?
Copy the setup prompt into Claude Code, Codex, Cursor, or Copilot. Your agent handles setup and reads your existing scan results.
01What Apex CLI is
Apex CLI is the standalone Apex client. It ships an interactive shell, a scripted command surface, and a stable apex-mcp server over stdio. apex setup registers Apex with Claude Code, Codex CLI, and GitHub Copilot CLI and installs their skills. The current published package is @cantinasecurity/apex-cli, version 0.1.28, published August 24, 2026.
Building a headless integration?
The local CLI and stdio MCP use device login for people and coding agents. Use hosted MCP at https://ai.cantina.xyz/mcp when a production agent needs Streamable HTTP and a static organization service key. Use the REST service API when a serverless function, cron job, or internal audit hub needs explicit HTTP and JSON control. On hosted, non-demo company tenants, active, verified organization managers and Apex administrators can generate one from company Settings under Service API keys. Active, verified personal-tenant owners use apex service-key create instead. On-prem deployments do not support hosted service API key management.
02Install the CLI
npm install -g @cantinasecurity/apex-cli
# or
pnpm add -g @cantinasecurity/apex-cliThe npm package requires Node.js 20 or newer. The install commands use the latest npm dist tag; this page was checked against @cantinasecurity/apex-cli@0.1.28.
Then register Apex with installed agent CLIs and install skills:
apex setup # registers with whichever CLIs are installed
apex setup claude # Claude Code only
apex setup codex # Codex CLI only
apex setup copilot # GitHub Copilot CLI only
apex update # upgrade in placeWhat apex setup does
Registers Apex as an MCP server in installed Codex, Claude Code, and GitHub Copilot CLI clients, installs the Codex skill into $CODEX_HOME/skills/apex-cli, installs the Claude project skill into .claude/skills/apex-cli in the current repository, and installs the GitHub Copilot CLI skill into $COPILOT_HOME/skills/apex-cli or ~/.copilot/skills/apex-cli. Published setup registrations launch the current npm release when the client starts, so an old global apex-mcp does not remain active indefinitely. Re-run setup after upgrading to refresh copied skill files.
03Sign in to Apex
apex login # starts device login
apex workspaces # lists your existing workspacesAlready ran a scan? Use apex workspace use with its workspace name, prefix, or ID before reading results. Run apex doctor only after selecting the workspace when you need to check source planning: on an unbound directory, it can resolve or create a workspace.
The default host is https://ai.cantina.xyz/. Use APEX_BASE_URL only when testing against a non-production Apex host.
APEX_SERVICE_KEY authenticates the hosted MCP and REST endpoints. It does not authenticate local CLI or stdio MCP commands, which use device login. apex doctor reports this distinction when it detects a service key but no local device-login session. APEX_API_KEY is recognized for that migration diagnostic, but APEX_SERVICE_KEY is the documented hosted-integration variable.
04Use with Claude Code
apex setup claude
# or, manually:
claude mcp add apex --scope user -e APEX_MCP_CLIENT=claude -e APEX_CLIENT_INTEGRATION=claude -- apex-mcpExpected result: Apex appears as a connected MCP server inside Claude Code and apex-* tools are available. If an installed Claude build rejects the user-scope option, apex setup claude safely preserves the same registration in the Claude user config.
05Use with Codex CLI
apex setup codex
# or, manually:
codex mcp add apex --env APEX_MCP_CLIENT=codex --env APEX_CLIENT_INTEGRATION=codex -- apex-mcp06Use with GitHub Copilot CLI
apex setup copilot
# or, manually:
copilot mcp add apex --tools "*" -- apex-mcp07Prompt examples
Phrases that work well from inside Claude Code, Codex CLI, GitHub Copilot CLI, or any other MCP-aware agent.
08Interactive shell
Bare apex opens the interactive shell. Slash commands inside it:
/credits
/scan [standard|audit|lite]
/scan pr <pr-number>
/scans
/findings [scan-id]
/findings workspace [filter...]
/findings comment <finding-ref> <comment>
/findings feedback <finding-ref> valid [comment]
/findings feedback <finding-ref> invalid <false-positive|by-design|not-relevant> [comment]
/findings fix-review <finding-ref>
/export [scan-id]
/workspaces
/workspace use <ref>
/workspace name <name>
/cancel-scan [scan-id]
/status
/doctor
/repos
/company [id|handle]
/connect github
/connect gitlab
/open
/clear
/update
/claim
/logout
/help
/exit09Scripted commands
apex credits
apex scan
apex scan --mode audit
apex scan --mode lite
apex scan --mode pr --pr <number> [--pr <number>] [--pr-path <path>]
apex scans
apex findings [--scan <scan-id>]
apex findings --workspace [--filter <[!]facet:value>]
apex findings comment <finding-id|finding-identifier> --content <markdown> [--parent-comment <comment-id>] [--scan <scan-id>]
apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant] [--label acknowledged|fixed] [--fix-pr-url <github-pr-url>]
apex findings fix-review <finding-id|finding-identifier> [--scan <scan-id>]
apex export findings [--scan <id>] [--format markdown|json|gitlab-sast] [--output <path>]
apex workspaces
apex workspace
apex workspace use <name|prefix|id>
apex cancel-scan [scan-id]
apex status [--scan <scan-id>]
apex doctor
apex login
apex redeem <trial-code> [--replace] [--json]
apex claim [--no-open] [--json]
apex logout
apex service-key create --name <name> [--company <id-or-handle>] [--scope <scope[,scope]>] [--expires-at <ISO-8601>] [--json]
apex service-key list [--company <id-or-handle>] [--json]
apex service-key revoke <key-id> [--company <id-or-handle>] [--json]
apex setup [all|codex|claude|copilot]
apex telemetry [status|enable|disable]
apex update
apex connect github
apex connect gitlabCommon flags
| --company <id-or-handle> | Target a specific company |
| --workspace-name <name> | Pin or create a named workspace |
| --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 for apex findings --workspace only |
| --finding-state all|open | Return every finding or only unresolved, non-duplicate findings |
| --filter <[!]facet:value> | Filter workspace findings (repeatable) |
| --format markdown|json|gitlab-sast | Export format |
| --output <path> | Output path for exports |
| --limit <count> | Cap list length |
| --mode standard|audit|lite|pr | Choose the scan type |
| --pr <number[:path,path]> | Select one or more GitHub PRs for PR scans |
| --pr-path <path> | Limit a single PR scan to changed paths |
| --source-mode auto|remote|local | Source materialization |
| --repo <path> | Constrain to a repo path (repeatable) |
| --force | Skip confirmation |
| --replace | Replace an existing guest trial session |
| --json | Machine-readable output |
| --no-open | Don't open the browser |
| --non-interactive | Fail fast in scripts |
| --content <markdown> | Body for a finding comment |
| --comment <markdown> | Rationale for finding feedback |
| --dismissal-reason false-positive|by-design|not-relevant | Required for invalid feedback |
| --suggested-severity extreme|critical|high|medium|low|informational | Suggested severity for valid feedback |
| --label acknowledged|fixed | Attach a finding feedback label |
| --fix-pr-url <github-pr-url> | Attach one or more Fix PR URLs |
10Run a scan
apex scan
apex scan --mode audit
apex scan --mode lite
apex scan --mode pr --pr 42
apex scan --mode pr --pr 42:src/auth.ts,src/policy.ts
apex scan --source-mode local
apex scan --repo ./services/api --repo ./services/worker
apex status # progress on the latest scan
apex status --scan <scan-id>
apex scans # recent scans
apex findings # latest scan's findings
apex findings --scan <scan-id>
apex findings --workspace --workspace-ref BEDR9 --company apex-internal --finding-state open
apex export findings --format markdown --output findings.mdAnalyze the whole workspace
Use apex findings --workspace --workspace-ref BEDR9 --company apex-internal --finding-state open, or call apex-workspace-findings with company: "apex-internal", workspaceRef: "BEDR9", findingState: "open". This direct selector does not depend on the current directory's workspace binding. Open findings exclude invalid findings, duplicates, and findings marked fixed, false positive, won't fix, or skipped. Stable web-UI filter facets are available with the same values: severity, scan, repo, review, impact, likelihood, status, validation, visibility, duplicate, and source. Finding statuses are proposed, partially_valid, valid, invalid, or duplicate;open is a finding state, not a status filter.
Workspace selection is explicit
--workspace-ref is supported only by apex findings --workspace. To list scans or export findings for a different workspace, bind it first with apex workspace use <name|prefix|id>. Unsupported or misspelled flags fail instead of silently falling back to the current local binding.
- Let Apex resolve the workspaceRun apex scan from the repository root. Apex uses the current folder as the default workspace name unless you pass --workspace-name.
- Keep source planning explicit when neededBy default, Apex scans the current directory. Use --repo for specific roots and --source-mode local when you want a snapshot of the exact working tree.
- Use the current scan-mode namesUse standard for normal scans, audit for audit scans, lite for beta-enabled Lite scans, and pr with --pr for GitHub pull request scans. The old ultra mode is still accepted only as a legacy alias for audit.
Local snapshots and provider-backed scans
Standard scans can use local snapshot uploads for dirty git worktrees and plain directories. Audit and Lite scans require provider-backed GitHub or GitLab sources that Apex can materialize remotely; Lite scans also require beta access. PR scans require one provider-backed GitHub repository.
PR scans can overlap active scans
Apex CLI 0.1.27 lets a new PR scan start while another workspace scan is active. Starting a new Standard, Audit, or Lite scan still asks for confirmation unless you pass --force.
11Review findings
Apex CLI can now add finding comments, mark findings valid or invalid, attach Fix PR URLs, and start fix review scans.
apex findings comment KERN2-25 --content "Needs auth boundary check"
apex findings feedback KERN2-25 valid --comment "Reproduced on latest build"
apex findings feedback KERN2-25 invalid --dismissal-reason false-positive --comment "Unreachable path"
apex findings feedback KERN2-25 valid --label fixed --fix-pr-url https://github.com/acme/app/pull/123 --comment "Fixed in PR #123"
apex findings fix-review KERN2-25Feedback authentication
Finding comments, feedback, and fix review scans use the same Apex CLI device-login credentials as read operations. MCP clients should complete apex-auth-start and apex-auth-wait, then call the finding write tools without asking users to paste browser cookies or auth tokens.
Asked for a browser-session token?
That requirement comes from an outdated MCP server. Update Apex CLI, re-run apex setup <client>, restart the client, and retry. Do not copy browser credentials into MCP configuration.
End-to-end Fix Review
Use the Fix Review workflow guide when a CLI or MCP workflow needs to line up finding feedback, Fix PR URLs, branch targets, and final verdict handling.
12MCP tools
Local stdio MCP
Agent clients working in a repository should prefer the local Apex MCP server over shelling out. Use apex setup for automatic registration, or manually point clients at the stable apex-mcp binary.
| apex-auth-status / apex-auth-start / apex-auth-wait | Check auth and complete device login without opening a browser |
| apex-trial-status | Read local guest-session and claim deadlines without exposing trial secrets |
| apex-doctor | Validate auth, detected sources, provider access, workspace binding, and source materialization |
| apex-workspace | Read the current local workspace binding without resolving or creating a workspace |
| apex-workspaces / apex-workspace-use | List workspaces and bind the current directory by name, prefix, or ID |
| apex-scan | Start standard, audit, Lite, or PR scans with explicit cwd, repoPaths, sourceMode, pullRequests, and force inputs |
| apex-status / apex-scans / apex-cancel-scan | Monitor the latest or selected scan, list workspace scans, and cancel scans |
| apex-findings / apex-export-findings | Inspect or export one scan's findings |
| apex-workspace-findings | Inspect all scans in a selected workspace, including a first-class open-finding view |
| apex-finding-comment / apex-finding-feedback | Leave comments or valid/invalid feedback on a finding |
| apex-finding-fix-review | Start a fix review scan after fixed feedback has a Fix PR URL |
codex mcp add apex --env APEX_MCP_CLIENT=codex --env APEX_CLIENT_INTEGRATION=codex -- apex-mcp
claude mcp add apex --scope user -e APEX_MCP_CLIENT=claude -e APEX_CLIENT_INTEGRATION=claude -- apex-mcp
copilot mcp add apex --tools "*" -- apex-mcpPlugin installs use the published package
Marketplace and plugin installs launch the pinned npm package with npx -y -p @cantinasecurity/apex-cli@0.1.28 apex-mcp, so users do not need a global apex install before enabling the plugin.
Hosted HTTPS MCP
Production agents can connect to https://ai.cantina.xyz/mcp over Streamable HTTP and send Authorization: Bearer <service-key>. The hosted surface is intentionally limited to operations that do not require a caller's filesystem, browser, or interactive device login.
| apex-credits / apex-workspaces | Check credit availability and resolve a connected GitHub repository |
| apex-scan | Start a standard, audit, or Lite scan for an exact full commit SHA with a stable idempotency key |
| apex-status / apex-cancel-scan | Monitor or cancel a selected scan |
| apex-findings | Fetch a completed scan's findings as GitLab SAST, including drafts |
| apex-workspace-findings | Fetch the workspace findings-browser set with optional filters |
export APEX_SERVICE_KEY='<service-key>'
codex mcp add apex --url https://ai.cantina.xyz/mcp --bearer-token-env-var APEX_SERVICE_KEYSee the service API guide for service-key scopes, Claude Code configuration, retry rules, and the exact hosted/local boundary.
13Usage telemetry
Apex CLI 0.1.28 emits first-party, privacy-preserving usage telemetry for direct CLI, interactive shell, and MCP usage. Telemetry is enabled by default and can be inspected or disabled locally:
apex telemetry status
apex telemetry disable
apex telemetry enable
APEX_TELEMETRY_DISABLED=1 apex scanTelemetry records lifecycle events, duration, success or failure category, CLI version, Node and platform basics, anonymous install and session IDs, and sanitized command metadata. It does not send raw cwd paths, repository URLs, finding IDs, scan IDs, PR URLs, comments, file paths, trial codes, claim tokens, onboarding fingerprints, bearer credentials, or raw flag values.
14Troubleshooting
- If apex isn't found, confirm your global bin directory is on PATH.
- Apex CLI requires Node.js 20 or newer.
- If setup skips a client, confirm the claude, codex, or copilot CLI is installed. Explicit setup targets require the matching CLI.
- Make sure MCP clients launch apex-mcp directly, not pnpm mcp without --silent.
- A service key in APEX_SERVICE_KEY or APEX_API_KEY does not sign the local CLI or local stdio MCP in. Use apex login for local device authentication, or use https://ai.cantina.xyz/mcp or the REST API for headless workflows.
- If you need to inspect or opt out of local usage telemetry, run apex telemetry status, apex telemetry disable, or set APEX_TELEMETRY_DISABLED=1.
- If browser launch fails during login, copy the verification URL manually.
- If you have a Cantina trial code, run apex redeem <code> in a terminal instead of starting device login. Trial codes are not accepted by MCP tools.
- When redeeming with --json, parse stdout only. Keep npm warnings from stderr separate; an idempotent outcome resumes the existing guest session and may already have a workspace.
- Guest standard scans validate the full local archive before reserving a workspace. An unbound renamed checkout may recover only the sole empty guest workspace when no explicit workspace name was supplied.
- If sources aren't found, run apex doctor from the repository root or pass --repo <path>.
- If remote materialization fails, retry with --source-mode local unless you specifically need provider-backed remote materialization.
- Audit and Lite scans require provider-backed GitHub or GitLab sources. Local snapshot fallback is for standard scans.
- Lite scans also require the Lite Scan beta feature and an available Lite scan entitlement.
- PR scans require a provider-backed GitHub repository and --mode pr --pr <number>.
- A new PR scan can start while another workspace scan is active. For standard, audit, or Lite scans, use apex status, pass --scan <scan-id> for a specific scan, or pass --force when you intentionally want to start another scan.
- Finding comments, feedback, and fix review scans use the same Apex login as read commands.
- If a finding write asks for a separate browser-session token, update Apex CLI, re-run apex setup for the client, restart it, and retry. That prompt comes from an outdated MCP server.