CLI
New laptop: curl -fsSL https://zephex.dev/cli/install.sh | bash then zephex login. Returning users: zephex login — browser opens zephex.dev/cli/auth. Writes ~/.zephex/credentials.json. Terminal credentials are separate from editor MCP (~/.cursor/mcp.json).
No Node? curl -fsSL https://zephex.dev/cli/install.sh | bash. Already have Node 22.5+? npx -y zephex@latest (terminal) or npx -y zephex@latest setup --cursor (editor). Install & upgrade. Same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, or zephex (after npm i -g zephex).
First time? Install & upgrade · CLI init.
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.
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 resultExtra 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.
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 see | Why | Fix |
|---|---|---|
command not found: zephex | curl | 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 error | npx/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 names | Stale 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 files | Hosted 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 failed | cmd.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/.zephex | Windows host and WSL are two installs. | Install once in the environment that actually runs the shell or the editor. |
doctor: CLI install is ~260 MB | Old npm install -g left unused packages under ~/.zephex/npm-global. | Re-run the curl installer. Credentials stay. voice-venv is unrelated (optional STT). |
# 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 --cursorzephex and mcpcli are the same program. Type whichever you remember: zephex overview and mcpcli overview do the same thing. Also: 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)zephex initmcpcli initzephex setupmcpcli setupzephex loginmcpcli loginzephex connect --cursormcpcli connect --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 workingzephex logoutmcpcli logout # Terminal + every editor + revoke keyszephex logout --allmcpcli logout --all # Remove one editor (revokes key)zephex disconnect --cursormcpcli disconnect --cursor # Fresh key after auth errorszephex reconnect --cursormcpcli 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 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 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.