Core documentation content is fully readable without JavaScript. The table of contents, assistant, and some copy buttons enhance the experience but are not required.

Installation

zephex deep — Project Dossier

One command on your local project: stack, how pieces connect, and ranked files for your task — so humans and AI agents stop flailing with random greps.

START HERE

cd your-appmcpcli deepmcpcli deep "auth middleware"mcpcli deep "add a settings button on the profile page"mcpcli deep "stripe billing usage" --json # Same binary after global installmcpcli deep   # same: zephex deep# Aliases: dossier · know · full-brief · project-deep# Slash palette: /deep

Needs a logged-in CLI key ( CLI account). Prefer a current local build or npm install -g zephex after publish — older registry bins may not map deep correctly.

What it is

One sentence

zephex deep is a local CLI orchestrator (Mode 2) that runs your existing Zephex analysis tools together — context, architecture, and search — then stitches a long plain-English Project Dossier (or --json for agents).

Product name

Project Dossier

Command: deep. Not a new MCP gallery tool. Not a full-repo dump. Local-first — cd into any app and run it.

With a task

Where to look first

Free text like auth middleware, settings button on profile, or stripe billing changes ranking and tool focus so the touch list matches the job.

Without a task

Full orientation

Product story, stack, run scripts, structure, architecture hubs — a richer start than a thin map.

What it is not

Not a replacement for Claude Code / Cursor — it feeds agents and humans so they start editing sooner
Not a Repomix-style dump of every file (token bomb)
Not a new MCP tool in the gallery (v1 is CLI-only orchestration)
Not a substitute for Test Pulse or Supply Pulse — different jobs

Install

Get the CLI

CURL INSTALLER

curl installer — terminal CLI (Mode 2)

This one-liner is the Mode 2 terminal installer — the same zephex shell you type / in. It is not the editor MCP wizard on the homepage (npx -p zephex mcpcli setup). Same account and API key later; different first command.

curl -fsSL https://zephex.dev/cli/install.sh | bash

Same script lives at both URLs (use either):

curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash

What it does

Installs into ~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.
If your system Node is missing or older than 22.5, it downloads a private Node 22 runtime (~50 MB compressed, once) under ~/.zephex/node.
Downloads the zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).
Starts zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).

By operating system

macOS (Intel or Apple Silicon) — Terminal or iTerm. Needs curl (already there). After install, new Terminal windows pick up PATH from ~/.zshrc and ~/.zprofile. The current window still needs:

source ~/.zephex/env.sh

Linux (x64 or arm64) — bash, zsh, or fish. Same curl line. PATH is appended to ~/.bashrc / ~/.profile (and fish config if needed). If you installed as one user and launch the desktop as another, the binary will not be on PATH — stay on the same account.

Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:

irm https://zephex.dev/install.ps1 | iex

WSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.

Cloud shells, phones, other OS

Google Cloud Shell, GitHub Codespaces, Railway / Render shells — use the same curl line. Those boxes often ship Node 18 or 20. The installer notices and downloads a private Node 22 under ~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.
Android (Termux) — curl + bash work. Same installer. Hosted commands still need HTTPS out to zephex.dev.
iPhone / iPad — there is no native zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.
Windows ARM (Surface, Snapdragon) — PowerShell installer downloads the win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.

What the CLI talks to

Install download — Vercel serves install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.
Sign-in — browser or QR hits zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600).
Tool commands (/overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.
Sentry — Railway captures hosted tool / API errors (tagged with CLI version). The local zephex process does not send your repo to Sentry.

After install — first commands

source ~/.zephex/env.shcd your-appzephex# type /overview   or   /help

Hosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.

Upgrade

The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:

zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bash

Check what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.

This vs the homepage npx line

curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.
npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.
You can use both with one API key. Install the CLI first, then zephex connect --cursor when you want the editor.

Uninstall

zephex uninstall           # PATH + credentialszephex uninstall --full    # delete entire ~/.zephex

If something looks stuck

command not found: zephex — source ~/.zephex/env.sh, then open a new tab.
Piped curl into bash: the installer cannot keep PATH in that parent shell. That is why it prints the source line.
Only run the script from zephex.dev— never a random gist.
Offline or corporate TLS intercept: the script needs HTTPS to zephex.dev (npm package) and, if Node is missing, nodejs.org.

More paths: all install methods · macOS · Linux · Windows · terminal CLI

mcpcli is the short install name for the Zephex MCP CLI (npm package zephex). Same binary, same API key, same 10 tools — you can type mcpcli instead of zephex after a one-time install. Official package name on npm remains zephex; command aliases ship inside that package (v2.4.6+).

Node.js required (or alternatives)

Includes best download path and how many MB each option uses — see download sizes.

mcpcli, npx zephex, and npm install -g zephex are Node.js programs. They need Node.js 22+ 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.

BEST DOWNLOAD · HOW MANY MB?

Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org or skip Node entirely with the curl installer (~3 MB CLI tarball). npm install -g zephex currently unpacks ~260 MB of unused deps — prefer curl.

# Best download — no Node required (~3 MB CLI; +~50 MB Node only if missing)curl -fsSL https://zephex.dev/cli/install.sh | bash # Already have Node 22.5+ and want editor MCP only:npx -y zephex@latest setup --cursor # Avoid until slim publish: npm install -g zephex / bare npx zephex# Those currently also install unused server libraries (~260 MB).

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`)	~3 MB	~260 MB in npm cache
npx zephex setup (no global install)	Same ~3 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 npm

v18.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 22+.

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.

INSTALL NODE.JS (MAC · WINDOWS · LINUX)

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 --lts

Step 3 — after Node works, run Zephex setup:

npm install -g zephex && mcpcli setup

Without global install (still needs Node + npm for npx):

npx zephex setupnpx -p zephex mcpcli setup

BUN & PNPM (ALTERNATIVE RUNTIMES)

These 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 setup

pnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setup

No 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-context

Optional 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-context

Full CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.

EDITOR ONLY — NO LOCAL NODE

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

TROUBLESHOOTING

# "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 22.5+ — or use curl install.sh, which bundles Node.

FAQ

Question	Answer
Do I need Node.js to use Zephex at all?	Not for the curl installer — it bundles Node 22 under ~/.zephex if needed. npx / npm / bun still need Node 22.5+ on PATH. Editor MCP over HTTPS can work with only an API key.
What is the best install for a new user?	curl -fsSL https://zephex.dev/cli/install.sh \| bash — then source ~/.zephex/env.sh. That works with or without Node. Use npx zephex setup --cursor only when you already have Node 22.5+ and want editor MCP.
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 v22.5 or higher. Below that, use the curl installer — it downloads a private Node 22 instead of failing.
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?	curl installer: ~3 MB CLI tarball, plus ~50 MB Node only if you are below 22.5. npm install -g zephex / npx zephex currently also pull unused server libraries (~260 MB, ~2 minutes) until the slim package is published. Docker is a ~50 MB Node image plus that same npm package.
What is the best way to download if I have nothing installed?	curl -fsSL https://zephex.dev/cli/install.sh \| bash. If you cannot run curl\|bash, use editor-only MCP (paste a key into Cursor) or the web terminal. Do not start with npm install -g until the slim package is on npm.

More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex

First time (any OS, Node already installed)

Pick one path — both work the first time you run setup:

Recommended — global install (shortest commands forever):

npm install -g zephex && mcpcli setup

One-shot without global install (pick one):

npx zephex setupnpx -p zephex mcpcli setup

Plain mcpcli setup only works after npm install -g zephex (or the combined line above). That is expected — there is no separate npm package named mcpcli on the public registry.

After install — daily commands

mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctor

All of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.

Terminal-only vs editor MCP

MCP CLI (Mode 2) runs in your shell — no AI agent required. mcpcli setup when you pick Terminal / CLI only does not change Cursor/VS Code MCP config. Use mcpcli setup --cursor (or another flag) if you also want tools inside the editor.

logout vs disconnect: mcpcli logout removes only ~/.zephex terminal credentials — your editor can keep using MCP. mcpcli disconnect removes Zephex from an editor config and revokes the key — not the same as logout. You can use terminal tools and editor MCP together with one API key; you do not run two separate products.

Who can run it?

Anyone in the world can download and run mcpcli / zephex from npm (public CLI). Your hosted MCP tools at https://zephex.dev/mcp require your API key from setup — strangers cannot use your quota without a key. Keys stay in ~/.zephex (or editor config); nothing secret is baked into the npm package.

Connect MCP (editors) · Terminal tools · Full command list · Install & package names · Install methods (no Node / Docker / manual) · CLI in Docker

Confirm the command exists:

mcpcli deep --help# Expect: full project intelligence dossier · aliases dossier/know/full-brief

Commands

Everyday usage

# Full local orientationmcpcli deep # Task-focused (this is the main product)mcpcli deep "auth middleware"mcpcli deep "add rate limiting on API"mcpcli deep "stripe billing usage"mcpcli deep "add a settings button on the profile page"mcpcli deep "new CLI command" # Agent / machine packetmcpcli deep "auth middleware" --jsonmcpcli deep "auth middleware" --json -o .zephex/deep.json # Expand / cachemcpcli deep --fullmcpcli deep --more stackmcpcli deep --more touchmcpcli deep --force                    # bypass ~30m cache # Another package in a monorepomcpcli deep --cwd dashboard "profile settings UI" # Optional public remote (secondary)mcpcli deep github:owner/repomcpcli deep github:owner/repo "add auth"

Aliases

dossier, know, full-brief, project-deep — same command. Interactive slash palette: /deep, /dossier.

Flags

Flag	What it does
`--json`	Stable `schema_version: 1` JSON for agents (no pretty human card)
`--full`	Deeper architecture, fuller context, more touch files
`--more <section>`	Expand one chapter: `story` · `stack` · `touch` · `architecture` · `all`
`--force` / `-f`	Bypass local deep cache under `.zephex/`
`--cwd <dir>`	Analyze that directory (monorepo package)
`--path` / remote	Explicit path or `github:owner/repo`

How it works

Pipeline (inside one command)

Resolve local project root (and monorepo package if needed)
Classify the task string (auth, frontend, billing, CLI, jobs, …) — no LLM
Run in parallel (partial results if one times out):
- get_project_context — stack, scripts, structure
- explain_architecture — wiring + task concern
- find_code — hosted search (limited by upload)
Local disk ripgrep — required for real private repos (hosted find only sees a small inline_files subset)
Rank likely_touch — real paths only, never invented
Render human dossier or --json

Tools deep reuses (specialties)

Tool	Specialty in deep
`get_project_context`	Stack, scripts, monorepo shape, topic slices
`explain_architecture`	Entry points, auth, integrations, concern cluster
`find_code`	Hosted keyword search (best-effort on local private trees)
Local `rg`	Primary touch-list source on disk — multi-language, no monorepo allowlist

Credits are billed as the underlying tool calls (context + architecture + find). The footer shows tools used, time, confidence, and estimated credits.

Task mode

Free-text tasks (any project)

Pass any goal as a string. Intent routing picks context topics and find queries. Ranking prefers basename / path-segment matches so auth.ts beats a random index.ts.

Example task	Intent bias
`auth middleware` · `OAuth login`	Auth & access
`settings button on profile`	UI / frontend (may suggest `--cwd` for app packages)
`stripe billing usage` · `payment webhook`	Billing & usage
`rate limiting` · `API proxy`	API / backend
`database schema migration`	Data — prefers real `migrations/` trees
`new CLI command`	CLI / commands
`background job queue`	Jobs & workers (not UI Background components)

Human output shape (with task)

TASK — ordered steps (open this file first, then that one)
IMPORTANT — honesty when the package does not match the task (e.g. UI on a backend-only tree)
WHERE TO LOOK — ranked real paths with short why
Focus section (AUTH & ACCESS, UI / FRONTEND, BILLING, …)
Compact STACK + HOW YOU RUN IT (context, not the main product)
NEXT / DIG DEEPER — get-context topic, architecture, find, test

JSON for agents

`--json` contract

Same run, machine-readable. Agents should open likely_touch[0..2], read plan, respect honesty, and treat stack/run as context only.

{  "schema_version": 1,  "project_root": "/abs/path",  "task": "auth middleware",  "product": { "name": "", "summary": "", "kind": "web|cli|monorepo|…" },  "stack": { "language": "", "framework": "", "database": "", "auth": "" },  "architecture": { "entry_points": [], "auth": "", "integrations": [] },  "likely_touch": [    { "path": "src/middleware/auth.ts", "why": "…", "role": "write", "score": 0 }  ],  "run": { "dev": "", "test": "", "build": "" },  "plan": ["Open … first", "Next, review …"],  "honesty": null,  "confidence": 0.95,  "next_commands": ["zephex get-context --topic auth", "…"],  "meta": {    "ms": 0,    "tools_ok": ["context", "architecture"],    "intent_kind": "auth",    "local_only": true,    "credits_estimated": 0  }}

vs other commands

Need	Use
Quick product story	`overview`
One topic only (auth, database, …)	`get-context --topic …`
Wiring map only	`architecture`
Search only	`find` / `find-code`
Everything to start working	`deep`
Agent packet	`deep --json`
Run tests	check-test

Any local project

Not monorepo-locked

Search and ranking are project-universal: Python app/views.py, Go internal/, Flutter lib/, monorepos with apps/web — not only TypeScript under src/. Noise filters drop node_modules, dist, lockfiles, and deprecated trees. Intent extras use domain language (oauth, stripe, migration) — not one repo's filenames.

Tips & honesty

Be specific when you can: page name, provider, feature word (profile, stripe, oauth).
If the dossier says the package is API-only for a UI task, re-run with --cwd on the frontend package (or follow the honesty hint).
Paths are never invented — empty touch list means tighten keywords or find.
Vague goals (community, websocket, encrypted DMs when the feature does not exist) stay best-effort — confidence can look high but the top file may be soft.
Unset dead MCP overrides if tools flake: unset ZEPHEX_MCP_URL ZEPHEX_MCP_URL_ALLOW_OVERRIDE — production MCP is https://zephex.dev/mcp.
Agents: run deep --json before broad native Read/Grep exploration.

Troubleshooting

`deep` runs the wrong command (e.g. package check)

Registry npx zephex may lag behind. Use a current global install or the built local binary while publishing catches up.

Empty or weak WHERE TO LOOK

Ensure rg (ripgrep) is installed for local search
Pass --force after big refactors
Try a tighter task phrase or --cwd into the right package

Hosted find failed in the footer

Common on private local trees. Local disk search still builds the touch list — that is expected and intentional.

Installation

zephex deep — Project Dossier

One command on your local project: stack, how pieces connect, and ranked files for your task — so humans and AI agents stop flailing with random greps.

START HERE

cd your-appmcpcli deepmcpcli deep "auth middleware"mcpcli deep "add a settings button on the profile page"mcpcli deep "stripe billing usage" --json # Same binary after global installmcpcli deep   # same: zephex deep# Aliases: dossier · know · full-brief · project-deep# Slash palette: /deep

Needs a logged-in CLI key ( CLI account). Prefer a current local build or npm install -g zephex after publish — older registry bins may not map deep correctly.

What it is

One sentence

Product name

Project Dossier

Command: deep. Not a new MCP gallery tool. Not a full-repo dump. Local-first — cd into any app and run it.

With a task

Where to look first

Free text like auth middleware, settings button on profile, or stripe billing changes ranking and tool focus so the touch list matches the job.

Without a task

Full orientation

Product story, stack, run scripts, structure, architecture hubs — a richer start than a thin map.

What it is not

Not a replacement for Claude Code / Cursor — it feeds agents and humans so they start editing sooner
Not a Repomix-style dump of every file (token bomb)
Not a new MCP tool in the gallery (v1 is CLI-only orchestration)
Not a substitute for Test Pulse or Supply Pulse — different jobs

Install

Get the CLI

CURL INSTALLER

curl installer — terminal CLI (Mode 2)

curl -fsSL https://zephex.dev/cli/install.sh | bash

Same script lives at both URLs (use either):

curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash

What it does

Installs into ~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.
If your system Node is missing or older than 22.5, it downloads a private Node 22 runtime (~50 MB compressed, once) under ~/.zephex/node.
Downloads the zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).
Starts zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).

By operating system

source ~/.zephex/env.sh

Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:

irm https://zephex.dev/install.ps1 | iex

WSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.

Cloud shells, phones, other OS

Google Cloud Shell, GitHub Codespaces, Railway / Render shells — use the same curl line. Those boxes often ship Node 18 or 20. The installer notices and downloads a private Node 22 under ~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.
Android (Termux) — curl + bash work. Same installer. Hosted commands still need HTTPS out to zephex.dev.
iPhone / iPad — there is no native zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.
Windows ARM (Surface, Snapdragon) — PowerShell installer downloads the win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.

What the CLI talks to

Install download — Vercel serves install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.
Sign-in — browser or QR hits zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600).
Tool commands (/overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.
Sentry — Railway captures hosted tool / API errors (tagged with CLI version). The local zephex process does not send your repo to Sentry.

After install — first commands

source ~/.zephex/env.shcd your-appzephex# type /overview   or   /help

Hosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.

Upgrade

The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:

zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bash

Check what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.

This vs the homepage npx line

curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.
npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.
You can use both with one API key. Install the CLI first, then zephex connect --cursor when you want the editor.

Uninstall

zephex uninstall           # PATH + credentialszephex uninstall --full    # delete entire ~/.zephex

If something looks stuck

command not found: zephex — source ~/.zephex/env.sh, then open a new tab.
Piped curl into bash: the installer cannot keep PATH in that parent shell. That is why it prints the source line.
Only run the script from zephex.dev— never a random gist.
Offline or corporate TLS intercept: the script needs HTTPS to zephex.dev (npm package) and, if Node is missing, nodejs.org.

More paths: all install methods · macOS · Linux · Windows · terminal CLI

Node.js required (or alternatives)

Includes best download path and how many MB each option uses — see download sizes.

BEST DOWNLOAD · HOW MANY MB?

# Best download — no Node required (~3 MB CLI; +~50 MB Node only if missing)curl -fsSL https://zephex.dev/cli/install.sh | bash # Already have Node 22.5+ and want editor MCP only:npx -y zephex@latest setup --cursor # Avoid until slim publish: npm install -g zephex / bare npx zephex# Those currently also install unused server libraries (~260 MB).

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`)	~3 MB	~260 MB in npm cache
npx zephex setup (no global install)	Same ~3 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

Step 1 — check what you already have:

node -vnpm -vwhich nodewhich npm

v18.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 22+.

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.

INSTALL NODE.JS (MAC · WINDOWS · LINUX)

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 --lts

Step 3 — after Node works, run Zephex setup:

npm install -g zephex && mcpcli setup

Without global install (still needs Node + npm for npx):

npx zephex setupnpx -p zephex mcpcli setup

BUN & PNPM (ALTERNATIVE RUNTIMES)

These 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 setup

pnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setup

No 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-context

Optional 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-context

Full CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.

EDITOR ONLY — NO LOCAL NODE

# 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

TROUBLESHOOTING

# "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 22.5+ — or use curl install.sh, which bundles Node.

FAQ

Question	Answer
Do I need Node.js to use Zephex at all?	Not for the curl installer — it bundles Node 22 under ~/.zephex if needed. npx / npm / bun still need Node 22.5+ on PATH. Editor MCP over HTTPS can work with only an API key.
What is the best install for a new user?	curl -fsSL https://zephex.dev/cli/install.sh \| bash — then source ~/.zephex/env.sh. That works with or without Node. Use npx zephex setup --cursor only when you already have Node 22.5+ and want editor MCP.
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 v22.5 or higher. Below that, use the curl installer — it downloads a private Node 22 instead of failing.
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?	curl installer: ~3 MB CLI tarball, plus ~50 MB Node only if you are below 22.5. npm install -g zephex / npx zephex currently also pull unused server libraries (~260 MB, ~2 minutes) until the slim package is published. Docker is a ~50 MB Node image plus that same npm package.
What is the best way to download if I have nothing installed?	curl -fsSL https://zephex.dev/cli/install.sh \| bash. If you cannot run curl\|bash, use editor-only MCP (paste a key into Cursor) or the web terminal. Do not start with npm install -g until the slim package is on npm.

More: Install methods (all 6) · Connect MCP · CLI in Docker · npx zephex

First time (any OS, Node already installed)

Pick one path — both work the first time you run setup:

Recommended — global install (shortest commands forever):

npm install -g zephex && mcpcli setup

One-shot without global install (pick one):

npx zephex setupnpx -p zephex mcpcli setup

Plain mcpcli setup only works after npm install -g zephex (or the combined line above). That is expected — there is no separate npm package named mcpcli on the public registry.

After install — daily commands

mcpcli setupmcpcli get-contextmcpcli usagezepx helpzphx doctor

All of these run the same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, zephex.

Terminal-only vs editor MCP

Who can run it?

Connect MCP (editors) · Terminal tools · Full command list · Install & package names · Install methods (no Node / Docker / manual) · CLI in Docker

Confirm the command exists:

mcpcli deep --help# Expect: full project intelligence dossier · aliases dossier/know/full-brief

Commands

Everyday usage

# Full local orientationmcpcli deep # Task-focused (this is the main product)mcpcli deep "auth middleware"mcpcli deep "add rate limiting on API"mcpcli deep "stripe billing usage"mcpcli deep "add a settings button on the profile page"mcpcli deep "new CLI command" # Agent / machine packetmcpcli deep "auth middleware" --jsonmcpcli deep "auth middleware" --json -o .zephex/deep.json # Expand / cachemcpcli deep --fullmcpcli deep --more stackmcpcli deep --more touchmcpcli deep --force                    # bypass ~30m cache # Another package in a monorepomcpcli deep --cwd dashboard "profile settings UI" # Optional public remote (secondary)mcpcli deep github:owner/repomcpcli deep github:owner/repo "add auth"

Aliases

dossier, know, full-brief, project-deep — same command. Interactive slash palette: /deep, /dossier.

Flags

Flag	What it does
`--json`	Stable `schema_version: 1` JSON for agents (no pretty human card)
`--full`	Deeper architecture, fuller context, more touch files
`--more <section>`	Expand one chapter: `story` · `stack` · `touch` · `architecture` · `all`
`--force` / `-f`	Bypass local deep cache under `.zephex/`
`--cwd <dir>`	Analyze that directory (monorepo package)
`--path` / remote	Explicit path or `github:owner/repo`

How it works

Pipeline (inside one command)

Resolve local project root (and monorepo package if needed)
Classify the task string (auth, frontend, billing, CLI, jobs, …) — no LLM
Run in parallel (partial results if one times out):
- get_project_context — stack, scripts, structure
- explain_architecture — wiring + task concern
- find_code — hosted search (limited by upload)
Local disk ripgrep — required for real private repos (hosted find only sees a small inline_files subset)
Rank likely_touch — real paths only, never invented
Render human dossier or --json

Tools deep reuses (specialties)

Tool	Specialty in deep
`get_project_context`	Stack, scripts, monorepo shape, topic slices
`explain_architecture`	Entry points, auth, integrations, concern cluster
`find_code`	Hosted keyword search (best-effort on local private trees)
Local `rg`	Primary touch-list source on disk — multi-language, no monorepo allowlist

Credits are billed as the underlying tool calls (context + architecture + find). The footer shows tools used, time, confidence, and estimated credits.

Task mode

Free-text tasks (any project)

Pass any goal as a string. Intent routing picks context topics and find queries. Ranking prefers basename / path-segment matches so auth.ts beats a random index.ts.

Example task	Intent bias
`auth middleware` · `OAuth login`	Auth & access
`settings button on profile`	UI / frontend (may suggest `--cwd` for app packages)
`stripe billing usage` · `payment webhook`	Billing & usage
`rate limiting` · `API proxy`	API / backend
`database schema migration`	Data — prefers real `migrations/` trees
`new CLI command`	CLI / commands
`background job queue`	Jobs & workers (not UI Background components)

Human output shape (with task)

TASK — ordered steps (open this file first, then that one)
IMPORTANT — honesty when the package does not match the task (e.g. UI on a backend-only tree)
WHERE TO LOOK — ranked real paths with short why
Focus section (AUTH & ACCESS, UI / FRONTEND, BILLING, …)
Compact STACK + HOW YOU RUN IT (context, not the main product)
NEXT / DIG DEEPER — get-context topic, architecture, find, test

JSON for agents

`--json` contract

Same run, machine-readable. Agents should open likely_touch[0..2], read plan, respect honesty, and treat stack/run as context only.

{  "schema_version": 1,  "project_root": "/abs/path",  "task": "auth middleware",  "product": { "name": "", "summary": "", "kind": "web|cli|monorepo|…" },  "stack": { "language": "", "framework": "", "database": "", "auth": "" },  "architecture": { "entry_points": [], "auth": "", "integrations": [] },  "likely_touch": [    { "path": "src/middleware/auth.ts", "why": "…", "role": "write", "score": 0 }  ],  "run": { "dev": "", "test": "", "build": "" },  "plan": ["Open … first", "Next, review …"],  "honesty": null,  "confidence": 0.95,  "next_commands": ["zephex get-context --topic auth", "…"],  "meta": {    "ms": 0,    "tools_ok": ["context", "architecture"],    "intent_kind": "auth",    "local_only": true,    "credits_estimated": 0  }}

vs other commands

Need	Use
Quick product story	`overview`
One topic only (auth, database, …)	`get-context --topic …`
Wiring map only	`architecture`
Search only	`find` / `find-code`
Everything to start working	`deep`
Agent packet	`deep --json`
Run tests	check-test

Any local project

Not monorepo-locked

Tips & honesty

Be specific when you can: page name, provider, feature word (profile, stripe, oauth).
If the dossier says the package is API-only for a UI task, re-run with --cwd on the frontend package (or follow the honesty hint).
Paths are never invented — empty touch list means tighten keywords or find.
Vague goals (community, websocket, encrypted DMs when the feature does not exist) stay best-effort — confidence can look high but the top file may be soft.
Unset dead MCP overrides if tools flake: unset ZEPHEX_MCP_URL ZEPHEX_MCP_URL_ALLOW_OVERRIDE — production MCP is https://zephex.dev/mcp.
Agents: run deep --json before broad native Read/Grep exploration.

Troubleshooting

`deep` runs the wrong command (e.g. package check)

Registry npx zephex may lag behind. Use a current global install or the built local binary while publishing catches up.

Empty or weak WHERE TO LOOK

Ensure rg (ripgrep) is installed for local search
Pass --force after big refactors
Try a tighter task phrase or --cwd into the right package

Hosted find failed in the footer

Common on private local trees. Local disk search still builds the touch list — that is expected and intentional.

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

zephex deep — Project Dossier

One sentence

What it is not

Get the CLI

curl installer — terminal CLI (Mode 2)

What it does

By operating system

Cloud shells, phones, other OS

What the CLI talks to

After install — first commands

Upgrade

This vs the homepage npx line

Uninstall

If something looks stuck

Node.js required (or alternatives)

First time (any OS, Node already installed)

After install — daily commands

Terminal-only vs editor MCP

Who can run it?

More

Everyday usage

Aliases

Pipeline (inside one command)

Tools deep reuses (specialties)

Free-text tasks (any project)

Human output shape (with task)

--json contract

Not monorepo-locked

deep runs the wrong command (e.g. package check)

Empty or weak WHERE TO LOOK

Hosted find failed in the footer

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

zephex deep — Project Dossier

One sentence

What it is not

Get the CLI

curl installer — terminal CLI (Mode 2)

What it does

By operating system

Cloud shells, phones, other OS

What the CLI talks to

After install — first commands

Upgrade

This vs the homepage npx line

Uninstall

If something looks stuck

Node.js required (or alternatives)

First time (any OS, Node already installed)

After install — daily commands

Terminal-only vs editor MCP

Who can run it?

More

Everyday usage

Aliases

Pipeline (inside one command)

Tools deep reuses (specialties)

Free-text tasks (any project)

Human output shape (with task)

--json contract

Not monorepo-locked

deep runs the wrong command (e.g. package check)

Empty or weak WHERE TO LOOK

Hosted find failed in the footer

`--json` contract

`deep` runs the wrong command (e.g. package check)

`--json` contract

`deep` runs the wrong command (e.g. package check)