Installation
All 15 Zephex CLI Commands
Every command, every flag, with copy-paste examples. Run any of these from any terminal — Mac, Linux, Windows.
Quick Reference
The Zephex CLI is one binary with 15 commands grouped into four areas: setup, management, inspection, and updates.
SETUP Connect, switch, fix npx zephex setup Interactive wizard npx zephex setup --cursor Skip the picker npx zephex setup --project Install for current project only npx zephex reconnect Re-run setup (fresh API key) npx zephex reset Clean install (config + skill + rule) MANAGEMENT Once you're connected npx zephex disconnect Remove from one editor npx zephex disconnect --all Remove from every editor npx zephex tools List the 10 MCP tools npx zephex tools --enable a,b Restrict tools (min 2, max 9) npx zephex tools --reset Re-enable all tools npx zephex skills Install skill + rule files npx zephex skills --upgrade Refresh skill files to latest npx zephex skills --remove Remove skill + rule files INSPECTION What's installed, what's broken npx zephex list Show every editor's install status npx zephex status Live check the proxy with your key npx zephex keys Show installed keys (masked) npx zephex usage Per-tool call counts npx zephex doctor 6 diagnostic checks npx zephex info Version, install path, update check META npx zephex update How to update Zephex itself npx zephex help Full help with examples npx zephex --version Same as infosetup — Connect an editor
The wizard does everything: opens the browser, signs you in, creates an API key, writes the config file, and optionally installs the skill + rule files.
Three steps in one flow
Step 1 → Pick editor (20 options, hotkeys 1-9 / 0 / a-j)Step 2 → Pick scope (only shown if you're in a real project) ┌── All projects (global) — works everywhere └── This project only — config stays in this folderStep 3 → Pick mode ┌── MCP + Skill + Rule (default) — agent uses tools proactively └── MCP only — tools available, agent decides Then → Browser opens → Sign in → API key created → Config written → DoneCommon variations
# Full wizardnpx zephex setup # Skip the picker — directly connect Cursornpx zephex setup --cursor # Skip both picker and scope prompt — Cursor, this project onlynpx zephex setup --cursor --project # Skip everything — Cursor, this project, with skill + rulenpx zephex setup --cursor --project --with-skill # Connect multiple editors at oncenpx zephex setup --cursornpx zephex setup --claudenpx zephex setup --vscode # Use a key you already have (skip OAuth)ZEPHEX_API_KEY=mcp_prod_... npx zephex setup --cursordisconnect — Remove from an editor
Removes the Zephex entry from an editor's MCP config file and revokes the API key on the server.
# Interactive pickernpx zephex disconnect # Specific editornpx zephex disconnect --cursornpx zephex disconnect --claudenpx zephex disconnect --vscode # Every editor at once (also revokes every key)npx zephex disconnect --all # Disconnect AND remove the skill/rule filesnpx zephex disconnect --cursor --with-skillreset — Full cleanup
Like disconnect but also removes the skill and rule files. Use when you want a totally fresh slate.
# Reset one editornpx zephex reset --cursor # Nuclear option — every editor + every skill/rule filenpx zephex reset --allstatus — Live connection check
For each editor that has Zephex installed, hits the proxy with the actual API key and reports PASS/FAIL.
$ npx zephex status EDITOR CONFIG KEY STATUS TOOLS DETAIL------------------ ---------------------------------- --------------- ------ ----- ------Cursor (global) ~/.cursor/mcp.json mcp_prod_pri... PASS 10 okClaude Code ~/.claude.json mcp_prod_pri... PASS 10 okVS Code (project) ./.vscode/mcp.json mcp_prod_ver... PASS 10 okCodex (global) ~/.codex/config.toml mcp_prod_pri... PASS 10 okIf STATUS shows FAIL, run npx zephex doctor for diagnostics.
list — Offline install map
Shows every editor and whether it has Zephex installed. Doesn't hit the network.
$ npx zephex list Zephex install status cwd: /Users/you EDITOR STATUS CONFIG ───────────────────────────────────────────── Cursor ● global ~/.cursor/mcp.json Claude Code ● connected ~/.claude.json (+ project) VS Code ● project ./.vscode/mcp.json Codex ● global ~/.codex/config.toml OpenCode ○ not installed — Windsurf ○ not installed — Zed ○ not installed — ... 4 of 20 editors connected. Run npx zephex status to verify the API key works.The connected status means both global AND project configs exist. global means only home directory; project means only the current folder.
tools — Filter which tools your agent sees
By default all 10 MCP tools are exposed to your AI agent. You can restrict that to any subset of 2-9 tools.
List all tools
$ npx zephex tools ● find_code code BM25 code search ● read_code code AST-based reader ● scope_task code Plain English → focus files ● get_project_context code Project snapshot ● explain_architecture code Mermaid + dependency analysis ● keep_thinking reasoning Persistent reasoning state ● audit_headers web HTTP / TLS audit ● check_package web Package safety check ● audit_package web Deep upgrade analysis ● Zephex_dev_info knowledge Expert dev knowledge baseRestrict to specific tools
# Just 2 tools (the minimum)npx zephex tools --enable find_code,read_code # Just 3 toolsnpx zephex tools --enable find_code,read_code,scope_task # All 5 code toolsnpx zephex tools --enable find_code,read_code,scope_task,get_project_context,explain_architecture # 4 tools — code reading + reasoningnpx zephex tools --enable find_code,read_code,scope_task,keep_thinking # Re-enable all 10npx zephex tools --resetThe filter is saved to ~/.zephex/config.json. Restart your editor for changes to take effect.
For the full filtering guide with use cases see Tool Filtering.
keys — Show installed API keys
Lists every Zephex API key you have installed across all editors. Keys are masked for safety — only the first 12 and last 4 chars are shown.
$ npx zephex keys Zephex API keys Keys installed in your editor configs (masked for safety) 1. mcp_prod_pri…4f32 (pro) Editors: Cursor (global), Claude Code (global), VS Code (project) Usage: 142/3000 this month (4%) 2. mcp_prod_ver…9a01 (free) Editors: Codex (global) Usage: 47/300 this month (15%) 2 unique keys across 4 editor configs.If multiple editors share one key (because you signed in once and connected several editors), they'll be grouped together. Each unique OAuth login creates one key.
usage — Per-tool call counts
Shows how many times each tool has been called this month, with a bar chart.
$ npx zephex usage Zephex tool usage How often each tool has been called by your installed keys mcp_prod_pri…4f32 (pro) Used by: Cursor (global), Claude Code (global) Today 17 calls This month 423 / 3000 ████░░░░░░░░░░░░░░░░ 14% By tool (this month): find_code 142 ███████████████ read_code 89 █████████░░░░░░ scope_task 67 ███████░░░░░░░░ keep_thinking 51 █████░░░░░░░░░░ explain_architecture 28 ███░░░░░░░░░░░░ audit_headers 16 ██░░░░░░░░░░░░░ check_package 15 ██░░░░░░░░░░░░░ audit_package 9 █░░░░░░░░░░░░░░ get_project_context 4 ░░░░░░░░░░░░░░░ Zephex_dev_info 2 ░░░░░░░░░░░░░░░If your editor was just connected, give it a few minutes — first calls take time to register. For live numbers see the dashboard.
doctor — Diagnose problems
Runs 6 checks to find common issues.
$ npx zephex doctor zephex doctor Diagnostic checks for Zephex setup ✓ Node.js version Node.js 22.10.0 ✓ Platform darwin arm64 (24.5.0) ✓ Proxy environment No proxy configured ✓ Network access Reached https://zephex.dev/api/health ✓ MCP endpoint https://zephex.dev/mcp responding (401 expected without key) ✓ Installed editors Found Zephex in 4 editor config(s) All checks passed. You're good to go.If any check fails, the doctor shows a fix:
✗ Network access Network error: getaddrinfo ENOTFOUND → Check your internet connection or HTTPS_PROXY env var ✗ Node.js version Node.js 18.0.0 is too old (requires 20+) → Upgrade Node.js: https://nodejs.org/info — Package info + update check
Shows the installed version, install path, platform, and checks the npm registry for newer versions.
$ npx zephex info Zephex CLI MCP tools for AI coding agents Installed 2.2.0 Website https://zephex.dev Dashboard https://zephex.dev/dashboard Support support@zephex.dev Runtime Install type global (npm install -g) Install path /usr/local/bin/zephex Node v22.10.0 Platform darwin arm64 Update ● Newer version available: 2.3.0 (you have 2.2.0) npm install -g zephex@latest npx zephex@latest setupskills — Manage skill + rule files
The skill file teaches your AI agent when to call Zephex tools. The rule file sets conventions. Without them, tools are available but the agent may not use them proactively.
# Install skill + rule for an editornpx zephex skills --cursor # Install for any editor (interactive picker)npx zephex skills # Refresh existing skill + rule files to the latest versionnpx zephex skills --upgrade # Remove all skill + rule filesnpx zephex skills --removeSkill files are written to editor-specific paths. For Cursor that's ~/.cursor/skills/zephex/SKILL.md and ~/.cursor/rules/zephex.md. For Claude Code that's ~/.claude/skills/zephex/SKILL.md.
Flag reference
Editor flags (skip the picker)
--cursor Cursor IDE--claude Claude Code (CLI)--vscode VS Code (with Copilot/Cline)--codex Codex (OpenAI)--opencode OpenCode CLI--windsurf Windsurf IDE--zed Zed editor--warp Warp terminal agent--gemini Gemini CLI--kiro Kiro (AWS)--cline Cline (VS Code extension)--jetbrains JetBrains IDEs--kilo Kilo Code (Roo successor)--amp Amp (Sourcegraph)--continue Continue (VS Code + JetBrains plugin)--copilot GitHub Copilot CLI--droid Factory Droid--claude-desktop Claude Desktop app--antigravity Google Antigravity IDE--trae TRAE (ByteDance)Behavior flags
--all Apply to all editors (disconnect/reset)--with-skill Also install skill + rule after setup--project Install config in current project only--global Install config globally (default outside projects)--upgrade Refresh skill + rule files to latest version--remove Remove skill + rule files--reset Re-enable all tools (with tools command)--enable a,b,c Restrict to specific tools (with tools command)--debug Verbose output for troubleshooting--help, -h Show help--version, -v Same as infoEnvironment variables
ZEPHEX_API_KEY Override the API key (skip OAuth flow)AUTH0_CLI_CLIENT_ID Override the Auth0 client (advanced)DEBUG Set to any value for verbose loggingNO_COLOR Set to disable colored outputHTTPS_PROXY HTTP proxy URL (for corporate networks)Exit codes
0 Success1 Configuration error or user cancellation2 Network or auth error3 Editor config write failedWhere to next
- Setup Walkthrough — visual end-to-end install diagram
- Tool Filtering — enable/disable specific tools with examples
- Quickstart — manual config (no Node.js)
- Supported Editors — config path for each of 20 editors
- Troubleshooting — common errors and fixes