Installation
Terminal tools (Mode 2)
Same hosted MCP as your editor — answers in plain English in the shell. All 10 MCP tools have terminal commands; 10 tools total. Local folder by default; answer cards, not chat dumps.
Tip: Run mcpcli setup or mcpcli init once — it saves ~/.zephex/credentials.json so terminal tools work even before you connect an editor. Then cd into a project and run mcpcli overview.
Both hit https://zephex.dev/mcp with the same API key. CLI returns human-readable output you can pipe or paste; MCP tools run inside your editor agent loop.
| Scenario | Terminal CLI | Editor MCP tool | Pick |
|---|---|---|---|
| You want a project brief before coding | mcpcli get-context | Ask agent: get_project_context | Either — CLI for copy-paste; MCP when agent is already in chat |
| Search repo for a symbol or string | mcpcli find-code "auth" | Ask agent: find_code | CLI for quick grep; MCP when agent should act on results |
| Outline a file before editing | mcpcli outline src/auth.ts | Ask agent: read_code | CLI — human-readable, no agent loop |
| Check if an npm package is safe | mcpcli safe express | Ask agent: check_package | Either — no project folder required |
| Audit live HTTP headers / TLS | mcpcli check url https://localhost:3000 --deep | audit_headers | CLI or MCP — needs a reachable URL (dev server or production) |
| Multi-turn investigation session | mcpcli think "debug 401" (one-shot) | keep_thinking with sessionId | MCP for persistent sessions; CLI for quick reasoning |
| Connect a new editor | mcpcli setup --cursor | N/A — setup is CLI-only | CLI |
| Diagnose broken MCP connection | mcpcli doctor · mcpcli repair · mcpcli list | Ask agent: tools/list | CLI — doctor checks Node, network, and config files |
Common mistake: Running terminal tools from ~ or /tmp — Zephex needs a project folder with package.json + source files. cd into your app first, or use --cwd apps/web in monorepos.
Zephex CLI is a terminal product that talks to the same hosted intelligence as your editor MCP — but answers in plain English for humans. You install once, sign in once, then run short commands from any project folder: stack brief, find a symbol, outline a file, check if a package is safe, run tests, or audit a live URL. No agent loop required.
What a good Mode 2 reply looks like: short hero, plain English, · tags, │ sections, numbered Dig deeper — not a wall of chat.
The craft: answer cards, not chat dumps
Mode 2 is designed like a senior engineer sitting next to you — not like a chat model monologue. Each successful tool prints a structured answer card:
Hero first
Project name, package name, or search query in high contrast — so you know what you’re looking at in half a second.
Plain English story
Two to four sentences on what it is and how you’d use it. Badges and marketing noise are stripped before display.
· tags + │ rails
Stack, license, and scale as a quiet tag strip. Sections use a left rail so your eye can scan What this is / What it does / Getting started.
Dig deeper
Numbered next commands (architecture, find-code, setup…) so you never dead-end after one answer.
Honesty
If a section has no real data, it is dropped — Zephex does not invent stack or print “none detected” filler.
Human ≠ agent
Default output is the card. Pass --json when you want the same lean payload your editor agent sees.
| Who | When | Try |
|---|---|---|
| Solo builders | Before opening the editor — orient on a new clone in under a minute. | mcpcli overview |
| Teams onboarding | Hand a new hire five commands instead of a 40-page wiki. | mcpcli get-context · mcpcli architecture |
| Security-minded deploys | Before npm install, or after shipping a public URL. | mcpcli safe express · mcpcli check url https://your.app |
| Monorepo maintainers | Point tools at one package without losing the root workspace. | mcpcli find-code "auth" --cwd apps/web |
| CI / scripts | Pipe machine-readable results into bots or logs. | mcpcli get-context --json · mcpcli deps --json |
| Editor users who also live in the shell | Same API key as Cursor / Claude — terminal for speed, MCP for multi-step agent work. | mcpcli setup --cursor then mcpcli find-code "…" |
# 1) Install once (Mac, Linux, Windows)npm install -g zephex # 2) Sign in (browser → saves ~/.zephex/credentials.json)mcpcli init# or: mcpcli setup --terminal # 3) Stand in a real project (package.json + source)cd ~/projects/my-app # 4) First answers — plain English cardsmcpcli overviewmcpcli get-contextmcpcli find-code "auth"mcpcli safe expressmcpcli check-test # 5) Optional: wire an editor toomcpcli connect --cursor # 6) Healthmcpcli doctormcpcli usageLearn these ten first. Everything else is aliases, Power Mode, or Pulse product lines.
| Command | What you get |
|---|---|
overview | Product story + stack bars + how to run |
get-context | Structured project brief (topics: auth, database, …) |
find-code | Search symbols, strings, renames |
summarize | Plain-English file read (read_code) |
check-test | Run tests + failures / why |
safe | Is this npm package safe to install? |
architecture | How the app is wired |
check url | Live URL header / TLS audit |
remember | Save a project fact for later sessions |
connect | Wire Cursor / VS Code / Claude / 22+ editors |
New repo clone — “what is this?”
- cd into the app (or apps/web in a monorepo)
- mcpcli overview — product story, size, how to run
- mcpcli get-context — stack, scripts, env names
- mcpcli architecture — how modules wire together
cd my-appmcpcli overviewmcpcli get-contextmcpcli architecture --focus authFind a symbol, then read it
- mcpcli find-code "validateToken" — ranked hits
- mcpcli symbol validateToken — AST body
- mcpcli summarize src/lib/auth.ts — plain-English file brief
mcpcli find-code "validateToken"mcpcli symbol validateTokenmcpcli summarize src/lib/auth.tsBefore you npm install
- mcpcli safe <pkg> — CVEs + registry risk (no project required)
- mcpcli check-package next --task upgrade --from-version 14.2.0
- mcpcli deps — scan every direct dependency in package.json
mcpcli safe lodashmcpcli check-package next --task upgrade --from-version 14.2.0mcpcli depsBefore you ship
- mcpcli check-test — run suite + failure clusters
- mcpcli check url https://staging.example.com — headers, TLS, secrets surface
- mcpcli supply https://staging.example.com — Supply Pulse on the live site
mcpcli check-testmcpcli check url https://staging.example.commcpcli supply https://staging.example.comRemember decisions across sessions
- mcpcli remember "auth uses Supabase JWT in cookies"
- mcpcli recall auth — search saved facts
- mcpcli memory list — recent titles
mcpcli remember "rate limit is Upstash sliding window per API key"mcpcli recall rate limitmcpcli memory listSTEP 1
You type a short command (or plain English)
Intent routing maps typos and phrases to the right tool — no LLM in the loop for routing. Example: mcpcli "tell me about my project" → get-context.
STEP 2
Local project is indexed from your disk
By default Zephex uploads manifests + a bounded file set (inline_files) from your current folder — private repos work without a public GitHub URL.
STEP 3
Hosted tools analyze at zephex.dev/mcp
Same API key as editor MCP. Usage counts toward your plan. Failures on empty folders fail fast so you do not burn quota from ~.
STEP 4
Terminal renders an answer card
Hero, plain English, tags, sections, Dig deeper. --json skips the card and prints the agent payload.
On a TTY, bare mcpcli opens a shell. Type / for the palette — Tab fills, Enter runs.
mcpcli # bare + TTY → interactive shell, type //overview # slash palette (Tab to fill, Enter to run)/find auth/safe express/login # if not signed inmcpcli help terminal # full Mode 2 alias listmcpcli learn find_code # per-tool guide, no API call| Mistake | Fix |
|---|---|
| Running from ~ or /tmp | cd into a folder with package.json (or pyproject.toml / go.mod) first. |
| Expecting full monorepo search from the root always | Use mcpcli … --cwd packages/api or cd into the package you care about. |
| Confusing remember with package upgrade | remember/recall = project_memory facts. Package upgrades = mcpcli check-package --task upgrade (legacy: loop-guard). |
| Assuming multi-turn think works like the editor | Terminal mcpcli think is one-shot. Full keep_thinking sessions with sessionId are editor MCP. |
| Using an old global binary | mcpcli update --apply or npm install -g zephex@latest — then mcpcli doctor. |
No AI agent in the loop. Your shell runs npx zephex; the CLI uploads a search index from disk (inline_files) and calls the same hosted endpoint as your editor.
Terminal CLI needs Node.js 18+ (or Docker). Check with node -v. No Node? start from zero (MB + steps) · 6 install methods
Short commands: after npm install -g zephex, use mcpcli setup (same as npx zephex setup). Requires Node.js 18+ — no Node? see options. Same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, or zephex (after npm i -g zephex).
npm install -g zephex && mcpcli setupcd your-appmcpcli overviewmcpcli get-contextmcpcli find-code "auth middleware"mcpcli summarize src/index.tsmcpcli architecturemcpcli check-testmcpcli safe expressYou should see an answer card (hero name, · tags, │ sections) and often Using local project (N files from …) — not a bare git remote URL. If tools fail with Using Git remote, update: npm install -g zephex@latest.
npx zephex cli-guidenpx zephex cli-guide quickstartnpx zephex cli-guide monoreponpx zephex help terminalUnknown subcommand? See Command Compass.
npx zephex learnnpx zephex learn find_codenpx zephex find-code toolsOption A — cd into app
cd mcp-proxy && mcpcli find-code "query"Option B — --cwd from root
mcpcli find-code "query" --cwd mcp-proxymcpcli outline mcp-proxy/src/cli.tsDEFAULT
Uploads an index from the folder on your machine. Private code never leaves unless you run the tool.
REMOTE
mcpcli get-context github:owner/repo or --path github:owner/repo
FORCE REMOTE
--no-local — requires repo access on your Zephex account
mcpcli safe expressmcpcli check-package next --task upgrade --from-version 14.2.0mcpcli check-package --from-lock --strict --jsonSee check_package and complete packages section.
| Command | MCP tool |
|---|---|
get-context | get_project_context |
find-code | find_code |
summarize / outline / symbol | read_code |
architecture | explain_architecture |
check-test | check_test |
think | keep_thinking |
check-package | check_package |
remember / recall / memory | project_memory |
check url | audit_headers |
docs | Zephex_dev_info |
keep_thinking (multi-turn)
Terminal has one-shot think/reason/debug-think; sessionId checkpoint flows are editor-only.
--json Raw MCP JSON--cwd <dir> Project / package root--no-local Use git remote instead of local upload--path github:o/r Explicit remote repo--api-key Override saved key