Installation
Command Compass
You don't need to memorize every mcpcli subcommand. Typo something, type a question as a command, or run nonsense input — Zephex shows a short guide with copy-paste commands that work. Same visual style as learn. Local only: no MCP calls and no LLM for routing.
Related: Terminal CLI · Full command reference · CLI without an AI agent · First-run init
After npm install -g zephex, every bin runs the same CLI: mcpcli · zephex · zepx · zphx · mcpz · zepcli · zephx
The problem Command Compass solves
Before Compass, an unknown command often dumped setup boilerplate to stderr — hard to read, nothing you could copy and run. New users would type questions like where is my database and get the wrong tool, or typo learbn and hit a dead end.
Command Compass replaces that with:
- One best command— "Try this first" with a one-line explanation
- Two alternates— "Also works" when another tool fits
- Learn link — always points to the full tool index
- TTY menu — pick 1, 2, or 3 and Zephex runs it for you
Examples always use your active bin — mcpcli, zephex, or npx zephex — never a hardcoded string that does not match how you installed.
Example: typo
◇ Command compass › not sure what you meant You typed: "learbn" Did you mean: learn │ Try this first Shows all terminal tools · mcpcli learn │ Also works · mcpcli cli-guide · mcpcli help │ See all tools · mcpcli learn Pick a number to run (TTY) or copy a command above.Example: nothing matches
When Compass has low confidence, it still gives you three sensible starters plus learn — not an empty error.
◇ Command compass › not sure what you meant You typed: "totally-unknown-cmd-xyz" │ Try this first · mcpcli ask "totally unknown cmd xyz" │ Also works · mcpcli get-context · mcpcli find-code │ See all tools · mcpcli learnExample: phrase routes directly
Strong matches often skip the compass page entirely. The intent router runs the best command before you see a guide — same outcome, fewer steps.
# High-confidence phrase — often no compass screen at all:$ mcpcli where is my databaseUsing local project (142 files from …)… database context brief …Real scenarios
Five situations you will actually hit in the terminal:
| Scenario | You type | What happens | Tip |
|---|---|---|---|
| New user typos learn | mcpcli learbn | Compass suggests mcpcli learn + cli-guide; TTY lets you pick 1 to run it | Same as mcpcli commands — terminal tool index, not editor MCP tools toggle |
| Question typed as a command | mcpcli where is my database | Often routes straight to get-context database (no compass screen) | If unsure, run mcpcli compass "where is my database" to see all options first |
| Package upgrade typo | mcpcli upgrde react | Compass or intent router → mcpcli upgrade react | Add --run-suggestion on compass to auto-run high-confidence picks |
| Random keyboard mash | mcpcli asdfghjkl | Compass with ask fallback — not a bogus npm package lookup | Short real package names like react still go to check-package by design |
| Wrong learn topic | mcpcli learn supabase-magic | Compass page instead of Unknown tool stderr | Then try mcpcli learn get_project_context or mcpcli get-context database |
| Natural-language package safety | mcpcli is lodash safe | Compass or router → mcpcli check-package lodash | Package name is extracted from is … safe and check … patterns |
| Topic typo without compass | mcpcli databse | Spellcheck → get-context database (may skip compass screen) | Topic typos on context commands often auto-correct before dispatch |
| Empty compass subcommand | mcpcli compass | Full learn index — useful when you forgot the tool name entirely | Add a phrase after compass when you know roughly what you want |
| CI / piped stdin | mcpcli learbn 2>&1 | tee log.txt | Guide prints to stdout; no TTY menu — copy commands from output | Use --run-suggestion only when you trust high-confidence auto-run |
| TTY pick and re-run | mcpcli totally-unknown-cmd | Pick 1 from menu → same process runs get-context / find-code / learn | No shell respawn; ZEPHEX_COMPASS_REDIRECT blocks a second auto-redirect |
Decision flow (no AI)
Compass uses a local phrase catalog (35 intents) plus Levenshtein spellcheck. Routing completes in milliseconds with no network call. Multi-word phrases like where is my database are often corrected before you see a compass screen — Zephex runs the right command directly.
Your input │ ├─ Known command? ──────────────────────────► Run it (get-context, find-code, …) │ ├─ Multi-word phrase matches intent? ─────────► Run best command (e.g. where is my database → get-context database) │ ├─ Single-token typo close to real command? ──► Compass with "Did you mean" │ ├─ Unknown subcommand / nonsense? ──────────► Compass guide page │ └─ TTY + you pick 1–3? ─────────────────────► Re-run that command in-processPhrase normalization
Before matching, your input is normalized so casual typing still hits the catalog:
| Rule | Example |
|---|---|
| Lowercase | Where Is My Database → where is my database |
| Strip punctuation | where is my database? → where is my database |
| Collapse hyphens/underscores to spaces | get-contect → get contect |
| Collapse repeated spaces | find code → find code |
| Multi-word argv joined | argv ["where","is","my","database"] → phrase match |
High vs low confidence
Confidence affects whether --run-suggestion auto-runs and whether the intent router dispatches immediately:
| Level | Meaning | Examples | Behavior |
|---|---|---|---|
| High | Exact or strong phrase match (score ≥ 70), or spellcheck ≥ 80% | where is my database · learbn (close typo) · is express safe | Intent router may run command directly; --run-suggestion auto-runs best pick |
| Low | Partial phrase overlap or weaker spell match | totally-unknown-cmd-xyz · vague single words | Shows compass with ask/get-context/learn fallbacks; --run-suggestion does not auto-run |
Package name extraction
Upgrade and safety intents attach a package name when you include one in the phrase:
| You type | Resolves to | Note |
|---|---|---|
upgrde react | mcpcli upgrade react | Trailing token after upgrade intent |
is lodash safe | mcpcli check-package lodash | is … safe extracts package name |
check express | mcpcli check-package express | check <pkg> when intent is package-safe |
react alone | mcpcli check-package react | Short real package names still use check-package (by design) |
asdfghjkl | Compass fallback | 9+ char nonsense skips bare package route |
Triggers
| When | Example | Result |
|---|---|---|
| Unknown subcommand | mcpcli learbn | Compass page with Did you mean + runnable examples |
| Long nonsense token | mcpcli asdfghjkl | Compass (not surprise check-package lookup) |
| Explicit compass | mcpcli compass "where is my database" | Compass for any phrase |
| Unknown learn topic | mcpcli learn foobar | Compass instead of stderr wall |
| Smart phrase routing | mcpcli where is my database | Runs get-context database directly (no compass needed) |
| Bare compass (no phrase) | mcpcli compass | Opens learn index — same as mcpcli learn |
| Quoted single argv | mcpcli "where is my database" | Intent router splits phrase → get-context database |
| help on unknown cmd | mcpcli learbn help | Compass (not per-command --help) |
| Redirect loop guard | ZEPHEX_COMPASS_REDIRECT=1 + typo | Exit 1 — prevents infinite re-dispatch |
You might type → run this
Top 10 intents — the ones users hit most often:
| You might type | Try this first | Also works |
|---|---|---|
| database / db / where is my database | mcpcli get-context databaseShows where your DB is configured | mcpcli find-code "DATABASE_URL" · mcpcli ask "where is my database configured" |
| auth / login / where is auth | mcpcli find-code "auth"Find auth and login code | mcpcli architecture --topic auth · mcpcli ask "where is login handled" |
| upgrade / upgrde react | mcpcli upgrade reactUpgrade or audit a package | mcpcli check-package react · mcpcli deps |
| is lodash safe | mcpcli check-package lodashCheck if a package is safe | mcpcli loop-guard lodash · mcpcli deps |
| what stack | mcpcli get-contextProject stack snapshot | mcpcli architecture · mcpcli ask "what stack is this" |
| find / search / where is … | mcpcli find-code "your query"Search code across the repo | mcpcli ask · mcpcli scope-task "your task" |
| scope / what files for … | mcpcli scope-task "your task"Map a task to files | mcpcli find-code "…" · mcpcli get-context |
| deps / packages | mcpcli depsScan project dependencies | mcpcli check-package express · mcpcli compare lodash ramda |
| help / commands / what can you do | mcpcli learnSee all terminal tools | mcpcli cli-guide · mcpcli help |
| nonsense / asdfghjkl | mcpcli ask "your question"Fallback when nothing matches | mcpcli get-context · mcpcli learn |
All 35 intent routes
Every row below is baked into the CLI. Phrases are matched after normalizing case, punctuation, and spacing. Package names appended to upgrade/check intents (e.g. upgrde react) attach automatically.
Project context
get-context topics — stack, DB, deploy, monorepo
| Topic | Example phrases | Best command | Also works | What it does |
|---|---|---|---|---|
database | database, db, databse, datbase, where is my database, postgres connection, supabase url | mcpcli get-context database | mcpcli find-code "DATABASE_URL" · mcpcli ask "where is my database configured" | Shows where your DB is configured |
stack | what stack, tech stack, what framework, what is this project, what kind of app | mcpcli get-context | mcpcli architecture · mcpcli ask "what stack is this" | Project stack snapshot |
framework | framework, frontend, backend, what framework, next js stack | mcpcli get-context framework | mcpcli architecture · mcpcli deps | Framework and stack details |
env | env, environment, env vars, dotenv, secrets config | mcpcli get-context env | mcpcli find-code ".env" · mcpcli ask "where are env vars" | Environment configuration |
deploy | deploy, hosting, production, vercel, railway, render | mcpcli get-context deploy | mcpcli architecture · mcpcli find-code "deploy" | Deploy and hosting setup |
scripts | scripts, npm scripts, how to run, start dev, dev server | mcpcli get-context scripts | mcpcli get-context start · mcpcli deps | Run scripts and dev commands |
testing | tests, testing, jest, vitest, playwright, test suite | mcpcli get-context testing | mcpcli find-code "describe(" · mcpcli scope-task "add tests" | Testing setup in the project |
monorepo | monorepo, workspaces, turbo, lerna, pnpm workspace | mcpcli get-context monorepo | mcpcli deps · mcpcli architecture | Monorepo layout |
Code & architecture
Search, read, map structure, find integrations
| Topic | Example phrases | Best command | Also works | What it does |
|---|---|---|---|---|
auth | auth, login, authentication, where is auth, sign in flow, session handling | mcpcli find-code "auth" | mcpcli architecture --topic auth · mcpcli ask "where is login handled" | Find auth and login code |
find | find, search, where is, locate, grep, look for, find code | mcpcli find-code "query" | mcpcli ask · mcpcli scope-task "task" | Search code across the repo |
read-code | read code, read file, show file, outline file, summarize file | mcpcli read-code | mcpcli find-code · mcpcli symbol | Read or outline a file |
architecture | architecture, how it works, app structure, system design, explain architecture | mcpcli architecture | mcpcli get-context · mcpcli find-code "router" | Architecture map of the app |
api-routes | api routes, rest api, endpoints, where are my routes, express routes | mcpcli find-code "router" | mcpcli architecture · mcpcli get-context backend | Find API route definitions |
middleware | middleware, where is middleware, express middleware | mcpcli find-code "middleware" | mcpcli architecture --topic auth · mcpcli read-code | Locate middleware in the codebase |
docker | docker, dockerfile, container, where is docker | mcpcli find-code "Dockerfile" | mcpcli get-context deploy · mcpcli ask "how is this deployed" | Find container and deploy config |
ci | ci, github actions, pipeline, workflow, where is ci | mcpcli find-code ".github/workflows" | mcpcli get-context deploy · mcpcli architecture | Find CI/CD workflow files |
stripe-billing | stripe, billing, subscription, payments, checkout | mcpcli find-code "stripe" | mcpcli get-context integrations · mcpcli architecture | Find billing and Stripe integration |
rename | rename, rename symbol, rename everywhere, find usages | mcpcli rename "Symbol" | mcpcli usages · mcpcli find-code | Find every usage before a rename |
Packages & dependencies
Upgrade, audit, compare, safety checks
| Topic | Example phrases | Best command | Also works | What it does |
|---|---|---|---|---|
upgrade-package | upgrade, upgrde, updgrade, update package, bump package, upgrade packages | mcpcli upgrade <pkg> | mcpcli check-package <pkg> · mcpcli deps | Upgrade or audit a package |
package-safe | is safe, is it safe, cve check, security check package, check if safe | mcpcli check-package <pkg> | mcpcli loop-guard <pkg> · mcpcli deps | Check if a package is safe |
deps | deps, dependencies, packages, package json, npm deps, outdated deps | mcpcli deps | mcpcli check-package express · mcpcli compare lodash ramda | Scan project dependencies |
compare-pkg | compare packages, vs packages, lodash vs, package compare | mcpcli compare a b | mcpcli check-package · mcpcli deps | Compare two npm packages |
audit-pkg | audit package, migration guide, breaking changes, changelog | mcpcli loop-guard <pkg> | mcpcli check-package <pkg> · mcpcli upgrade <pkg> | Package upgrade audit |
check-pkg | check package, package info, npm package, lookup package | mcpcli check-package <pkg> | mcpcli loop-guard <pkg> · mcpcli safe <pkg> | Check one npm package |
Account & setup
Keys, usage, setup, init, status
| Topic | Example phrases | Best command | Also works | What it does |
|---|---|---|---|---|
history | history, again, last command, recent commands, rerun | mcpcli history | mcpcli again · mcpcli usage | Re-run recent commands |
setup | setup, connect editor, install mcp, configure cursor, login zephex | mcpcli setup | mcpcli connect · mcpcli status | Connect Zephex to your editor |
account | account, api key, keys, usage, billing, logout | mcpcli keys | mcpcli usage · mcpcli status | API keys and usage |
init | init, onboard, getting started, first run, onboarding | mcpcli init | mcpcli setup · mcpcli learn | First-run onboarding |
docs | docs, documentation, dev info, zephex docs | mcpcli docs | mcpcli cli-guide · mcpcli learn | Zephex developer docs |
status | status, am i connected, is zephex working, doctor | mcpcli status | mcpcli doctor · mcpcli keys | Check Zephex install and connection |
Help & reasoning
Learn index, ask, scope, think
| Topic | Example phrases | Best command | Also works | What it does |
|---|---|---|---|---|
scope | scope, what files, which files, files for task, scope task, what to touch | mcpcli scope-task "task" | mcpcli find-code · mcpcli get-context | Map a task to files |
help | help, commands, what can you do, what can i do, tool list, cli help | mcpcli learn | mcpcli cli-guide · mcpcli help | See all terminal tools |
ask-nl | ask, question, natural language, tell me | mcpcli ask "…" | mcpcli find-code · mcpcli get-context | Ask in plain English |
think | think, reason, debug think, step by step | mcpcli think | mcpcli scope-task · mcpcli ask | Structured reasoning helper |
prove | prove, verify claim, fact check | mcpcli ask "…" | mcpcli find-code · mcpcli check-package | Investigate a claim in your repo |
Spellcheck corrections
Close typos show Did you mean on the compass page. Some are also rewritten automatically before dispatch (e.g. get-contect → get-context).
| Typo | Suggests | Try it |
|---|---|---|
get-contect | get-context | mcpcli get-contect |
find-coed | find-code | mcpcli find-coed auth |
upgrde | upgrade | mcpcli upgrde next |
updgrade | upgrade | mcpcli updgrade react |
databse | get-context database | mcpcli databse |
datbase | get-context database | mcpcli datbase |
architecure | architecture | mcpcli architecure |
scop-task | scope-task | mcpcli scop-task "fix bug" |
chekc-package | check-package | mcpcli chekc-package express |
learbn | learn | mcpcli learbn |
comands | commands | mcpcli comands |
setp | setup | mcpcli setp |
histroy | history | mcpcli histroy |
How to invoke Compass
# 1 — Typo unknown subcommand → compass automaticallymcpcli learbn # 2 — Explicit compass for any phrase (quoted or spaced)mcpcli compass "where is my database"mcpcli compass upgrde react # 3 — Auto-run best pick (high confidence only, no menu)mcpcli compass "where is my database" --run-suggestion # 4 — Terminal tool index (NOT editor MCP tools toggle)mcpcli commandsmcpcli learnmcpcli learn find_code # 5 — Phrase may skip compass and run directlymcpcli where is my databasemcpcli get-context databasemcpcli databse # topic typo → database contextFive-minute try (no agent)
npm install -g zephexcd your-appmcpcli learbn # see compassmcpcli compass "what stack" # see suggestionsmcpcli where is my database # often runs get-context directlymcpcli learn # full tool indexExit codes
| Code | When |
|---|---|
0 | TTY pick succeeded and re-dispatched command finished OK, or --run-suggestion high-confidence run succeeded |
1 | Guide shown and you exited (0/Esc), redirect loop guard, or re-dispatched command failed |
1 | Compass redirect guard active (ZEPHEX_COMPASS_REDIRECT=1) — caller exits without second compass |
Pick a number and run
When stdin is an interactive terminal (not CI, not a pipe), Compass shows a menu after the guide page:
What would you like to run? 1 mcpcli get-context database 2 mcpcli find-code "DATABASE_URL" 3 mcpcli learn 0 Exit- 1–3 — Re-dispatches in-process (same shell, no
npxrespawn). UsesZEPHEX_COMPASS_REDIRECTto prevent loops (max one auto-redirect per session). - 0 or Esc — Exit code
1(guide was shown). - CI / scripts — Commands print only; copy from stdout. No menu.
- Success after pick — Exit code
0if the re-run command succeeds.
Commands the menu can re-run
Picking from the TTY menu re-dispatches in-process — no new shell. These subcommands are supported today:
get-contextfind-coderead-codeoutlinesymbolarchitecturescope-taskcheck-packageloop-guardupgradedepscompareasklearncommandscli-guidehistorykeysusagesetupconnectinitdocsthink
Anything else prints Cannot run: … and exits 1. Use learn from the menu to find the right tool name first.
Flags
| Flag | Effect |
|---|---|
--run-suggestion | On high-confidencematch only: run "Try this first" immediately — skips the TTY menu. Useful in scripts when you trust the phrase catalog. |
--compass-run | Alias for --run-suggestion. |
Compass vs learn vs ask vs help
| Command | Use when | Calls MCP? | TTY menu? |
|---|---|---|---|
mcpcli learn | You want the full menu of tools and examples | No | No |
mcpcli commands | Same as learn — terminal discovery alias | No | No |
mcpcli compass … | You typed wrong input and need the right command now | No | Yes (TTY) |
mcpcli ask "…" | You have a plain-English question about the repo | Yes | Sometimes |
mcpcli help / mcpcli cli-guide | Long-form reference and account/setup topics | No | No |
mcpcli tools | Enable/disable MCP tools in your editor config — different from commands | No | No |
FAQ
Does Command Compass use AI?
No. Routing uses 35 local intent phrases plus Levenshtein spellcheck. Compass itself never calls MCP and never calls an LLM.
Why does react still run package check?
Short tokens that look like real npm package names still route to check-package — that is intentional. Long nonsense tokens (9+ characters with no spell match, e.g. asdfghjkl) show Compass instead of a surprise registry lookup.
What is the difference between commands and tools?
mcpcli commands and mcpcli learn show the terminal tool guide (copy-paste examples, no API). mcpcli tools lists and toggles which MCP tools are enabled in Cursor, Claude, VS Code, etc.
Can I use Compass in CI?
Yes — output is on stdout and is copy-paste friendly. There is no TTY menu in pipes. Use --run-suggestion only when you accept auto-running a high-confidence command. Exit 1 unless a picked/rerun command succeeds.
How is this different from find-code tools?
Appending tools or help after a knowncommand opens that tool's learn screen. Compass handles unknown input and cross-tool suggestions.
Where is the source of truth?
Intent phrases live in mcp-proxy/src/lib/cli-command-intents.ts. UI in cli-command-compass.ts. This docs page mirrors dashboard/src/lib/cli-docs-inventory.ts.
Why did my phrase run a command instead of showing Compass?
High-confidence intent matches in applyIntentRouting rewrite argv before dispatch — that is intentional. Run mcpcli compass "your phrase" when you want to see all three suggestions without auto-running.
Does Compass work without an API key?
Yes for the guide itself — routing and the compass page are local. Commands you pick from the menu (e.g. get-context, ask) follow their normal auth rules and may prompt for setup if no key is stored.
What if I run compass with no arguments?
mcpcli compass opens the full learn index — same as mcpcli commands. Add a phrase when you want targeted suggestions.
Common issues
- Menu does not appear — stdin is not a TTY (CI, pipe, or agent subprocess). Copy commands from stdout instead.
- Compass redirect loop prevented — you already picked once this session. Run the suggested command directly in your shell.
- Short token went to check-package — real package names like
reactare intentional. Usemcpcli compass reactfor alternatives. - --run-suggestion did nothing — only fires on high confidence. Low-confidence input still shows the guide.
- Wrong bin in examples — Compass uses your active invoke prefix (
mcpcli,zephex,npx zephex). Docs tables use the same helper.
Where to next
- Terminal CLI (Mode 2) — get-context, find-code, monorepos, flags
- CLI commands — full reference + discovery hints
- Terminal tools complete guide — deep dives per tool
- Account & logout — setup, keys, usage