Installation
Run Zephex hosted tools with npx zephex in your terminal — no chat UI, no agent loop. Requires Node.js 18+ (or Docker on the host). Same API key as Cursor or Claude Code; human-readable briefs. Your code stays on disk; the CLI uploads a search index unless you opt into remote git.
Only want to watch videos or connect in Cursor? You are on the Terminal CLI page — skip Node/mcpcli here. Setup video (0 MB download) · Connect MCP · Quickstart
Terminal tools guide: Terminal tools complete guide
This section is for people who want npx zephex in Terminal. If you only wanted videos or editor connect, use the links at the top instead.
mcpcli, npx zephex, and npm install -g zephex are Node.js programs. They need Node.js 18+ 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.
Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org (one installer), then the Zephex CLI from npm. Total download is not huge — on the order of tens of MB for Node, plus about 2.4 MB for the CLI itself.
# Best download for most people (small + permanent):# 1) Node.js LTS installer — ~30 MB (Windows) or ~85 MB (macOS) one-time download# https://nodejs.org/en/download# 2) Then in terminal (Zephex CLI is only ~2–3 MB from npm):npm install -g zephexmcpcli setup # Smallest try-before-install (still needs Node for npx):npx zephex setup# First run downloads zephex (~2–3 MB) to npm cache; no huge SDK.| What you download | Approx. download | After 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) | ~2.4 MB | ~3–20 MB in npm cache |
| npx zephex setup (no global install) | Same ~2.4 MB CLI on first run | Cached under ~/.npm; no separate “Zephex app” installer |
Docker node:22-alpine (no local Node) | ~45–60 MB image pull | Docker Desktop ~500+; image ~45–60 MB |
| Editor-only MCP (HTTPS + API key) | 0 MB CLI — config only | No 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:
node -vnpm -vwhich nodewhich npmv18.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 18+.Step 2 — pick the best path for you:
| Your situation | Best option | Notes |
|---|---|---|
| New user, can install software | Node.js LTS + npm install -g zephex && mcpcli setup | Recommended. Shortest commands: mcpcli, zepx, zephex. |
| Have Node, try before installing globally | npx zephex setup | ~5s first download; nothing permanent except credentials. |
| Use Bun instead of Node day-to-day | bun install -g zephex | Still a JS runtime; see Bun block below. |
| Use pnpm | pnpm add -g zephex | Same CLI; see pnpm block below. |
| No Node on host; Docker allowed | Docker + npx in container | Mount $HOME so credentials survive. |
| No Node, no Docker; only Cursor / Claude | Editor MCP (HTTP) | Mode 1 in editor — not the same as terminal mcpcli tools. |
| Corporate laptop, no installs | Manual JSON config | Paste MCP config + API key; setup wizard optional on another machine. |
| Only need terminal tools occasionally | npx zephex … per command | Needs Node each time; no global PATH entry. |
Download the LTS installer if you are unsure — it includes npm. After install, close and reopen your terminal (required on Windows so PATH updates).
# 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# 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# 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 --ltsStep 3 — after Node works, run Zephex setup:
npm install -g zephex && mcpcli setupWithout global install (still needs Node + npm for npx):
npx zephex setupnpx -p zephex mcpcli setupThese still require a JavaScript runtime on the machine — not a substitute for “no Node at all.”
bun install -g zephexmcpcli setup# or one-shot:bunx zephex setuppnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setupNo Node on this computer? Use Docker (Node runs inside the image) or editor-only MCP. Docker still requires Docker Desktop / Engine on the host.
# 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-contextOptional alias so daily commands look like local mcpcli:
# ~/.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-contextFull CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.
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.
# 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# "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 18+ LTS — zephex CLI will not run on EOL Node.| Question | Answer |
|---|---|
| Do I need Node.js to use Zephex at all? | Only for the terminal CLI (mcpcli / npx zephex). Editor MCP via hosted HTTPS (Cursor, Claude Code) can work without Node on your laptop if you paste an API key or HTTP config. Terminal tools always need Node somewhere — your machine or Docker. |
| What is the best install for a new user? | Install Node.js LTS from nodejs.org (includes npm), restart the terminal, then run: npm install -g zephex && mcpcli setup. That gives the shortest commands forever. |
| 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 v18 or higher. You do not need a separate Node install for Zephex. Use the same npm/npx. |
| 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? | Node.js LTS installer is roughly 30 MB (Windows) or 85 MB (macOS) — not hundreds of MB. The zephex CLI package from npm is about 2–3 MB. npx zephex setup only adds that CLI download on first run (cached after). Docker pulls a ~50 MB Node Alpine image plus the same small zephex package inside the container. |
| What is the best way to download if I have nothing installed? | Use the official Node.js LTS installer from nodejs.org (includes npm), restart your terminal, then run npm install -g zephex && mcpcli setup. That is the smallest hassle long-term. If you truly cannot install Node, use editor-only MCP (no download) or Docker if your IT allows it. |
More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex
Browser sign-in on zephex.dev — then ~/.zephex/credentials.json is written for you. You do not paste JSON to log in.
# Requires Node.js 18+ (see "Do you have Node.js?" above) or use Docker # Recommended — install once, then one-word commands everywherenpm install -g zephexmcpcli init # No global install (one-shot)npx -p zephex mcpcli setup # Same engine, alternate bin names after global installzephex setupmcpcli setupSame tool, different prefix — after install, any of these run get-context:
mcpcli get-contextzephex get-contextzepx get-contextzphx get-context# all same binary after: npm install -g zephex| I want to… | Run this | What happens |
|---|---|---|
| Use MCP in the terminal only (no AI agent) | mcpcli setup | Browser sign-in → key saved to ~/.zephex/credentials.json. Does not edit Cursor/VS Code MCP files. |
| Use MCP inside Cursor / Claude / VS Code | mcpcli setup --cursor (or your editor flag) | Writes that editor's MCP config (often mcp.json or .vscode/mcp.json) — agent calls tools in chat. |
| Both terminal and editor | mcpcli setup --cursor then use terminal tools too | One API key, same account — not two products. |
| Sign out of terminal CLI only | mcpcli logout | Deletes ~/.zephex/credentials.json only. Editor MCP can keep working. |
| Remove Zephex from an editor | mcpcli disconnect --cursor | Edits editor config + revokes key — not the same as logout. |
| Machine-readable output (CI/scripts) | mcpcli get-context --json | --json is output format only — not a login method or JSON-file sign-in. |
login is an alias for setup (same browser flow). Details: Account & logout.
Short commands: after npm install -g zephex, use mcpcli setup (same as npx zephex setup). Requires Node.js 18+ — no Node? see options. Same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, or zephex (after npm i -g zephex).
npm install -g zephexmcpcli init cd ~/projects/my-appmcpcli get-context mcpcli find-code "validateToken"mcpcli read-code --mode outline src/lib/auth.tsmcpcli check-test "add Stripe webhooks"mcpcli check-package expressmcpcli architecturemcpcli usagemcpcli doctorHelp: npx zephex help terminal · npx zephex cli-guide
No AI agent in the loop. Your shell runs npx zephex; the CLI uploads a search index from disk (inline_files) and calls the same hosted endpoint as your editor.
From project research (see mcp-proxy/summary.md and docs/CLI-MODE2-COMPLETE-GUIDE.md): three principles apply.
https://zephex.dev/mcp.--path github:o/r.audit_headers stays editor-only (needs a live HTTP URL).| Category | Count | Where documented |
|---|---|---|
| Account & meta (setup, logout, doctor, help, …) | 25 | CLI commands · Account & logout |
| Terminal MCP tools (hosted) | 9 + 1 editor-only | This page · Terminal reference |
| find_code aliases alone | 31 | npx zephex find-code --help |
| read_code aliases | 31 | npx zephex read-code --help |
| get_project_context topics + typos | 50+ | npx zephex cli-guide project |
| Natural language (quoted phrase) | unlimited routing | npx zephex "find auth middleware" |
| MCP tool | Primary CLI | Aliases | Example | Needs project folder? |
|---|---|---|---|---|
get_project_context | get-context | 50+: context, ., stack, framework, database, backend, frontend, auth, quick, … | mcpcli get-context | Yes |
find_code | find-code | 31: find, search, grep, rename, everywhere, usages, defs, where, … | mcpcli find-code "auth middleware" | Yes |
read_code | summarize / outline / symbol | 31: read-code, read, explain, show, files, peek, … | mcpcli outline src/lib/auth.ts | Yes |
explain_architecture | architecture | 6+: arch, explain-architecture, structure | mcpcli architecture --focus auth | Yes |
check_test | check-test | 9: scope, plan, files-for, touch, scope-task | mcpcli check-test "add Stripe webhooks" | Yes |
keep_thinking | think | 3: reason, debug-think (one-shot in terminal) | mcpcli think "debug 401 after refresh" | No |
check_package | check-package | 13: check, safe, lookup, pkg, package | mcpcli safe express | No |
project_memory | project-memory | 0: | mcpcli project-memory | No |
Zephex_dev_info | docs | 2: ask | mcpcli docs "Stripe webhooks" | No |
Editor-only (still part of the same MCP server after setup):
audit_headers — HTTP/TLS header audit on a live URL — requires a running dev server; use in Cursor/Claude after setup.keep_thinking (multi-turn) — Terminal has one-shot think/reason/debug-think; sessionId flows are editor-only.| Command | Aliases | What it does |
|---|---|---|
init | onboard, getting-started | First-run wizard: prereq checks → zephex.dev/cli/auth → terminal + optional editor |
setup | login, sign-in, connect | Browser OAuth → API key → editor MCP config + ~/.zephex |
connect | — | Alias for setup — connect MCP to any of 22+ editors |
logout | sign-out | Delete ~/.zephex; --all also disconnects every editor |
disconnect | remove | Remove Zephex from editor JSON; revoke key server-side |
reconnect | — | disconnect --quiet + fresh setup (--cursor, --claude-code, --vscode, …) |
reset | — | disconnect + remove skill/rule files |
status | — | Live MCP tools/list per installed editor config |
list | ls | Every supported editor — installed or not |
doctor | — | Node, network, MCP reachability, project index, API key |
keys | — | Masked keys + usage; links to dashboard |
usage | stats | Per-tool call counts this billing month |
tools | — | List / enable / disable MCP tools in editor config |
skills | — | Install or upgrade agent skill + rule markdown |
info | version, -v | Package version and install path |
help | -h, --help | Full reference; topics: terminal, tools, setup |
cli-guide | guide, howto | Mode 2 deep guide (topics: project, auth, monorepo, …) |
learn | commands | Per-tool terminal guide (no MCP call); index or learn find_code |
compass | — | Command Compass — guide when input doesn't match a command (no MCP call) |
ask | — | Natural-language router to find, context, package, architecture |
deps | dependencies | Scan all direct deps in package.json (batch check_package) |
compare | vs | Side-by-side package intel for two npm packages |
history | hist, again, repeat | Local command log; re-run with history N or again |
update | upgrade (no args) | Check npm latest; --apply runs npm install -g zephex@latest |
repair | — | Fix broken stdio npm pins in editor MCP configs |
Connect / disconnect testing: CLI account & logout · Connect MCP
| Run | You get |
|---|---|
mcpcli help | Editors + account + terminal overview |
mcpcli help terminal | Every Mode 2 alias on one screen |
mcpcli help tools | All 10 MCP tools — editor vs terminal |
mcpcli help setup | Editor flags, --project vs --global |
mcpcli cli-guide | Mode 2 guide index |
mcpcli cli-guide project | Scenarios A–H (where am I searching?) |
mcpcli cli-guide account | logout vs disconnect lifecycle |
mcpcli find-code --help | Per-tool flags for find_code |
mcpcli logout --help | Terminal sign-out vs disconnect |
mcpcli update --help | Check and apply npm CLI upgrades |
This table matches npx zephex cli-guide project and the engineering handoff in handoff/cli-mode2/.
| # | Situation | Expected |
|---|---|---|
| A | Terminal in app folder (package.json + src/) | Using local project (N files from …) |
| B | Monorepo root (thin workspace package.json) | Auto-pick busiest package; (monorepo) in label |
| C | Private repo on disk | Local inline_files only — no public GitHub required |
| D | Public OSS without clone | get-context github:owner/repo or --path on find/read |
| E | ~, /tmp, or empty folder | No project here — fail fast, do not burn quota |
| F | No API key | Run mcpcli setup or set ZEPHEX_API_KEY |
| G | File path while cwd is wrong | Error names project root; use cd or --cwd |
| H | check-package / loop-guard | Works with no project folder |
cd your-appmcpcli get-contextmcpcli find-code "AuthService"mcpcli read-code --mode outline src/auth.tsmcpcli check-test "add OAuth"mcpcli architecture --focus authmcpcli ask "what stack is this" --path github:docker/mcp-registrymcpcli help terminalmcpcli cli-guide projectmcpcli explain-architecturemcpcli loop-guard react--json prints machine-readable tool output for scripts. It does not change how you sign in.
--json Raw MCP JSON output (CI / agent parity) — NOT login--cwd <dir> Project or package root (monorepos)--no-local Use git remote instead of folder upload--path github:o/r Explicit remote repo--api-key mcp_… Override ~/.zephex / ZEPHEX_API_KEY-q, --quiet Less stderr--force Refresh get-context cache only# Copy-paste test flow (no AI agent) — mcpcli = zephexnpm install -g zephexmcpcli initmcpcli doctorcd your-app # folder with package.json + srcmcpcli get-contextmcpcli find-code "test"mcpcli safe lodashmcpcli logoutmcpcli setup # sign in againmcpcli update --checkIf find-code prints Using Git remote then errors, update the CLI — 2.4+ defaults to local upload. From this repo: cd mcp-proxy && bun run build && npx . find-code "test"