Apex CLI

Standalone CLI client for Apex.

Installing And Updating

For a public install, use a global package manager install:

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

Then run:

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:

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:

apex update

You can also update directly with your package manager:

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:

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:

pnpm install

2. Run the CLI:

pnpm apex

By default, the CLI targets https://ai.cantina.xyz/.

Use APEX_BASE_URL only when testing against a non-production Apex host:

APEX_BASE_URL=https://preview.cantina.xyz pnpm apex

Interactive Shell

Bare apex opens the interactive shell:

$ 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|audit]
• /scan pr <pr-number>
• /scans
• /findings [scan-id]
• /findings comment <finding-id|finding-identifier> <comment>
• /findings feedback <finding-id|finding-identifier> valid [comment]
• /findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]
• /findings fix-review <finding-id|finding-identifier>
• /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 scan --mode pr --pr <number> [--pr <number>] [--pr-path <path>]
• apex scans
• apex findings [--scan <scan-id>]
• 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 <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

apex credits shows standard scan credits plus audit scan entitlements when the server returns them.

Finding Review Feedback

Finding review collaboration now has explicit write commands:

• apex findings comment <finding-id|finding-identifier> --content "Needs auth check"
• apex findings feedback <finding-id|finding-identifier> valid --comment "Reproduced on latest build"
• apex findings feedback <finding-id|finding-identifier> invalid --dismissal-reason false-positive --comment "This path is unreachable"
• apex findings feedback <finding-id|finding-identifier> valid --label fixed --fix-pr-url https://github.com/acme/app/pull/123 --comment "Fixed in PR #123"
• apex findings fix-review <finding-id|finding-identifier>
• /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>

Identifiers such as KERN2-25 are resolved against the selected or latest scan for the current workspace binding. Pass --scan <scan-id> when you need a specific scan, or pass the finding UUID directly to skip workspace-based resolution.

Finding comments, valid/invalid feedback, and fix review scan starts currently require a Cantina web session token in CANTINA_AUTH_TOKEN. Set it to the value of your logged-in auth_token cookie before using the write commands or the corresponding MCP tools.

Invalid feedback requires a dismissal reason. Valid feedback can include --suggested-severity extreme|critical|high|medium|low|informational.

Fix review scans use a two-step callback flow for agents that create a PR outside Apex:

1. Save fixed feedback on the finding with --label fixed and one or more --fix-pr-url values.
2. Start the scan with apex findings fix-review <finding-id|finding-identifier>.

The matching MCP flow is apex-finding-feedback with status: "valid", labels: ["fixed"], and fixPrUrls, followed by apex-finding-fix-review.

This is intentionally documented as a separate auth requirement because the current Apex read APIs and finding review write APIs do not accept the same credentials:

• read operations such as apex findings, apex export findings, and apex-findings use the Apex CLI device-login bearer token
• finding comments and feedback currently go through the Cantina web-app routes and require CANTINA_AUTH_TOKEN

Local Source Scans

apex scan now works against any local source root you point it at. By default, that source root is the current working directory:

• 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 instead of the current directory
• --source-mode auto|remote|local to control remote-first fallback behavior
• --mode standard|audit|pr to choose the scan mode
• --pr <number> to select one or more GitHub pull requests for --mode pr
• --pr <number:path,path> or --pr-path <path> to limit a PR scan to changed paths

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.

Audit scans use audit as the scan mode and 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.

PR scans require exactly one provider-backed GitHub repository. If the current directory resolves to multiple sources, pass --repo <path> to select the one that contains the pull request.

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:

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:

codex mcp add apex -- apex-mcp

For Claude Code:

claude mcp add --scope user apex -- apex-mcp

For any other MCP client, configure it to launch:

{
  "mcpServers": {
    "apex": {
      "command": "apex-mcp"
    }
  }
}

From a local checkout during development, prefer the repo-local binary so the MCP stream stays clean:

{
  "mcpServers": {
    "apex": {
      "command": "/path/to/apex-cli/bin/apex-mcp"
    }
  }
}

If you need to launch through pnpm, use --silent:

{
  "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
• PR scan start by calling apex-scan with mode: "pr" and pullRequests
• finding comments and valid/invalid feedback with apex-finding-comment and apex-finding-feedback
• Fix PR callback and fix review scans with apex-finding-feedback plus apex-finding-fix-review

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.

Plugin And Marketplace Packaging

The npm package also includes marketplace-ready plugin artifacts:

• .codex-plugin/plugin.json and .mcp.codex.json for Codex plugin installs
• .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/[email protected] 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.

For local Claude validation:

claude plugin validate .
claude plugin marketplace add ./ --scope local
claude plugin install apex-cli@cantina-tools --scope local

For local Codex validation, add this repo as a local marketplace, then install apex-cli from the Cantina Tools marketplace in the Codex plugin directory:

codex plugin marketplace add ./

See MARKETPLACE.md for the official Claude, Anthropic Connectors Directory, and OpenAI/Codex submission checklist. The local stdio MCP server is plugin-ready, but remote marketplace submissions still require the external review steps documented there.

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