CLI
New laptop: curl -fsSL https://zephex.dev/cli/install.sh | bash then zephex init --terminal. The wizard opens zephex.dev/cli/auth (dashboard login, not docs). Credentials land in ~/.zephex/credentials.json. Same binary: zephex, mcpcli, zphx.
Login URL: https://zephex.dev/cli/auth (user login). Docs are reference only — init never sends you to a docs page to authenticate.
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).
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). |
# Install (no Node required)curl -fsSL https://zephex.dev/cli/install.sh | bashsource ~/.zephex/env.sh # Or if Node 22.5+ is already installednpm install -g zephex && mcpcli setup # First run — browser opens zephex.dev login (NOT docs)zephex init --terminalmcpcli init # Terminal only (no editor MCP config)mcpcli init --terminal # Skip picker — connect Cursor after loginmcpcli init --cursor # Non-interactive (CI / scripts) — terminal sign-in onlymcpcli init -y # After init — try inside your project foldermcpcli get-contextmcpcli find-code "auth"mcpcli learn # Account lifecycle (all 22+ editors — same flags)mcpcli connect --cursormcpcli connect --claude-codemcpcli disconnect --vscodemcpcli reconnect --zedmcpcli logoutmcpcli logout --allmcpcli updatemcpcli update --applymcpcli doctor| Command | Best for | Browser opens |
|---|---|---|
mcpcli init | Brand-new users — guided first run | zephex.dev/cli/auth |
mcpcli setup | Pick editor, scope, skill mode | zephex.dev/cli/auth |
mcpcli login | Alias for setup | zephex.dev/cli/auth |
Install once: npm install -g zephex. Then any bin name works:
| npm package | Command names |
|---|---|
zephex (canonical) | zephex, mcpcli, zepx, zphx, mcpz, zepcli, zephx |
@tanstratum/mcpcli | mcpcli, zephex |
@tanstratum/zphx | zphx, mcpcli, zephex |
mcpcli initzephex initzphx init --terminalnpx -p zephex mcpcli initzephex 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.
cd your-appzephex get-contextmcpcli get-contextzephex find-code "auth"mcpcli find-code "auth"zephex overviewmcpcli overviewzephex doctormcpcli doctorHelp: mcpcli help terminal · mcpcli ask --help
# 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