@cantinasecurity/apex-cli 0.1.9 → 0.1.11

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

@@ -7,6 +7,8 @@ description: Use when a user wants to run Apex scans, inspect findings, export r
 
 This skill is bundled with Apex CLI and can be installed into the current repository with `apex setup claude`.
 
+`apex setup claude` configures the MCP server with client attribution so Apex can distinguish Claude MCP usage from direct CLI usage. Users can inspect or disable anonymous local usage telemetry with `apex telemetry status` and `apex telemetry disable`.
+
 ## Instructions
 
 Use Apex through the MCP server when the `apex-*` tools are available.
@@ -39,6 +41,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - When checking a scan that is not the workspace binding's latest scan, pass `scanId` to `apex-status`; use `apex scans` or `apex-scans` first if you need to discover scan IDs.
 - Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status` and complete `apex-auth-start` / `apex-auth-wait` instead of asking for browser cookies or auth tokens.
+- Anonymous telemetry records only sanitized command/tool metadata such as command names, enum modes, counts, durations, success/failure categories, CLI version, and client integration. It must not include raw repository paths, scan IDs, finding IDs, comments, file paths, PR URLs, or tokens.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
 - Fix PR callback feedback requires valid feedback with `labels: ["fixed"]` and `fixPrUrls`; start the fix review scan with `apex-finding-fix-review` after saving that feedback.
 - Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit `scanId` when needed, or use the finding UUID directly.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.9"
+    "version": "0.1.11"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.9"
+        "version": "0.1.11"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.9",
+      "version": "0.1.11",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,9 +5,13 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.9",
+        "@cantinasecurity/apex-cli@0.1.11",
         "apex-mcp"
-      ]
+      ],
+      "env": {
+        "APEX_MCP_CLIENT": "claude",
+        "APEX_CLIENT_INTEGRATION": "claude"
+      }
     }
   }
 }

package/.mcp.codex.json

@@ -4,8 +4,12 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.9",
+      "@cantinasecurity/apex-cli@0.1.11",
       "apex-mcp"
-    ]
+    ],
+    "env": {
+      "APEX_MCP_CLIENT": "codex",
+      "APEX_CLIENT_INTEGRATION": "codex"
+    }
   }
 }

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.9 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.11 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -19,15 +19,17 @@ 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
+- registers Apex as an MCP server in any installed Codex CLI, 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
+- installs the GitHub Copilot CLI skill into `$COPILOT_HOME/skills/apex-cli` or `~/.copilot/skills/apex-cli`
 
 If you only want one client, run:
 
 ```bash
 apex setup codex
 apex setup claude
+apex setup copilot
 ```
 
 If one client is not installed yet, `apex setup` skips it automatically. If you target a client explicitly, its CLI must already be installed.
@@ -146,7 +148,8 @@ Supported shell commands:
 - `apex doctor`
 - `apex login`
 - `apex logout`
-- `apex setup [all|codex|claude]`
+- `apex setup [all|codex|claude|copilot]`
+- `apex telemetry [status|enable|disable]`
 - `apex update`
 - `apex connect github`
 - `apex connect gitlab`
@@ -219,18 +222,30 @@ If Apex is installed globally, prefer:
 apex setup
 ```
 
-That registers Apex for installed Codex and Claude Code clients automatically.
+That registers Apex for installed Codex CLI, Claude Code, and GitHub Copilot CLI clients automatically. Codex and Claude registrations also set `APEX_MCP_CLIENT` and `APEX_CLIENT_INTEGRATION` so Apex can distinguish agent-driven MCP usage from direct CLI usage.
 
 If you want to wire clients manually instead, Apex ships a stable `apex-mcp` binary. For Codex:
 
 ```bash
-codex mcp add apex -- apex-mcp
+codex mcp add apex \
+  --env APEX_MCP_CLIENT=codex \
+  --env APEX_CLIENT_INTEGRATION=codex \
+  -- apex-mcp
 ```
 
 For Claude Code:
 
 ```bash
-claude mcp add --scope user apex -- apex-mcp
+claude mcp add --scope user \
+  -e APEX_MCP_CLIENT=claude \
+  -e APEX_CLIENT_INTEGRATION=claude \
+  apex -- apex-mcp
+```
+
+For GitHub Copilot CLI:
+
+```bash
+copilot mcp add apex --type stdio --tools "*" -- apex-mcp
 ```
 
 For any other MCP client, configure it to launch:
@@ -239,7 +254,11 @@ For any other MCP client, configure it to launch:
 {
   "mcpServers": {
     "apex": {
-      "command": "apex-mcp"
+      "command": "apex-mcp",
+      "env": {
+        "APEX_MCP_CLIENT": "custom-mcp-client",
+        "APEX_CLIENT_INTEGRATION": "custom-mcp-client"
+      }
     }
   }
 }
@@ -251,7 +270,11 @@ From a local checkout during development, prefer the repo-local binary so the MC
 {
   "mcpServers": {
     "apex": {
-      "command": "/path/to/apex-cli/bin/apex-mcp"
+      "command": "/path/to/apex-cli/bin/apex-mcp",
+      "env": {
+        "APEX_MCP_CLIENT": "local-dev",
+        "APEX_CLIENT_INTEGRATION": "local-dev"
+      }
     }
   }
 }
@@ -265,7 +288,11 @@ If you need to launch through `pnpm`, use `--silent`:
     "apex": {
       "command": "pnpm",
       "args": ["--silent", "mcp"],
-      "cwd": "/path/to/apex-cli"
+      "cwd": "/path/to/apex-cli",
+      "env": {
+        "APEX_MCP_CLIENT": "local-dev",
+        "APEX_CLIENT_INTEGRATION": "local-dev"
+      }
     }
   }
 }
@@ -285,10 +312,64 @@ The MCP server exposes Apex-specific tools for:
 
 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 Codex-style clients, the packaged skill can be installed with `apex setup codex`. For GitHub Copilot CLI, the same skill is installed into `~/.copilot/skills/apex-cli` with `apex setup copilot`. 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.
 
+## Usage Telemetry
+
+Apex CLI emits first-party, privacy-preserving usage telemetry so Cantina can understand how people use the direct CLI, the interactive shell, and MCP tools in Codex, Claude, GitHub Copilot CLI, or other clients.
+
+Telemetry is enabled by default and can be disabled locally:
+
+```bash
+apex telemetry status
+apex telemetry disable
+apex telemetry enable
+```
+
+Environment opt-outs override local config:
+
+```bash
+APEX_TELEMETRY_DISABLED=1 apex scan
+# also honored: APEX_DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1
+```
+
+Telemetry records lifecycle events such as command/tool start and completion, duration, success/failure category, CLI version, Node/platform basics, anonymous install/session IDs, and sanitized command metadata. It also adds attribution headers to Apex API requests, including surface (`cli`, `interactive_shell`, or `mcp`), client integration, invocation ID, command/tool name, and CLI version.
+
+Telemetry does not send raw cwd paths, repository URLs, finding IDs, scan IDs, PR URLs, comments, file paths, tokens, or raw flag values. Sensitive inputs are reduced to booleans, counts, enum values, or length buckets.
+
+Telemetry event posts do not include bearer tokens. The telemetry endpoint is `POST /api/cli/v1/telemetry/events` with a batch payload:
+
+```json
+{
+  "events": [
+    {
+      "schemaVersion": 1,
+      "event": "apex.invocation.completed",
+      "cliVersion": "0.1.11",
+      "invocation": {
+        "surface": "mcp",
+        "command": "apex-scan",
+        "mcpTool": "apex-scan",
+        "metadata": {
+          "mode": "pr",
+          "pullRequestCount": 1,
+          "cwdProvided": true
+        }
+      },
+      "client": {
+        "integration": "codex"
+      },
+      "outcome": {
+        "success": true,
+        "durationMs": 1234
+      }
+    }
+  ]
+}
+```
+
 ## Plugin And Marketplace Packaging
 
 The npm package also includes marketplace-ready plugin artifacts:
@@ -297,7 +378,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.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/apex-cli@0.1.9 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.11 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.
 

package/dist/apex.js

@@ -1,12 +1,12 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { parseArgs } from "./args.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandTelemetry, 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 { createCliTelemetryInvocation, emitInvocationCompleted, emitInvocationStarted, withTelemetryContext, } from "./telemetry.js";
 import { maybePromptForUpdate } from "./update.js";
-async function main() {
-    const parsed = parseArgs(process.argv.slice(2));
+async function dispatch(parsed) {
     if (parsed.flags.help === true || parsed.command === "help") {
         process.stdout.write(CLI_HELP_TEXT);
         return;
@@ -45,6 +45,9 @@ async function main() {
         case "setup":
             await commandSetup(cwd, parsed.flags, parsed.subcommand);
             return;
+        case "telemetry":
+            await commandTelemetry(parsed.flags, parsed.subcommand);
+            return;
         case "doctor":
             await commandDoctor(client, cwd, parsed.flags);
             return;
@@ -117,6 +120,21 @@ async function main() {
             throw new Error(`Unknown command: ${parsed.command}`);
     }
 }
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const invocation = createCliTelemetryInvocation(parsed);
+    emitInvocationStarted(invocation);
+    await withTelemetryContext(invocation, async () => {
+        try {
+            await dispatch(parsed);
+            emitInvocationCompleted(invocation);
+        }
+        catch (error) {
+            emitInvocationCompleted(invocation, error);
+            throw error;
+        }
+    });
+}
 function getFlagValue(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }

package/dist/api-client.js

@@ -1,4 +1,5 @@
 import { clearCredentials, loadConfig, loadCredentials, saveCredentials } from "./config.js";
+import { getTelemetryRequestHeaders } from "./telemetry.js";
 export class ApiError extends Error {
     status;
     body;
@@ -84,7 +85,11 @@ export class ApexApiClient {
     async request(path, options = {}) {
         const baseUrl = await this.getBaseUrl();
         const headers = new Headers(options.headers ?? {});
+        const telemetryHeaders = await getTelemetryRequestHeaders();
         let credentials = options.auth === false ? null : await this.refreshIfNeeded().catch(() => null);
+        for (const [key, value] of Object.entries(telemetryHeaders)) {
+            headers.set(key, value);
+        }
         if (options.json !== undefined) {
             headers.set("Content-Type", "application/json");
         }

package/dist/commands.js

@@ -12,6 +12,7 @@ import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, remediateMi
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
 import { commandSetup as runCliSetup } from "./setup.js";
+import { getTelemetryStatus, setTelemetryEnabled, } from "./telemetry.js";
 import { commandUpdate as runCliUpdate } from "./update.js";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -496,6 +497,41 @@ export async function commandUpdate(flags) {
 export async function commandSetup(cwd, flags, target) {
     return runCliSetup(cwd, flags, target);
 }
+function formatTelemetryDisabledBy(disabledBy) {
+    if (!disabledBy)
+        return "not disabled";
+    if (disabledBy === "config")
+        return "local config";
+    return disabledBy.replace(/^env:/, "environment variable ");
+}
+export async function commandTelemetry(flags, target) {
+    let payload;
+    switch (target ?? "status") {
+        case "status":
+            payload = await getTelemetryStatus("cli");
+            break;
+        case "enable":
+            payload = await setTelemetryEnabled(true);
+            break;
+        case "disable":
+            payload = await setTelemetryEnabled(false);
+            break;
+        default:
+            throw new Error("Usage: apex telemetry [status|enable|disable]");
+    }
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Telemetry: ${payload.enabled ? "enabled" : "disabled"}`, flags);
+    logLine(`Disabled by: ${formatTelemetryDisabledBy(payload.disabledBy)}`, flags);
+    logLine(`Endpoint: ${payload.endpointPath}`, flags);
+    logLine(`Client integration: ${payload.client.integration}`, flags);
+    if (payload.installId) {
+        logLine(`Install ID: ${payload.installId}`, flags);
+    }
+    return payload;
+}
 export async function commandDoctor(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     try {

package/dist/config.js

@@ -32,12 +32,16 @@ export async function loadConfig() {
             version: 1,
             baseUrl: DEFAULT_BASE_URL,
             defaultCompanyId: null,
+            telemetryDisabled: config?.telemetryDisabled ?? null,
+            telemetryInstallId: config?.telemetryInstallId ?? null,
         };
     }
     return {
         version: 1,
         baseUrl: config.baseUrl,
         defaultCompanyId: config.defaultCompanyId ?? null,
+        telemetryDisabled: config.telemetryDisabled ?? null,
+        telemetryInstallId: config.telemetryInstallId ?? null,
     };
 }
 export async function saveConfig(config) {

package/dist/help.js

@@ -21,7 +21,10 @@ export const CLI_HELP_TEXT = `Usage:
   apex login                        Sign in to Apex
   apex logout                       Sign out locally
   apex mcp                          Start the Apex MCP server over stdio
-  apex setup [all|codex|claude]     Configure Apex for Codex and Claude Code
+  apex setup [all|codex|claude|copilot]
+                                    Configure Apex for Codex, Claude Code, and GitHub Copilot CLI
+  apex telemetry [status|enable|disable]
+                                    Show or change local anonymous usage telemetry settings
   apex update                       Update the local Apex CLI install
   apex connect github               Open the GitHub connection flow
   apex connect gitlab               Open the GitLab connection flow
@@ -65,6 +68,7 @@ Tips:
   Invalid finding feedback requires --dismissal-reason.
   Fix review scans require valid feedback with --label fixed and at least one --fix-pr-url, then apex findings fix-review.
   Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
+  Anonymous usage telemetry helps Apex understand CLI, MCP, Codex, Claude, and Copilot usage. Disable it with apex telemetry disable or APEX_TELEMETRY_DISABLED=1.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
 `;
@@ -89,6 +93,8 @@ Commands:
   /cancel-scan [scan-id]  Cancel a running or most recent scan
   /status [scan-id]       Show progress for the most recent or selected scan
   /doctor                 Validate auth, repos, connections, and workspace binding
+  /telemetry [status|enable|disable]
+                          Show or change local anonymous usage telemetry settings
   /update                 Update the local Apex CLI install and exit the shell
   /logout                 Sign out locally and exit the shell
   /repos                  List detected repositories
@@ -111,5 +117,6 @@ Tips:
   Invalid finding feedback requires a dismissal reason.
   Fix review scans require fixed valid feedback with a Fix PR URL. Use scripted CLI or MCP for attaching Fix PR URLs.
   Use scripted CLI flags for advanced feedback options such as suggested severity or dismissal reason.
+  Anonymous usage telemetry can be disabled with /telemetry disable or APEX_TELEMETRY_DISABLED=1.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;