Apex CLI guide

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.40, published October 19, 2026.

$ npm install -g @cantinasecurity/apex-cli
# or
$ pnpm add -g @cantinasecurity/apex-cli

The 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.40.

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 place

apex login     # starts device login
apex workspaces # lists your existing workspaces

Already 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.

$ apex setup claude
# or, manually:
$ claude mcp add apex --scope user -e APEX_MCP_CLIENT=claude -e APEX_CLIENT_INTEGRATION=claude -- apex-mcp

Expected 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.

Phrases that work well from inside Claude Code, Codex CLI, GitHub Copilot CLI, or any other MCP-aware agent.

Bare apex opens the interactive shell. Slash commands inside it:

/credits
/scan [standard|audit|lite] [target...]
/scan pr <pr-number>
/scans
/findings [scan-id]
/findings workspace [filter...]
/findings comment <finding-ref> <comment>
/findings status <finding-ref> <open|fixed> [note]
/findings feedback <finding-ref> valid [comment]
/findings feedback <finding-ref> invalid <false-positive|by-design|not-relevant> [comment]
/findings fix-review <finding-ref>
/findings send <finding-ref> <linear|jira>
/findings tickets <finding-ref>
/findings link-ticket <finding-ref> <linear|jira> <issue-key|url>
/export [scan-id]
/workspaces
/workspace use <ref>
/workspace name <name>
/cancel-scan [scan-id]
/status
/doctor
/repos
/company [id|handle]
/connect github
/connect gitlab
/connect forgejo
/open
/clear
/update
/claim
/logout
/help
/exit

$ apex credits
$ apex scan
$ apex scan ./contracts --mode standard
$ apex scan ./contracts/UniswapV2ERC20.sol --mode standard
$ apex scan https://github.com/Uniswap/v2-core --mode standard
$ 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 status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [--note <rationale>] [--expected-updated-at <timestamp>]
$ 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 <pr-url>]
$ apex findings fix-review <finding-id|finding-identifier> [--scan <scan-id>]
$ apex findings send <finding-ref> <linear|jira> [--scan <scan-id>] [--json]
$ apex findings tickets <finding-ref> [--scan <scan-id>] [--json]
$ apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url> [--scan <scan-id>] [--json]
$ apex export findings [--scan <id>] [--format markdown|json|gitlab-sast] [--output <path>]
$ apex workspaces
$ apex workspace
$ apex workspace use <name|prefix|id>
$ apex cvss get
$ apex cvss set --file cvss.json
$ apex cancel-scan [scan-id]
$ apex status [--scan <scan-id>]
$ apex doctor
$ apex login
$ apex redeem <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 gitlab
$ apex connect forgejo

Common flags

Sign in and bind the existing workspace before editing its CVSS 3.1 scoring rubric. These scripted commands require live workspace membership and return JSON. Guest sessions cannot configure CVSS.

$ 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. Keep exactly enabled andpolicy at the top level. Give the policy a name, keepversion at 3.1, and supply guidance for every allowed value in all eight base metrics: AV, AC, PR, UI, S, C, I, A. Omit values you want to disallow; each metric needs at least one value.

$ apex cvss set --file cvss.json
$ apex cvss get

Set enabled to false to disable CVSS scoring while retaining the rubric. The change applies to future audit synthesis and does not rescore existing findings. If Audit Setup or another workspace update is active, retry after it finishes. These commands do not start scans or initiate login; CVSS administration is available through the scripted CLI, with no MCP or shell command.

$ apex scan
$ apex scan ./contracts --mode standard
$ apex scan ./contracts/UniswapV2ERC20.sol --mode standard
$ apex scan https://github.com/Uniswap/v2-core --mode standard
$ 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.md

1. 1
   Let Apex resolve the workspace

   Run apex scan from the repository root. Apex uses the current folder as the default workspace name unless you pass --workspace-name.
2. 2
   Keep source planning explicit when needed

   By default, Apex scans the current directory. Pass files, directories, or HTTPS GitHub/GitLab URLs as positional targets or with --repo. Company-enabled Forgejo repositories resolve through saved connections. A file target scans only that file; remote URLs use the default branch.
3. 3
   Use the current scan-mode names

   Use standard for normal scans, audit for audit scans, lite for beta-enabled Lite scans, and pr with --pr for GitHub or connected Forgejo pull request scans. The old ultra mode is still accepted only as a legacy alias for audit.

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-25

Close and reopen findings

Use apex-finding-status to close a resolved issue with status: "fixed" or reopen it with status: "open". This records your remediation decision and an audit entry while preserving the scanner verdict, severity, and validity feedback.

apex findings status KERN2-25 fixed --note "Resolved in PR #123" --json
$ apex findings status KERN2-25 open --note "Regression reproduced" --json
/findings status KERN2-25 fixed "Resolved in PR #123"

Local MCP takes findingRef, status, optional cwd/scanId, and note, using your existing device login. A finding UUID works without binding a checkout.

Other statuses are acknowledged, in_review, pending_merge, false_positive, wont_fix, and skipped. Reopening retains the reviewed state as accepted. Invalid or duplicate findings require a validity or duplicate-classification review before they can enter the open queue.

Include the finding's updatedAt as expectedUpdatedAt(CLI: --expected-updated-at) to prevent overwriting a newer edit. A conflict returns FINDING_STATUS_CONFLICT; reload and review the latest state before retrying. The response includes the saved reviewState, updatedAt, and changed. Workspace finding lists include remediationStatus so open and acknowledged remain distinct on subsequent reads.

Linear sync currently runs from Linear to Apex: started tickets become acknowledged and completed tickets become fixed. Changing a finding here does not update its Linear or Jira ticket. Use the direct status operation when managing remediation from an MCP client or API integration.

Send findings to Linear or Jira

Create a ticket from a finding with the same title, severity, details, and Apex link as the frontend. Connect the integration and configure its destination in Apex first. Sending uses saved Linear workspace project and labels (or the company default), or the workspace Jira site, project, and issue type.

$ apex findings send KERN2-25 linear --json
$ apex findings send KERN2-25 jira --json

Local MCP exposes apex-finding-send with findingRef, provider, and optional cwd/scanId. CLI users can pass --scan or a finding UUID. These flows use device login. Hosted MCP takes findingId (UUID) and requires explicit findings:write.

Already sent or linked findings return their existing ticket with created: false; an active export returns a conflict. After an ambiguous timeout or provider failure, inspect the linked tickets and the provider before retrying. Sending is never automatically retried.

Link existing Linear or Jira tickets

Connect the integration in company settings, then link an existing ticket to a finding. Apex verifies that the integration can access the ticket and displays the link on the finding in the frontend.

$ apex findings link-ticket KERN2-25 linear SEC-123 --json
$ apex findings link-ticket KERN2-25 jira https://acme.atlassian.net/browse/SEC-123 --json
$ apex findings tickets KERN2-25 --json

Use a finding UUID directly, or a finding identifier with the bound workspace and optional --scan. Ticket keys and HTTPS issue URLs are accepted; Linear also accepts an issue UUID. For ambiguous Jira sites, use the full issue URL or configure the workspace destination. One ticket per provider can be linked. Repeating the same link is safe; a different existing link or an in-progress export returns a conflict. Linking does not create or modify the provider ticket.

Local MCP uses apex-finding-link-ticket with findingRef, provider, and issueRef; apex-finding-tickets lists links. Hosted MCP uses findingId (UUID), with findings:write for linking and findings:read for listing. Existing keys and default scopes remain unchanged; request the write scope explicitly when creating a key.

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.

$ 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-mcp

Hosted HTTPS MCP

Production agents can connect to https://ai.cantina.xyz/mcp over Streamable HTTP and send Authorization: Bearer <service-key>. The hosted tools do not require a local filesystem or device-login session.

ChatGPT and supported Codex loopback clients can use the same endpoint's OAuth discovery flow. Other clients can use an organization service key. Sign in with Cantina, select an organization you manage or your owned personal workspace, and approve the requested scopes. The client manages the OAuth tokens; those tokens authenticate only hosted MCP, not the REST API or local CLI.

Apex Black is available only through the hosted tool when the connected deployment advertises it. The organization must have beta access, or the researcher who issued the personal-workspace credential has individual beta access. Researchers do not need to join a company. Check apex-black-prepare first, then supply 1–16 exact HTTPS origins, a stable idempotencyKey, and authorizationAccepted: true only when the user has already authorized every target and accepted the 200 Standard credit cost. Use the returned scanId with apex-status and apex-findings. A stored start failure is replayed by identical retries; retain its durable IDs and contact support before another request. Local CLI and stdio MCP have no Black scan mode or start tool.

$ export APEX_SERVICE_KEY='<service-key>'
$ codex mcp add apex --url https://ai.cantina.xyz/mcp --bearer-token-env-var APEX_SERVICE_KEY

See the service API guide for service-key scopes, Claude Code configuration, retry rules, and the exact hosted/local boundary.

Apex CLI 0.1.40 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 scan

Telemetry 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.

• 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.
• When connecting GitHub, use the browser signed in to the same account used for CLI login and complete GitHub authorization. After an organization owner approves an installation request, reopen apex connect github to finish linking it to your company.
• If you have a Cantina Standard-scan code, use Apex CLI 0.1.34 or later and run apex redeem <code> in a terminal. New codes share one redemption limit between a 200-credit trial and 100% off the 200-credit checkout package. 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>.
• For a local checkout, use --source-mode local if remote materialization fails. For an explicit remote URL, connect its provider or clone it locally first; the CLI never substitutes the current directory.
• Unauthenticated --json, --non-interactive, and non-TTY commands fail fast. Run apex login explicitly before automation. Transient refresh failures preserve credentials.
• Company access requires a current, activated Cantina membership. Removing or disabling a member blocks existing CLI access, token refresh, and guest claims into that company; pending invitations do not grant access. If membership changes, run apex login again. If membership verification is temporarily unavailable, retry after Cantina recovers.
• Audit scans require connected GitHub, GitLab, or company-enabled Forgejo sources. Lite scans support GitHub or GitLab. Local snapshot fallback is for standard scans.
• If AUDIT_SETUP_REQUIRED appears, use the error's selected-workspace setup command only when you intend to scan its saved repositories. Setup uses saved workspace sources and does not preserve local target selections. Explicit Standard source scans require current CLI and backend versions.
• Eligible beta accounts receive Setup commands in CLI help. Draft operations require the ID returned by preparation. Setup supports Standard and Audit modes; Lite and PR do not use --setup.
• Lite scans also require the Lite Scan beta feature and an available Lite scan entitlement.
• PR scans require a provider-backed GitHub repository or a company-enabled Forgejo connection. Use --mode pr --pr <number-or-url>; Forgejo PR URLs use /pulls/<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.

Forgejo support is available when an administrator enables Forgejo in the company’s Beta settings. Connect a reachable HTTPS instance using a dedicated bot and repository-scoped tokens. The read token needs repository read access; an optional write token enables PR statuses, comments and webhook installation. A repository administrator can install the webhook manually if the bot cannot manage hooks.

$ apex connect forgejo --company acme
$ apex scan https://git.example.com/team/service
$ apex scan --mode pr --pr https://git.example.com/team/service/pulls/42
$ apex findings fix-review ACME-25 --fix-pr-url https://git.example.com/team/service/pulls/42

For an existing Apex workspace, bind its name or prefix with apex workspace use ACME --company acme before running apex doctor --json. In plannedSources, the repository should use provider: forgejo and materializationAuth: connection. Custom HTTPS hostnames resolve through the company’s saved connections.

• When creating a workspace, select Forgejo alongside GitHub and GitLab. Reuse a connection you own (administrators can reuse any company connection), or connect an instance in the dialog, select repositories and branches, PRs or commits, then continue to context and Standard or Audit scan setup.
• The Forgejo repositories and scans page connects selected repositories to a workspace and starts repository or PR scans. CLI and MCP use the same company connection.
• Enable automatic PR scans when connecting, or comment /apex scan as a repository collaborator with write access. Signed fix handoff markers attribute a PR to its original finding and start Fix Review.
• PR and Fix Review results publish against the reviewed head commit. Draft and fork PRs are excluded. A push refreshes a linked Fix Review; merged and closed PRs update the finding review state.
• Forgejo uses Standard, Audit, PR and Fix Review scans. Lite, guest and demo flows retain their existing providers. Tokens stay on the server and are not returned to CLI or MCP.
• The hosted integration requires an internet-reachable HTTPS endpoint. Private-only instances require an additional connector before enabling this integration. Every repository is checked against its saved instance and repository ID.