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.
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: /deepNeeds 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.
Related: CLI without an agent · CLI commands · get_project_context · explain_architecture · find_code
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
Get the 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 18+ 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.
Recommended if you have nothing installed yet: official Node.js LTS from nodejs.org (one installer), then the Zephex CLI from npm. Total download is not huge — on the order of tens of MB for Node, plus about 2.4 MB for the CLI itself.
# Best download for most people (small + permanent):# 1) Node.js LTS installer — ~30 MB (Windows) or ~85 MB (macOS) one-time download# https://nodejs.org/en/download# 2) Then in terminal (Zephex CLI is only ~2–3 MB from npm):npm install -g zephexmcpcli setup # Smallest try-before-install (still needs Node for npx):npx zephex setup# First run downloads zephex (~2–3 MB) to npm cache; no huge SDK.| 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) | ~2.4 MB | ~3–20 MB in npm cache |
| npx zephex setup (no global install) | Same ~2.4 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 npmv18.x,v20.x, orv22.x→ you are ready; skip to after Node is installed.command not found→ Node is missing; install below or use Docker / editor-only.v16or lower → upgrade Node; the CLI requires 18+.
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. |
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 --ltsStep 3 — after Node works, run Zephex setup:
npm install -g zephex && mcpcli setupWithout global install (still needs Node + npm for npx):
npx zephex setupnpx -p zephex mcpcli setupThese 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 setuppnpm add -g zephexmcpcli setup# or one-shot:pnpm dlx zephex mcpcli setupNo 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-contextOptional 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-contextFull CLI in Docker guide · Windows paths: use %USERPROFILE% instead of $HOME in -v mounts.
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# "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 18+ LTS — zephex CLI will not run on EOL Node.| Question | Answer |
|---|---|
| Do I need Node.js to use Zephex at all? | Only for the terminal CLI (mcpcli / npx zephex). Editor MCP via hosted HTTPS (Cursor, Claude Code) can work without Node on your laptop if you paste an API key or HTTP config. Terminal tools always need Node somewhere — your machine or Docker. |
| What is the best install for a new user? | Install Node.js LTS from nodejs.org (includes npm), restart the terminal, then run: npm install -g zephex && mcpcli setup. That gives the shortest commands forever. |
| 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 v18 or higher. You do not need a separate Node install for Zephex. Use the same npm/npx. |
| 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? | Node.js LTS installer is roughly 30 MB (Windows) or 85 MB (macOS) — not hundreds of MB. The zephex CLI package from npm is about 2–3 MB. npx zephex setup only adds that CLI download on first run (cached after). Docker pulls a ~50 MB Node Alpine image plus the same small zephex package inside the container. |
| What is the best way to download if I have nothing installed? | Use the official Node.js LTS installer from nodejs.org (includes npm), restart your terminal, then run npm install -g zephex && mcpcli setup. That is the smallest hassle long-term. If you truly cannot install Node, use editor-only MCP (no download) or Docker if your IT allows it. |
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 setupOne-shot without global install (pick one):
npx zephex setupnpx -p zephex mcpcli setupPlain 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 doctorAll 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.
More
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-briefEveryday 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.
| 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 |
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_filessubset) - 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.
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 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 }}| 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 |
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.
- 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
--cwdon 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 ishttps://zephex.dev/mcp. - Agents: run
deep --jsonbefore broad native Read/Grep exploration.
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
--forceafter big refactors - Try a tighter task phrase or
--cwdinto 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.