CLI
Install & upgrade the Zephex CLI
This is the page for “how do I install Zephex”, “how do I upgrade the CLI”, and “how should an AI agent use Zephex”. After install, zephex and mcpcli are the same program — zephex overview and mcpcli overview both work. Same API key as the editor MCP.
Shortest path (new laptop, no Node, no framework):
curl -fsSL https://zephex.dev/cli/install.sh | bashThen source ~/.zephex/env.sh, cd into a project, zephex login or mcpcli login, type /overview.
How to install Zephex CLI
There are two products that share one npm package named zephex:
- Terminal CLI (Mode 2) — you type
zephex//overviewin a real shell. Use the curl installer if you do not have Node. - Editor MCP (Mode 1) — Cursor, Claude Code, VS Code, etc. call the same tools. Use
npx -y zephex@latest setup --cursorif you already have Node 22.5+.
curl — no Node required
curl -fsSL https://zephex.dev/cli/install.sh | bashSame file also lives at https://zephex.dev/install.sh. The script installs into ~/.zephex, adds PATH in your shell rc, and downloads a private Node 22 only if your machine is below 22.5. It does not write Cursor/Claude config — that is zephex connect --cursor later.
Download size: about 3 MB for the CLI tarball (~13 MB on disk). Plus ~50 MB compressed Node if you have none.
npx / pnpm / bun — you already have Node 22.5+
npx -y zephex@latestpnpm dlx zephex@latestbunx zephex@latestThose start the CLI (or the TUI if you are in a real terminal). They are not the editor wizard. For editors:
npx -y zephex@latest setup --cursornpx -y zephex@latest setup --claudenpx -y zephex@latest setup --opencodenpx -y zephex@latest setup --codexWindows
irm https://zephex.dev/install.ps1 | iexDo not pipe the bash installer in cmd.exe. WSL and Git Bash use the curl line inside Linux. ARM Windows (Surface) uses the same install.ps1 — it picks win-arm64 Node. Paths: Windows guide.
macOS and Linux
Same curl line. Intel and Apple Silicon, x64 and arm64 Linux, Cloud Shell, Codespaces, and most VMs. After install, this window still needs source ~/.zephex/env.sh. New tabs pick it up from ~/.zshrc / ~/.zprofile / ~/.bashrc. macOS · Linux.
Phone / iPad
There is no native iOS CLI. Use the web terminal or SSH into a machine that has the installer. Android Termux can run the curl line.
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.
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.
First commands
source ~/.zephex/env.shcd your-appzephex login # same: mcpcli loginzephex overview # same: mcpcli overviewmcpcli overview # identical — pick the name you rememberzephex# type /overview /deep /find /help/help and /learn work without a key. Hosted tools (/overview, /architecture, /find) need zephex login / mcpcli login or a key from the dashboard.
zephex overview/mcpcli overview— what this repo iszephex deep --json/mcpcli deep --json— agent orientation packetzephex find "auth"/mcpcli find "auth"— searchzephex architecture --focus auth/mcpcli architecture --focus auth— wiringzephex safe lodash/mcpcli safe lodash— package CVEs before npm installzephex test/mcpcli testthenzephex check test failureszephex usage/mcpcli usage·zephex keys/mcpcli keys— credits by key namezephex doctor/mcpcli doctor— Node, Railway, API key, fat install size
Full map: terminal CLI · slash commands · command list.
How to upgrade the Zephex CLI
zephex update --checkmcpcli update --check # same CLI zephex update --applymcpcli update --apply # same # same as re-running the installer (safe to repeat; keeps credentials)curl -fsSL https://zephex.dev/cli/install.sh | bash # Windowsirm https://zephex.dev/install.ps1 | iex # confirmzephex infomcpcli infozephex doctormcpcli doctorIf you do not upgrade: an older CLI still talks to the same Railway MCP and the same API key. You only miss newer login (QR), usage labels, and the slim installer. Nothing billing-related breaks.zephex update --check tells you when npm is newer.
Re-running the curl installer is safe. It replaces the CLI files under ~/.zephex/npm-global and keeps ~/.zephex/credentials.json.
How AI agents should use Zephex
If a human asks an agent to “research my CLI”, “install Zephex”, or “run overview”, the agent should follow this — not invent flags.
Help this user install and use the Zephex terminal CLI. This is Mode 2 — a real shell on their machine. It is not Cursor / Claude Code / Codex MCP. Those editors talk to https://zephex.dev/mcp inside the chat. This prompt is for when they (or you) want to run the same tools from a terminal. Read this skill first:https://github.com/zephexMCP/zephex-cli Install + upgrade: https://zephex.dev/docs/zephex-cliEvery command: https://zephex.dev/docs/cli-commands Install — pick one:- No Node.js (or you are not sure). Mac / Linux / WSL / Cloud Shell. ~3 MB CLI; private Node 22 only if missing: curl -fsSL https://zephex.dev/cli/install.sh | bash source ~/.zephex/env.sh- Already have Node 22.5+? npx -y zephex@latest- Windows PowerShell: irm https://zephex.dev/install.ps1 | iex Then: cd /absolute/path/to/their-project zephex login zephex doctor The product command is zephex. After install there is also mcpcli — same file, same result. If they already type mcpcli, that is fine. Write new examples as zephex. Always cd into the project (or pass --cwd). The CLI uses the current directory. Do not invent flags. From a normal shell, type the commands below (not slash commands — those only exist inside the interactive TUI after they run bare `zephex`). The five commands that matter first: zephex overview What is this repo? Stack, scripts, how to run it. First touch on an unknown project. zephex structure Folder / language map. Cheap local layout. Use this before you guess where files live. zephex architecture How the app is wired (auth, layers, request flow). Add --focus auth (or another area) when they asked about one slice. zephex find "the symbol or concept" Ranked search. Prefer this over grepping blindly. zephex test Detect the runner and run the suite. After that: zephex check test failures. If the binary is missing or doctor complains, re-run the curl installer (it keeps ~/.zephex/credentials.json). To upgrade later: zephex update --check zephex update --apply Same API key and 555 free requests/mo as hosted MCP. Do not run `npx -y zephex@latest setup --cursor` unless they also want editor MCP.- Prefer MCP tools when Zephex is already connected in the editor (
get_project_context,find_code, …). - Prefer the CLI when the user is in a shell, wants
deep --json, or asked for Mode 2 /zephex …. - Always
cdto the project (or pass--cwd). The CLI uses the current directory. - Before
npm install, runzephex safe <pkg>(same as MCPcheck_package). - After code edits,
zephex testthenzephex check test failures.
Skill for agents: github.com/zephexMCP/zephex-cli. Same prompt is on the homepage AI Agent → CLI tab. Editor MCP is npx zephex setup. Do not tell users to install Node first if they can run curl.
What lands on the machine
~/.zephex/bin/zephexandmcpcli~/.zephex/npm-global/lib/node_modules/zephex— the CLI bundle only~/.zephex/node— only if the installer had to bundle Node~/.zephex/env.sh+ a block in~/.zshrc/~/.bashrc- After login:
~/.zephex/credentials.json(mode 0600)
Hosted commands go to https://zephex.dev/mcp (Railway). Sign-in is https://zephex.dev/cli/auth. Usage is stored per user_id and API key name.
If zephex doctor or mcpcli doctor says the install is ~260 MB, leftover npm deps from an old npm install -g — re-run the curl installer.
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). |
If something looks wrong
command not found: zephex—source ~/.zephex/env.sh, new terminal tab- Node 18/20 +
npx— use curl instead (needs 22.5+) - Corporate TLS — allow HTTPS to zephex.dev, registry.npmjs.org, nodejs.org
- Mixed Windows + WSL paths — install once, in the environment that actually runs the shell
- Never run a random gist. Only
https://zephex.dev/cli/install.sh
More: all install methods · npx / editor setup · login / logout / keys · CLI without an agent · MCP troubleshooting