zephex
CLIGet StartedPricingMCP ToolsCommunityGuidesDocs
←BackSign in
CLIGet StartedPricingMCP ToolsCommunityGuidesDocs
Get started freeSign in
DocsAPIToolsEditorsChangelogHelp

GET STARTED

WelcomeQuickstartSetup videoMCP Q&A (learn)BlogWhat is MCP?Who is Zephex for?Plans & PricingZ-GASAB benchmarkBenchmark chart (live)Changelog

CLI

Install & upgradeStartAll install methodsnpx zephex setupCLI without an agentFirst run (init)Login, logout, keysCommand referenceTerminal Mode 2Slash commandsCLI in Docker

INSTALLATION

Connect MCPAll editors (one command)Crush, Hermes, ChatGPT, KiloVS Code Marketplace extensionOAuth & HTTP setupSetup walkthroughHTTP vs stdioWeb Terminal (dashboard)Web Terminal toolsTerminal tools (complete)Test PulseTest Pulse commandsdeep (Project Dossier)Project MemorySupply PulseSupply Pulse commandsinstall (GitHub / npm files)install file commandsCommand CompassHTTP API

API & KEYS

API Key ManagementKey Naming & FormatAuthenticationKey Dashboard

CONFIGURATION

Universal RequirementsSupported EditorsHow It WorksArchitectureCLAUDE.md TemplateAGENTS.md Template

EDITORS28 guides

Supported EditorsVS CodeVS Code extension (Marketplace)Claude CodeCursorWindsurfJetBrains

PLATFORM

macOSWindowsLinux

TOOLS10 tools

Capabilities OverviewTools OverviewTool FilteringTool Workflowsget_project_contextread_codefind_codecheck_packageexplain_architectureZephex_dev_infocheck_testaudit_headerskeep_thinkingproject_memory

GUIDES

Best PracticesToken EfficiencyUse CasesZephex vs Local MCPZephex vs Context7Zephex vs GitHub MCPZephex vs SmitheryMCP EcosystemMarkdown Access

SUPPORT

Help CenterMCP troubleshootingTeam rolloutFAQConnection IssuesRate LimitsDowntime & ErrorsBillingTier GuidePro & Max guideUsage LimitsUsage Analytics

LEGAL

System StatusTerms (summary)Privacy (summary)Data UseSecurityAuthenticationSecurityData HandlingPrivacy PolicyTerms of Service

Quick Links

API Reference

Complete API documentation

Troubleshooting

Common issues and solutions

Community

Join our Discord community

Plugins

Editor and CLI integrations

Pricing

Free, Pro, and Max plans

Enter
Zephex_devzephex-devzephexzephexhello@zephex.dev
© 2026 Zephex. All systems operational.

CLI

npx zephex

The zephex npm package ships the setup wizard from mcp-proxy/src/commands/setup.ts. It signs you in, creates a CLI-scoped API key, writes your editor's MCP config, and verifies 10 tools — stdio bridge for most editors, hosted HTTP for Cursor and Claude Code.

Tip: Pin @latest on every setup and repair run. Stale npm cache is the #1 cause of missing tools after an upgrade. No Node? curl install.sh — install & upgrade the CLI.

UPGRADE THE CLI

Staying on an older CLI still works against the same hosted MCP. Upgrade when you want the slim installer, QR login, or newer usage screens.

shell
# Check installed vs npm latestzephex update --checkmcpcli update --check # Apply (CLI tarball into ~/.zephex — not npm install -g)zephex update --applymcpcli update --apply # Same effect — safe to re-run; keeps credentialscurl -fsSL https://zephex.dev/cli/install.sh | bashsource ~/.zephex/env.sh # Windows# irm https://zephex.dev/install.ps1 | iex # Refresh agent skill files after upgradezephex skills --upgrademcpcli skills --upgrade # Verifyzephex infomcpcli infozephex doctormcpcli doctor
ZEPHEX AND MCPCLI

Two names, one CLI

After install you get both commands. They are not two products. The installer links zephex and mcpcli to the same file. Use the product name if that is easier to remember. Use mcpcli if that is what you already typed last month. Nothing breaks if you mix them in one terminal.

shell
zephex overviewmcpcli overview    # same CLI, same result zephex loginmcpcli login    # same CLI, same result zephex doctormcpcli doctor    # same CLI, same result zephex update --checkmcpcli update --check    # same CLI, same result zephex usagemcpcli usage    # same CLI, same result

Extra aliases (same file again): zepx zphx mcpz zepcli zephx. You never have to memorize those. Slash commands inside the TUI (/overview) do not care which binary you launched.

USUAL SETUP FAILURES

These are the bugs people actually hit when installing or when an agent runs setup. Full install/upgrade page: Install & upgrade the CLI.

What you seeWhyFix
command not found: zephexcurl | bash cannot change PATH in the parent shell.source ~/.zephex/env.sh then open a new tab. which zephex should be ~/.zephex/bin/zephex.
npx zephex setup hangs or is huge (~260 MB)Published npm zephex still lists unused server deps. npx installs them.Use curl -fsSL https://zephex.dev/cli/install.sh | bash (~3 MB). Then zephex connect --cursor if you want the editor.
Node 18 / 20 — engines errornpx/npm/bun need Node 22.5+. Cloud Shell and many laptops are still 20.Do not upgrade Node just for us. Run the curl installer — it bundles Node 22 under ~/.zephex/node.
Agent says 0 tools / old tool namesStale npx cache or Grok/editor cached descriptors (23 files vs 10 live tools).npx -y zephex@latest doctor then repair. Grok: rm cached zephex tool JSON, grok mcp doctor zephex.
Login opened but CLI still “not signed in”QR/browser completed, poll did not write credentials, or you ran a different binary than the one that started login.zephex login or mcpcli login on the same machine. Check ~/.zephex/credentials.json exists (do not paste the key into chat).
Editor works, terminal does not (or the reverse)Editor MCP config and ~/.zephex/credentials.json are separate.Terminal: zephex login or mcpcli login. Editor: npx -y zephex@latest setup --cursor (or --claude). Same account.
HTTP MCP but find/read cannot see local filesHosted HTTPS cannot read the laptop disk. Cursor HTTP is fine for some tools; file tools need stdio.zephex repair — switches filesystem editors to stdio (npx -y zephex).
Windows: bash installer failedcmd.exe cannot run the Mac/Linux script.PowerShell: irm https://zephex.dev/install.ps1 | iex. WSL: use the curl line inside WSL, not on the host.
Mixed C:\Users\… and /home/you/.zephexWindows host and WSL are two installs.Install once in the environment that actually runs the shell or the editor.
doctor: CLI install is ~260 MBOld npm install -g left unused packages under ~/.zephex/npm-global.Re-run the curl installer. Credentials stay. voice-venv is unrelated (optional STT).
MCPCLI & COMMAND ALIASES

No Node? curl -fsSL https://zephex.dev/cli/install.sh | bash. npx/npm need Node.js 22.5+. Check with node -v. Still stuck? start from zero (MB + steps) · 6 install methods

CURL INSTALLER

curl installer — terminal CLI (Mode 2)

This one-liner is the Mode 2 terminal installer — the same zephex shell you type / in. It is not the editor MCP wizard on the homepage (npx -p zephex mcpcli setup). Same account and API key later; different first command.

shell
curl -fsSL https://zephex.dev/cli/install.sh | bash

Same script lives at both URLs (use either):

shell
curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash

What it does

  • Installs into ~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.
  • If your system Node is missing or older than 22.5, it downloads a private Node 22 runtime (~50 MB compressed, once) under ~/.zephex/node.
  • Downloads the zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).
  • Starts zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).

By operating system

macOS (Intel or Apple Silicon) — Terminal or iTerm. Needs curl (already there). After install, new Terminal windows pick up PATH from ~/.zshrc and ~/.zprofile. The current window still needs:

shell
source ~/.zephex/env.sh

Linux (x64 or arm64) — bash, zsh, or fish. Same curl line. PATH is appended to ~/.bashrc / ~/.profile (and fish config if needed). If you installed as one user and launch the desktop as another, the binary will not be on PATH — stay on the same account.

Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:

shell
irm https://zephex.dev/install.ps1 | iex

WSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.

Cloud shells, phones, other OS

  • Google Cloud Shell, GitHub Codespaces, Railway / Render shells — use the same curl line. Those boxes often ship Node 18 or 20. The installer notices and downloads a private Node 22 under ~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.
  • Android (Termux) — curl + bash work. Same installer. Hosted commands still need HTTPS out to zephex.dev.
  • iPhone / iPad — there is no native zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.
  • Windows ARM (Surface, Snapdragon) — PowerShell installer downloads the win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.

What the CLI talks to

  • Install download — Vercel serves install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.
  • Sign-in — browser or QR hits zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600).
  • Tool commands (/overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.
  • Sentry — Railway captures hosted tool / API errors (tagged with CLI version). The local zephex process does not send your repo to Sentry.

After install — first commands

shell
source ~/.zephex/env.shcd your-appzephex# type /overview   or   /help

Hosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.

Upgrade

The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:

shell
zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bash

Check what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.

This vs the homepage npx line

  • curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.
  • npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.
  • You can use both with one API key. Install the CLI first, then zephex connect --cursor when you want the editor.

Uninstall

shell
zephex uninstall           # PATH + credentialszephex uninstall --full    # delete entire ~/.zephex

If something looks stuck

  • command not found: zephex — source ~/.zephex/env.sh, then open a new tab.
  • Piped curl into bash: the installer cannot keep PATH in that parent shell. That is why it prints the source line.
  • Only run the script from zephex.dev— never a random gist.
  • Offline or corporate TLS intercept: the script needs HTTPS to zephex.dev (npm package) and, if Node is missing, nodejs.org.

More paths: all install methods · macOS · Linux · Windows · terminal CLI

mcpcli is the short install name for the Zephex MCP CLI (npm package zephex). Same binary, same API key, same 10 tools — you can type mcpcli instead of zephex after a one-time install. Official package name on npm remains zephex; command aliases ship inside that package (v2.4.6+).

Node.js required (or alternatives)

Includes best download path and how many MB each option uses — see download sizes.

mcpcli, npx zephex, and npm install -g zephex are Node.js programs. They need Node.js 22+ and npm on your PATH (or Node inside Docker). Zephex in the browser or in an editor over HTTPS does not replace that for terminal Mode 2.

Quick answer: Most people should install Node.js LTS, restart the terminal, then run npm install -g zephex && mcpcli setup. Pick another row in the table only if Node or global install is not possible on your machine.

BEST DOWNLOAD · HOW MANY MB?

Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org or skip Node entirely with the curl installer (~3 MB CLI tarball). npm install -g zephex currently unpacks ~260 MB of unused deps — prefer curl.

shell
# Best download — no Node required (~3 MB CLI; +~50 MB Node only if missing)curl -fsSL https://zephex.dev/cli/install.sh | bash # Already have Node 22.5+ and want editor MCP only:npx -y zephex@latest setup --cursor # Avoid until slim publish: npm install -g zephex / bare npx zephex# Those currently also install unused server libraries (~260 MB).
What you downloadApprox. downloadAfter install on disk
Node.js LTS (Windows .msi) — best base for most users~30 MB~100–250 MB
Node.js LTS (macOS .pkg)~84 MB~100–250 MB
zephex CLI only (npm install -g zephex)~3 MB~260 MB in npm cache
npx zephex setup (no global install)Same ~3 MB CLI on first runCached under ~/.npm; no separate “Zephex app” installer
Docker node:22-alpine (no local Node)~45–60 MB image pullDocker Desktop ~500+; image ~45–60 MB
Editor-only MCP (HTTPS + API key)0 MB CLI — config onlyNo Node required on laptop

Sizes vary slightly by Node version and OS. You are not downloading a large IDE or a multi-GB SDK — just Node (if needed) and a small npm package. Tools run against https://zephex.dev/mcp; your project code is not uploaded as a full repo by default.

Step 1 — check what you already have:

shell
node -vnpm -vwhich nodewhich npm
  • v18.x, v20.x, or v22.x → you are ready; skip to after Node is installed.
  • command not found → Node is missing; install below or use Docker / editor-only.
  • v16 or lower → upgrade Node; the CLI requires 22+.

Step 2 — pick the best path for you:

Your situationBest optionNotes
New user, can install softwareNode.js LTS + npm install -g zephex && mcpcli setupRecommended. Shortest commands: mcpcli, zepx, zephex.
Have Node, try before installing globallynpx zephex setup~5s first download; nothing permanent except credentials.
Use Bun instead of Node day-to-daybun install -g zephexStill a JS runtime; see Bun block below.
Use pnpmpnpm add -g zephexSame CLI; see pnpm block below.
No Node on host; Docker allowedDocker + npx in containerMount $HOME so credentials survive.
No Node, no Docker; only Cursor / ClaudeEditor MCP (HTTP)Mode 1 in editor — not the same as terminal mcpcli tools.
Corporate laptop, no installsManual JSON configPaste MCP config + API key; setup wizard optional on another machine.
Only need terminal tools occasionallynpx zephex … per commandNeeds Node each time; no global PATH entry.
INSTALL NODE.JS (MAC · WINDOWS · LINUX)

Download the LTS installer if you are unsure — it includes npm. After install, close and reopen your terminal (required on Windows so PATH updates).

shell
# macOS — recommended for most users# Option A: Homebrew (developers)brew install node # Option B: Official LTS installer (everyone)# Download from https://nodejs.org/en/download# Run the .pkg, then restart Terminal # Option C: Version manager (multiple Node versions)# fnm: https://github.com/Schniz/fnm# nvm: https://github.com/nvm-sh/nvm
shell
# Windows — recommended for most users# Option A: winget (Windows 10/11)winget install OpenJS.NodeJS.LTS # Option B: Official LTS installer# https://nodejs.org/en/download — check "Add to PATH" during install# Then open a NEW Command Prompt or PowerShell window # Verify (new window):node -vnpm -v
shell
# Linux — pick one# Option A: NodeSource (Debian/Ubuntu)curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs # Option B: Distro packages (may be older — need v18+)# sudo apt install nodejs npm   # only if version >= 18 # Option C: nvm (no sudo, per-user)# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash# nvm install --lts# nvm use --lts

Step 3 — after Node works, run Zephex setup:

shell
npm install -g zephex && mcpcli setup

Without global install (still needs Node + npm for npx):

shell
npx zephex setupnpx -p zephex mcpcli setup
BUN & PNPM (ALTERNATIVE RUNTIMES)

These still require a JavaScript runtime on the machine — not a substitute for “no Node at all.”

shell
bun install -g zephexmcpcli setup# or one-shot:bunx zephex setup
shell
pnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setup

No Node on this computer? Use Docker (Node runs inside the image) or editor-only MCP. Docker still requires Docker Desktop / Engine on the host.

shell
# Docker Desktop or Engine required on the hostdocker pull node:22-alpine # Setup (writes ~/.zephex + editor configs on YOUR machine)docker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup # Terminal tool in your repo (mount project folder)cd /path/to/your-appdocker run -it --rm \  -v "$HOME:/root" \  -v "$(pwd):/work" \  -w /work \  node:22-alpine \  npx -y zephex get-context

Optional alias so daily commands look like local mcpcli:

shell
# ~/.bashrc or ~/.zshrc — shorter daily commandsalias mcpcli='docker run -it --rm -v "$HOME:/root" -w "$(pwd):/work" -w /work node:22-alpine npx -y zephex' mcpcli setupmcpcli get-context

Full CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.

EDITOR ONLY — NO LOCAL NODE

If you only want MCP tools inside Cursor or Claude Code and never run commands in Terminal, you can connect over HTTPS without installing Node on your laptop. Terminal Mode 2 (mcpcli get-context, etc.) still needs Node or Docker somewhere.

shell
# No local Node needed for Cursor / Claude Code (hosted HTTP)# 1. Create a key: https://zephex.dev/dashboard/api-keys# 2. In Cursor: Settings → MCP → add server URL:#    https://zephex.dev/mcp#    Header: Authorization: Bearer YOUR_API_KEY# Or run setup on ANY machine that has Node once, copy the key into the editor. # Full wizard (needs Node somewhere once):# mcpcli setup --cursor
TROUBLESHOOTING
shell
# "command not found: node" or "command not found: npx"# → Node is not installed OR not on your PATH.# Fix: install LTS from nodejs.org, restart terminal, run node -v again. # "mcpcli: command not found" after npm install -g# → Global npm bin not on PATH, or install did not finish.# Fix: npm install -g zephex#       npm bin -g    # add this folder to PATH# Or skip global: npx zephex setup # EACCEs / permission denied on npm install -g (macOS/Linux)# Fix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global# Add to ~/.zshrc: export PATH="$HOME/.npm-global/bin:$PATH" # Old Node (v16 or below)# Fix: upgrade to Node 22.5+ — or use curl install.sh, which bundles Node.
FAQ
QuestionAnswer
Do I need Node.js to use Zephex at all?Not for the curl installer — it bundles Node 22 under ~/.zephex if needed. npx / npm / bun still need Node 22.5+ on PATH. Editor MCP over HTTPS can work with only an API key.
What is the best install for a new user?curl -fsSL https://zephex.dev/cli/install.sh | bash — then source ~/.zephex/env.sh. That works with or without Node. Use npx zephex setup --cursor only when you already have Node 22.5+ and want editor MCP.
I cannot install software on my work laptop.Use editor-only MCP (manual JSON or dashboard key) — see Install methods → Manual JSON. Or run setup once on a personal machine, copy the API key, paste into work editor config. Terminal CLI on the work machine may be blocked without Docker approval.
I have Node for another project — is that enough?Yes, if node -v shows v22.5 or higher. Below that, use the curl installer — it downloads a private Node 22 instead of failing.
Does the AI editor install Node for me?Sometimes. Cursor/VS Code may bundle npx for MCP stdio configs, but that does not put mcpcli on your system PATH for Mode 2 terminal use. For terminal tools, install Node yourself or use Docker.
Docker still needs something installed?Docker Desktop (or docker CLI) on the host — not Node. The container image includes Node and runs npx zephex for you.
How many MB will this download?curl installer: ~3 MB CLI tarball, plus ~50 MB Node only if you are below 22.5. npm install -g zephex / npx zephex currently also pull unused server libraries (~260 MB, ~2 minutes) until the slim package is published. Docker is a ~50 MB Node image plus that same npm package.
What is the best way to download if I have nothing installed?curl -fsSL https://zephex.dev/cli/install.sh | bash. If you cannot run curl|bash, use editor-only MCP (paste a key into Cursor) or the web terminal. Do not start with npm install -g until the slim package is on npm.

More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex

First time (any OS, Node already installed)

Pick one path — both work the first time you run setup:

Recommended — global install (shortest commands forever):

shell
npm install -g zephex && mcpcli setup

One-shot without global install (pick one):

shell
npx zephex setupnpx -p zephex mcpcli setup

Plain mcpcli setup only works after npm install -g zephex (or the combined line above). That is expected — there is no separate npm package named mcpcli on the public registry.

After install — daily commands

shell
mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctor

All of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.

Terminal-only vs editor MCP

MCP CLI (Mode 2) runs in your shell — no AI agent required. mcpcli setup when you pick Terminal / CLI only does not change Cursor/VS Code MCP config. Use mcpcli setup --cursor (or another flag) if you also want tools inside the editor.

logout vs disconnect: mcpcli logout removes only ~/.zephex terminal credentials — your editor can keep using MCP. mcpcli disconnect removes Zephex from an editor config and revokes the key — not the same as logout. You can use terminal tools and editor MCP together with one API key; you do not run two separate products.

Who can run it?

Anyone in the world can download and run mcpcli / zephex from npm (public CLI). Your hosted MCP tools at https://zephex.dev/mcp require your API key from setup — strangers cannot use your quota without a key. Keys stay in ~/.zephex (or editor config); nothing secret is baked into the npm package.

More

Connect MCP (editors) · Terminal tools · Full command list · Install & package names · Install methods (no Node / Docker / manual) · CLI in Docker

MAJOR SUBCOMMANDS

These six commands cover 90% of daily use — setup, diagnose, fix, inventory, and the two most-used terminal tools.

SETUP

setup · login, connect, sign-in

First connect — browser OAuth, writes editor MCP config + ~/.zephex/credentials.json

shell
npx -y zephex@latest setup --cursor

DOCTOR

doctor

Health check — Node version, network, MCP reachability, stdio pins, API key

shell
npx -y zephex@latest doctor

REPAIR

repair

Fix unpinned zephex, wrong OpenCode shape, legacy HTTP→stdio for filesystem editors

shell
npx -y zephex@latest repair

LIST

list · ls

Show every supported editor — installed configs highlighted

shell
npx -y zephex@latest list

GET-CONTEXT

get-context · context, stack, framework, .

Mode 2 — compact project brief from cwd (uploads local index)

shell
mcpcli get-context

FIND-CODE

find-code · find, search, grep, usages

Mode 2 — ripgrep-style repo search with AST-aware results

shell
mcpcli find-code "auth middleware"
SETUP WIZARD

The setup command auto-detects your editor (or use a flag below), runs OAuth in the browser unless you pass --api-key, writes the config file, and verifies the connection.

shell
# Terminal CLI (no Node required first) — ~3 MB tarball, not 260 MB of unused depscurl -fsSL https://zephex.dev/cli/install.sh | bash npm install -g zephex && mcpcli setup # Or one-shot (no global install) — needs Node 22.5+ alreadynpx -p zephex mcpcli setup # Official package name — always @latest until npm cache is freshnpx -y zephex@latest setup

Already have a key? Skip the browser step — paste a real key from the dashboard:

shell
npx -y zephex setup --cursor --api-key mcp_prod_your-key-herenpx -y zephex setup --opencode --api-key mcp_prod_your-key-herenpx -y zephex setup --vscode --api-key mcp_prod_your-key-here

Full cheat sheet: all editors + flags.

text
? Which editor? (interactive picker)  → Cursor          (writes hosted HTTP url)  → VS Code         (writes stdio: npx -y zephex)  → Claude Code     (claude mcp add --transport http, or HTTP JSON)  → OpenCode, Codex, Gemini, Windsurf, Kiro, Zed, … (stdio for local file tools) ✓ API key created via browser sign-in✓ Config written to the correct path for that editor✓ Connection verified — 10 tools available✓ Restart the editor (or reload window) to activate
How setup signs you in (one browser visit)
Terminalnpx zephex setupzephex.devPOST /api/cli/sessionBrowser/cli/authDashboardGitHub / GooglePollGET /pollsession_idopen URLOAuthkey readyEditor MCP filestdio or HTTP~/.zephexcredentials.jsonapi_keys rowuser_id + HMACwriteswritescreatesEmail shown once at setup — not stored in credentials.json (use dashboard for account)

Stdio editors never re-auth per tool call — the API key is written once into config env. HTTP editors (Cursor) store Bearer in headers.

Global by default — setup writes user-level config so Zephex works in every project. It also removes stale project-level Zephex entries that shadow global config. Add --project only when you intentionally want workspace-scoped config.

DOCTOR · REPAIR · LIST

doctor

Runs Node version check, pings https://zephex.dev/mcp, validates API key, and confirms stdio config pins zephex@latest.

shell
npx -y zephex@latest doctor

repair

Fixes unpinned stdio, OpenCode command-array shape, PATH hints for GUI-launched editors, and migrates legacy HTTP blocks to stdio for filesystem editors. Does not change Cursor/Claude Code HTTP.

shell
npx -y zephex@latest repair

list

Shows all 22+ supported editors with install status — which config files exist on disk and their transport type.

shell
npx -y zephex@latest list

Common mistake: Re-running setup repeatedly mints new API keys (free tier: 3 max). Run repair first, then doctor — only re-run setup if you need a fresh key or new editor.

GET-CONTEXT & FIND-CODE (MODE 2)

After setup saves ~/.zephex/credentials.json, run hosted tools in any terminal — no editor required.

get-context

Compact project brief — stack, auth, key files, env vars. Uploads a local file index from cwd by default.

shell
cd your-appmcpcli get-contextmcpcli get-context databasemcpcli get-context github:vercel/next.js

find-code

Fast repo-wide search — ripgrep-backed with symbol-aware results. Use --cwd for monorepos.

shell
mcpcli find-code "auth middleware"mcpcli find-code "validateToken" --cwd apps/webmcpcli usages AuthService

Full terminal guide: Terminal CLI · CLI without an AI agent.

AVOID REPEAT FAILURES
shell
# 1. Always @latest (not cached older npm)npx -y zephex@latest setup --cursor # 2. Verify immediatelynpx -y zephex@latest doctornpx -y zephex@latest list # 3. Fix stdio pins / OpenCode shapenpx -y zephex@latest repair # 4. Fully quit editor (Cmd+Q), reopen, new session

Details: MCP troubleshooting.

ALL ESSENTIAL COMMANDS
CommandWhen to use
npx -y zephex@latest setupConnect editor(s) — global config, browser OAuth, writes correct stdio/HTTP
npx -y zephex@latest initFirst-run wizard (terminal + editor picker)
npx -y zephex@latest listWhich editors have Zephex config on this machine
npx -y zephex@latest doctorNode, network, stdio pins, config health
npx -y zephex@latest repairFix unpinned zephex, wrong OpenCode command array, legacy entries
npx -y zephex@latest usageMonthly quota vs plan limit
npx -y zephex@latest disconnect --cursorRemove editor config + revoke key
npx -y zephex@latest update --applyUpgrade global npm install
WHY NO curl | bash?

Zephex does not ship curl -fsSL … | bash. Setup is editor JSON + optional browser login — not a system service. npx -y zephex@latest setup is the one-liner equivalent. See install methods.

WHERE SETUP WRITES FILES
Where setup writes config (all platforms)
macOS~/Library/…Linux~/.config/…Windows%APPDATA%Terminal creds~/.zephex/credentials.jsonVS Code MCPCode/User/mcp.jsonCursor~/.cursor/mcp.jsonAntigravity.gemini/antigravity/…npx zephexsame CLI

Same npx zephex setup command — paths differ by OS. Windows uses %USERPROFILE% and %APPDATA%.

Credentials land in ~/.zephex/credentials.json. Run npx -y zephex@latest list after setup to confirm paths.

TRANSPORT & REPAIR
Transport policy — stdio vs HTTP + repair
STDIO (local file tools)HTTP (hosted tools only)VS Code, Zednpx -y zephexAntigravityrepair migratesContinue, HermesYAML + jsoncmcpcli repairpin + PATHCursorBearer + urlClaude Codeglobal HTTPCrushHTTP by designfixesnot migrated

npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.

After upgrading the CLI, run repair before re-running setup. Account lifecycle: CLI account · HTTP vs stdio.

HOW TOOL CALLS BILL YOUR ACCOUNT
How terminal tools connect to your account
LOCAL CLIHOSTEDmcpcli find-codeMode 2 toolmcpcli usageprefix onlyFull Bearerfrom ~/.zephexkey_prefix20 charsRailway MCPauth middlewarezephex.dev/api/cli/usageusage_eventsuser_id + api_key_idtier + countsno email returnedbilllookup

Tool commands send the full API key; the proxy resolves user_id and logs usage_events. mcpcli usage only sends a 20-char prefix — tier counts, not identity.

Mode 2 terminal tools send the full Bearer key; the proxy resolves your account and logs usage. npx zephex usage is a lightweight quota check.

HOW STDIO WORKS

When your editor uses stdio, it launches npx -y zephex as a child process. The CLI forwards JSON-RPC to https://zephex.dev/mcp and reads local files for repo-aware tools.

json
{  "mcpServers": {    "zephex": {      "command": "npx",      "args": ["-y", "zephex"],      "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" }    }  }}
RUNNING MANUALLY

Test your API key before configuring an editor:

shell
# Run as stdio MCP server (what most editors call after setup)ZEPHEX_API_KEY="mcp_sk_your_key" npx -y zephex
SETUP FLAGS (from setup.ts)

npx zephex setup --cursor

Cursor

npx zephex setup --claude

Claude Code

npx zephex setup --claude-desktop

Claude Desktop

npx zephex setup --vscode

VS Code

npx zephex setup --opencode

OpenCode

npx zephex setup --codex

Codex CLI

npx zephex setup --gemini

Gemini CLI

npx zephex setup --antigravity

Antigravity

npx zephex setup --trae

TRAE

npx zephex setup --windsurf

Windsurf

npx zephex setup --zed

Zed

npx zephex setup --warp

Warp

npx zephex setup --kiro

Kiro IDE / Kiro CLI

npx zephex setup --jetbrains

JetBrains AI Assistant

npx zephex setup --droid

Factory Droid

npx zephex setup --cline

Cline

npx zephex setup --kilo

Kilo Code

npx zephex setup --crush

Crush

npx zephex setup --hermes

Hermes

npx zephex setup --chatgpt

ChatGPT

npx zephex setup --continue

Continue

npx zephex setup --copilot

GitHub Copilot CLI

npx zephex setup --roo

Roo Code

npx zephex setup --amp

Amp

npx zephex setup --project

Write project-scoped config (pair with any editor flag)

Also: --api-key mcp_sk_… (skip OAuth), --mcp / --cli (skills mode). See supported editors.

REQUIREMENTS

NODE

Node.js 18 or later (for npx)

NETWORK

HTTPS to zephex.dev on port 443

ACCOUNT

Setup creates the key, or use an existing key from the dashboard