Installation
New users: mcpcli init. Returning users: mcpcli setup or mcpcli login — your browser opens zephex.dev/cli/auth (dashboard login, not docs). Setup writes ~/.zephex/credentials.json automatically; you never paste a JSON file to authenticate. Terminal credentials are separate from editor MCP config (~/.cursor/mcp.json, .vscode/mcp.json, etc.).
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).
First time? See CLI init (first run) for the guided wizard.
# Sign in (browser) + editor config + terminal credentialsnpm install -g zephex && mcpcli setupmcpcli setup --cursormcpcli login --vscode # alias for setup # Check account & connectionmcpcli statusmcpcli doctormcpcli usagemcpcli keys # open dashboard keys page # Remove from editors (revokes key server-side)mcpcli disconnect --cursormcpcli disconnect --all # Terminal sign-out only (editors unchanged)mcpcli logout # Fresh config after disconnect (all editor aliases work)mcpcli reconnect --cursormcpcli reconnect --claude-codemcpcli reconnect --vscodemcpcli reconnect --factory-aimcpcli reconnect --zedmcpcli reconnect --terminal # Full sign-outmcpcli logout --all # Disconnect + remove skill/rule files Zephex addedmcpcli reset --cursorAfter npm install -g zephex, every bin runs the same CLI: mcpcli · zephex · zepx · zphx · mcpz · zepcli · zephx. Interactive help: mcpcli cli-guide account · mcpcli logout --help · mcpcli connect --help
Sign-in opens https://zephex.dev/cli/auth — the dashboard OAuth page, not documentation. Backend: POST /api/cli/session creates a session; browser completes auth at /cli/auth?session=…; CLI polls until the key is written to ~/.zephex/credentials.json.
# Browser opens dashboard login (NOT docs)mcpcli initmcpcli setupmcpcli login # alias for setupmcpcli connect --cursor # alias for setup --cursor # Login URL (implementation)# POST /api/cli/session → redirect /cli/auth?session=…Stdio editors never re-auth per tool call — the API key is written once into config env. HTTP editors (Cursor) store Bearer in headers.
connect, setup, and login run the same flow. First-time users: mcpcli init. Your email is shown once during browser sign-in — it is not stored in credentials.json (use the dashboard for account info).
logout only removes terminal credentials. Editors keep their MCP config and API key until you disconnect or revoke at dashboard keys.
# Terminal only — editors keep workingmcpcli logout # Terminal + every editor + revoke keysmcpcli logout --all # Remove one editor (revokes key)mcpcli disconnect --cursor # Fresh key after auth errorsmcpcli reconnect --cursorAfter npm install -g zephex, check for newer npm releases and apply without reinstalling manually. Same command whether you type mcpcli or zephex.
# Check installed vs npm latestmcpcli updatemcpcli update --check # Apply upgrade (global install)mcpcli update --apply # Refresh agent skill files after upgrademcpcli skills --upgrade # Verifymcpcli infomcpcli doctormcpcli update --apply # same: zephex update --apply
setup writes both editor MCP config and terminal credentials. logout only removes ~/.zephex. disconnect revokes the key and strips editor config.
This is the most common confusion. They solve different problems. Implementation matches src/commands/logout.ts and src/commands/disconnect.ts — not interchangeable.
| Command | What it changes | Key on server | When to use |
|---|---|---|---|
logout | Deletes ~/.zephex/credentials.json (Windows: %USERPROFILE%\.zephex\credentials.json) | Still valid until you revoke it | Sign out of terminal tools only; keep Cursor/VS Code connected |
disconnect | Removes Zephex block from editor MCP JSON; revokes that key | Revoked | Stop MCP in an editor; rotate compromised key |
reconnect | Quiet disconnect + full setup again | New key after setup | 401 errors, expired key, fresh OAuth |
reset | disconnect + removes Zephex skill/rule files it added | Revoked | Clean uninstall from a machine |
# Example: keep Cursor MCP, stop terminal tools using your keymcpcli logout# get-context will ask you to run setup again # Example: fully remove Zephex from Cursormcpcli disconnect --cursor# Restart Cursor — Zephex tools gone| Command | Aliases | Purpose |
|---|---|---|
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 |
uninstall | — | Remove Zephex CLI from PATH; --full deletes ~/.zephex |
welcome | — | Print home screen (tools, slash palette, quota) |
voice-check | — | Diagnose Voice Mode (pipe, PTT, STT subprocess) |
voice-setup | — | Interactive Voice Mode setup (pipe + env vars) |
slash-demo | slash-preview | Print / palette without TTY (docs + CI) |
remember | — | Store a project fact → project_memory MCP |
recall | — | Search saved memories by keyword |
memory | — | list | forget <uuid> — project_memory CLI |
check url | site-audit, audit-headers, check-url | Live HTTP/TLS header audit → audit_headers MCP |
web | website, scan-web | Full hosted website overview scan |
site | pulse, broken | Site Pulse — fast local HTTP or cloud browser scan |
supply | sup, chain | Supply Pulse — secrets, CVEs, deploy surface on URL or repo |
shadow | shadow-audit | Hidden API surface scan on repo or live URL |
upgrade | upgrde, updgrade | Package smart upgrade (check_package --task upgrade); bare = CLI self-update |
loop-guard | — | Alias for check-package --task upgrade (breaking-change guard) |
last | — | Repeat last package lookup |
Run this in a terminal to prove setup, terminal tools, logout, and reconnect — no editor required for the middle steps.
Prove Mode 2 works from your shell before you connect Cursor or VS Code.
# Copy-paste test flow (no AI agent) — mcpcli = zephexnpm install -g zephexmcpcli initmcpcli doctorcd your-app # folder with package.json + srcmcpcli overviewmcpcli get-contextmcpcli find-code "test"mcpcli safe lodashmcpcli check-testmcpcli check url https://example.commcpcli remember "first run used overview + get-context"mcpcli logoutmcpcli setup # sign in againmcpcli update --check# Editor-only test (after setup --cursor)mcpcli status # should list 10 toolsmcpcli disconnect --cursor# Restart Cursor → Zephex tools gonemcpcli reconnect --cursor# Restart Cursor → tools backsetup and login are the same command. It:
mcpcli setupmcpcli setup --cursor --projectmcpcli connect --claude-codemcpcli setup --api-key mcp_prod_xxx # skip browser if you already have a keyMCP connection walkthrough: Connect Zephex MCP.
Terminal tools resolve the API key in this order:
ZEPHEX_API_KEY or MCP_API_KEY~/.zephex/credentials.json (written by setup)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.
Manage keys in the dashboard: zephex.dev/dashboard/keys. Naming and formats: Key naming. Tool commands bill against your user_id server-side; mcpcli usage only sends a key prefix and returns tier counts.
Same npx zephex setup command — paths differ by OS. Windows uses %USERPROFILE% and %APPDATA%.
Same npx zephex setup on macOS, Windows, and Linux — only the on-disk paths differ. Windows uses %USERPROFILE%\.zephex\ and %APPDATA%\. Run mcpcli list to see every config file Zephex knows about on this machine.
npx zephex repair migrates HTTP → stdio for filesystem editors. Cursor, Claude Code (global HTTP), and Crush stay HTTP by design.
Most editors use stdio (npx -y zephex) so repo tools read your workspace. Cursor, Claude Code (global HTTP), and Crush stay HTTP. Run mcpcli repair to pin stdio versions, fix OpenCode command arrays, and migrate legacy HTTP entries for filesystem editors. Details: HTTP vs stdio.
Skills ship via setup --with-skill or skills install. Removal paths differ: per-editor reset vs global skills --remove.
| Action | Command | What changes |
|---|---|---|
| Add on first setup | mcpcli setup --cursor --with-skill | Installs find-code skill + rule for that editor |
| Add later | mcpcli skills --cursor | Installs skill + rule for one editor without re-running OAuth |
| Remove from one editor + skills | mcpcli reset --cursor | disconnect + skill removal (reset always passes --with-skill) |
| Remove all skill copies | mcpcli skills --remove | Strips skill/rule from every known editor path |
Pick the smallest command that matches your goal. These map to logout.ts, disconnect.ts (reset in cli.ts calls disconnect with --with-skill), and skills.ts.
| Goal | Command | Terminal creds | Editor MCP | Skills | Keys revoked |
|---|---|---|---|---|---|
| Stop terminal tools only | mcpcli logout | Deleted | Unchanged | Unchanged | No |
| Remove one editor | mcpcli disconnect --cursor | Unchanged | Stripped | Unchanged | Yes (that key) |
| Clean one editor + skills | mcpcli reset --cursor | Unchanged | Stripped | Removed | Yes |
| Remove every editor | mcpcli disconnect --all | Unchanged | All stripped | Unchanged | Yes (per editor key found) |
| Full machine sign-out | mcpcli logout --all | Deleted | All stripped | Optional via reset | Yes |
# Nuclear option — terminal + all editors + revokemcpcli logout --all # Also remove every skill copy Zephex installedmcpcli skills --removemcpcli doctor# Node version, network, MCP reachability mcpcli status# Tier, key prefix, connection state mcpcli list# Which editor config files reference Zephex mcpcli repair# Fix unpinned stdio, OpenCode shape, GUI PATH hints mcpcli usage# Monthly request count vs plan limit mcpcli keys# Masked keys + dashboard link # If setup keeps failing the same way — use @latestnpx -y zephex@latest doctornpx -y zephex@latest repairConnection failures: MCP troubleshooting · Global setup is the default (no --project unless you want workspace-scoped config).
Use the same editor flags as setup. --all removes every Zephex entry the CLI knows about on this machine. Unlike setup, disconnect has no --project flag — it always checks both global and project config paths for that editor (project paths use your current working directory). Run cd into the repo before disconnect if you only want project-level files cleaned alongside global paths.
mcpcli disconnect --cursormcpcli disconnect --vscodemcpcli disconnect --continuemcpcli disconnect --hermesmcpcli disconnect --kilomcpcli disconnect --claude-codemcpcli disconnect --allmcpcli disconnect --quiet # used internally by reconnectRevokes mcp_prod_ and legacy mcp_sk_ keys found in removed config blocks. Hermes YAML and Continue project JSON are supported (v2.5.5+).
600 on Unix; never commit API keys.logout does not revoke the key — use disconnect or revoke in the dashboard.mcpcli reconnect --cursor or create a new key and run setup with --api-key.Related: Authentication · API key management · Terminal CLI.