Was this page helpful?
Installation
The most important way to use Zephex: run hosted MCP tools directly in your terminal. Same API as Cursor or Claude Code, but you get human-readable briefs — no chat UI, no agent loop. Your code stays on disk; the CLI uploads a search index (inline_files), not your whole git remote, unless you ask for remote.
Full command guide (new): Terminal tools complete guide — every alias for get-context (50+), find-code (31), read-code (31), architecture (9), with copy-paste examples for search and onboarding.
# 1. Sign in once (browser) — saves ~/.zephex/credentials.jsonnpx zephex setup # 2. cd into your app (package.json + src or app/)cd ~/projects/my-app # 3. Prove local indexing (you MUST see this line):npx zephex get-context# → Using local project (N files from …) # 4. Run tools — human output, no editornpx zephex frameworknpx zephex find-code "validateToken"npx zephex outline src/lib/auth.tsnpx zephex scope-task "add Stripe webhooks"npx zephex safe express # Scripts / CInpx zephex get-context --json | jq '.framework'Empty menu: npx zephex · Full screen: npx zephex help terminal · Built-in guide: npx zephex cli-guide
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.
From project research (see mcp-proxy/summary.md and docs/CLI-MODE2-COMPLETE-GUIDE.md): three principles apply.
https://zephex.dev/mcp.--path github:o/r.audit_headers stays editor-only (needs a live HTTP URL).| Category | Count | Where documented |
|---|---|---|
| Account & meta (setup, logout, doctor, help, …) | 16 | CLI commands · Account & logout |
| Terminal MCP tools (hosted) | 9 + 1 editor-only | This page · Terminal reference |
| find_code aliases alone | 31 | npx zephex find-code --help |
| read_code aliases | 31 | npx zephex read-code --help |
| get_project_context topics + typos | 50+ | npx zephex cli-guide project |
| Natural language (quoted phrase) | unlimited routing | npx zephex "find auth middleware" |
| MCP tool | Primary CLI | Aliases | Example | Needs project folder? |
|---|---|---|---|---|
get_project_context | get-context | 50+: context, ., stack, framework, database, backend, frontend, auth, quick, … | npx zephex get-context | Yes |
find_code | find-code | 31: find, search, grep, rename, everywhere, usages, defs, where, … | npx zephex find-code "auth middleware" | Yes |
read_code | summarize / outline / symbol | 31: read-code, read, explain, show, files, peek, … | npx zephex outline src/lib/auth.ts | Yes |
explain_architecture | architecture | 6+: arch, explain-architecture, structure | npx zephex architecture --focus auth | Yes |
scope_task | scope-task | 9: scope, plan, files-for, touch | npx zephex scope-task "add Stripe webhooks" | Yes |
keep_thinking | think | 3: reason, debug-think (one-shot in terminal) | npx zephex think "debug 401 after refresh" | No |
check_package | check-package | 13: check, safe, lookup, pkg, package | npx zephex safe express | No |
audit_package | audit-package | 9: audit, upgrade (with pkg), migrate | npx zephex audit-package next --from-version 14 | No |
Zephex_dev_info | docs | 2: ask | npx zephex docs "Stripe webhooks" | No |
Editor-only (still part of the same MCP server after setup):
audit_headers — HTTP/TLS header audit on a live URL — requires a running dev server; use in Cursor/Claude after setup.keep_thinking (multi-turn) — Terminal has one-shot think/reason/debug-think; sessionId flows are editor-only.| Command | Aliases | What it does |
|---|---|---|
setup | login, sign-in | Browser OAuth → API key → editor MCP config + ~/.zephex |
logout | sign-out | Delete ~/.zephex only; editors unchanged |
disconnect | remove | Remove Zephex from editor JSON; revoke key server-side |
reconnect | — | disconnect --quiet + fresh setup |
reset | — | disconnect + remove skill/rule files |
status | — | Live MCP tools/list per installed editor config |
list | ls | Every supported editor — installed or not |
doctor | — | Node, network, MCP reachability, project index, API key |
keys | — | Masked keys + usage; links to dashboard |
usage | stats | Per-tool call counts this billing month |
tools | — | List / enable / disable MCP tools in editor config |
skills | — | Install or upgrade agent skill + rule markdown |
info | version, -v | Package version and install path |
help | -h, --help | Full reference; topics: terminal, tools, setup |
cli-guide | guide, howto | Mode 2 deep guide (topics: project, auth, monorepo, …) |
update | upgrade (no args) | How to npm install -g zephex@latest |
Connect / disconnect testing: CLI account & logout · Connect MCP
| Run | You get |
|---|---|
npx zephex help | Editors + account + terminal overview |
npx zephex help terminal | Every Mode 2 alias on one screen |
npx zephex help tools | All 10 MCP tools — editor vs terminal |
npx zephex help setup | Editor flags, --project vs --global |
npx zephex cli-guide | Mode 2 guide index |
npx zephex cli-guide project | Scenarios A–H (where am I searching?) |
npx zephex cli-guide account | logout vs disconnect lifecycle |
npx zephex find-code --help | Per-tool flags for find_code |
This table matches npx zephex cli-guide project and the engineering handoff in handoff/cli-mode2/.
| # | Situation | Expected |
|---|---|---|
| A | Terminal in app folder (package.json + src/) | Using local project (N files from …) |
| B | Monorepo root (thin workspace package.json) | Auto-pick busiest package; (monorepo) in label |
| C | Private repo on disk | Local inline_files only — no public GitHub required |
| D | Public OSS without clone | get-context github:owner/repo or --path on find/read |
| E | ~, /tmp, or empty folder | No project here — fail fast, do not burn quota |
| F | No API key | Run setup or set ZEPHEX_API_KEY |
| G | File path while cwd is wrong | Error names project root; use cd or --cwd |
| H | check-package / audit-package | Works with no project folder |
# Recommended chain before editing unfamiliar codecd your-appnpx zephex get-context # stack, scripts, layoutnpx zephex find-code "AuthService" # where things livenpx zephex outline src/auth.ts # file TOCnpx zephex scope-task "add OAuth" # which files to touchnpx zephex architecture --focus auth# Command quirks (from cli-intent-router — no LLM)npx zephex summary # → project quick brief (get-context)npx zephex summary src/foo.ts # → file outline (read_code)npx zephex explain # → architecture mapnpx zephex explain src/foo.ts # → file summarynpx zephex upgrade react # → audit-package (not self-update)npx zephex update # → how to npm install -g zephex@latest--json Raw MCP JSON (CI / agent parity)--cwd <dir> Project or package root (monorepos)--no-local Use git remote instead of folder upload--path github:o/r Explicit remote repo--api-key mcp_… Override ~/.zephex / ZEPHEX_API_KEY-q, --quiet Less stderr--force Refresh get-context cache only# Copy-paste test flow (no AI agent)npx zephex setupnpx zephex doctorcd your-app # folder with package.json + srcnpx zephex get-contextnpx zephex find-code "test"npx zephex safe lodashnpx zephex logoutnpx zephex setup # sign in againIf find-code prints Using Git remote then errors, update the CLI — 2.4+ defaults to local upload. From this repo: cd mcp-proxy && bun run build && npx . find-code "test"