# Terminal tools — complete guide

Mode 2 terminal access to all nine CLI-exposed MCP tools plus account commands.

# CLI without an AI agent (Mode 2)

Use `npx zephex` directly in your terminal for the same hosted MCP tools — no Cursor, Claude, or VS Code required.

## Quick start
1. `npx zephex setup` — browser OAuth, writes ~/.zephex
2. `cd` into your app (folder with package.json + src/)
3. `npx zephex get-context` — project snapshot
4. `npx zephex find-code "auth"` — search the repo
5. `npx zephex safe express` — package safety (no repo needed)

## Project detection scenarios
| ID | 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 mcpcli setup or set ZEPHEX_API_KEY |
| G | File path while cwd is wrong | Error names project root; use cd or --cwd |
| H | check-package / loop-guard | Works with no project folder |

## Endpoint
All tools call https://zephex.dev/mcp with your API key from ~/.zephex or ZEPHEX_API_KEY.

## Next docs
- [CLI commands reference](https://zephex.dev/docs/cli-commands)
- [Terminal tools complete guide](https://zephex.dev/docs/terminal-tools-complete-guide)
- [CLI account & logout](https://zephex.dev/docs/cli-account)


Canonical HTML: https://zephex.dev/docs/cli-without-agent

# Zephex CLI — full command reference

Account commands (setup, logout, disconnect) plus Mode 2 terminal tools. Primary guide for terminal-only use without an AI agent.

## Account commands
| Command | Aliases | Purpose |
| --- | --- | --- |
| `init` | onboard, getting-started | First-run wizard: prereq checks → zephex.dev/cli/auth → terminal + optional editor |
| `setup` | login, sign-in, connect | Browser OAuth → API key → editor MCP config + ~/.zephex |
| `connect` | — | Alias for setup — connect MCP to any of 22+ editors |
| `logout` | sign-out | Delete ~/.zephex; --all also disconnects every editor |
| `disconnect` | remove | Remove Zephex from editor JSON; revoke key server-side |
| `reconnect` | — | disconnect --quiet + fresh setup (--cursor, --claude-code, --vscode, …) |
| `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, …) |
| `learn` | commands | Per-tool terminal guide (no MCP call); index or learn find_code |
| `compass` | — | Command Compass — guide when input doesn't match a command (no MCP call) |
| `ask` | — | Natural-language router to find, context, package, architecture |
| `deps` | dependencies | Scan all direct deps in package.json (batch check_package) |
| `compare` | vs | Side-by-side package intel for two npm packages |
| `history` | hist, again, repeat | Local command log; re-run with history N or again |
| `update` | upgrade (no args) | Check npm latest; --apply runs npm install -g zephex@latest |
| `repair` | — | Fix broken stdio npm pins in editor MCP configs |
| `uninstall` | — | Remove Zephex CLI from PATH; --full deletes ~/.zephex |
| `welcome` | — | Print home screen (tools, slash palette, quota) |
| `voice-check` | — | Diagnose Voice Mode (pipe, PTT, STT subprocess) |
| `voice-setup` | — | Interactive Voice Mode setup (pipe + env vars) |
| `slash-demo` | slash-preview | Print / palette without TTY (docs + CI) |
| `remember` | — | Store a project fact → project_memory MCP |
| `recall` | — | Search saved memories by keyword |
| `memory` | — | list | forget <uuid> — project_memory CLI |
| `check url` | site-audit, audit-headers, check-url | Live HTTP/TLS header audit → audit_headers MCP |
| `web` | website, scan-web | Full hosted website overview scan |
| `site` | pulse, broken | Site Pulse — fast local HTTP or cloud browser scan |
| `supply` | sup, chain | Supply Pulse — secrets, CVEs, deploy surface on URL or repo |
| `shadow` | shadow-audit | Hidden API surface scan on repo or live URL |
| `upgrade` | upgrde, updgrade | Package smart upgrade (check_package --task upgrade); bare = CLI self-update |
| `loop-guard` | — | Alias for check-package --task upgrade (breaking-change guard) |
| `last` | — | Repeat last package lookup |

## Terminal tools (Mode 2)
| MCP tool | CLI primary | Aliases | Example | Needs project |
| --- | --- | --- | --- | --- |
| `get_project_context` | get-context | context, ., stack, framework, database, backend, frontend, auth, quick, … | `mcpcli get-context` | yes |
| `find_code` | find-code | find, search, grep, rename, everywhere, usages, defs, where, … | `mcpcli find-code "auth middleware"` | yes |
| `read_code` | summarize / outline / symbol | read-code, read, explain, show, files, peek, … | `mcpcli outline src/lib/auth.ts` | yes |
| `explain_architecture` | architecture | arch, explain-architecture, structure | `mcpcli architecture --focus auth` | yes |
| `check_test` | check-test | scope, plan, files-for, touch, scope-task | `mcpcli check-test "add Stripe webhooks"` | yes |
| `keep_thinking` | think | reason, debug-think (one-shot in terminal) | `mcpcli think "debug 401 after refresh"` | no |
| `check_package` | check-package | check, safe, lookup, pkg, package | `mcpcli safe express` | no |
| `project_memory` | remember / recall / memory | /memory, /remember, /recall | `mcpcli remember "auth uses Supabase JWT"` | no |
| `audit_headers` | check url | site-audit, audit-headers, /check-url | `mcpcli check url https://zephex.dev --deep` | no |
| `Zephex_dev_info` | docs | /docs | `mcpcli docs "Stripe webhooks"` | no |

## Editor-only tools
- **keep_thinking (multi-turn)** — Terminal has one-shot think/reason/debug-think; sessionId checkpoint flows are editor-only.

## Help topics
| Command | Output |
| --- | --- |
| `mcpcli help` | Editors + account + terminal overview |
| `mcpcli help terminal` | Every Mode 2 alias on one screen |
| `mcpcli help tools` | All 10 MCP tools — editor vs terminal |
| `mcpcli help setup` | Editor flags, --project vs --global |
| `mcpcli cli-guide` | Mode 2 guide index |
| `mcpcli cli-guide project` | Scenarios A–H (where am I searching?) |
| `mcpcli cli-guide account` | logout vs disconnect lifecycle |
| `mcpcli find-code --help` | Per-tool flags for find_code |
| `mcpcli logout --help` | Terminal sign-out vs disconnect |
| `mcpcli update --help` | Check and apply npm CLI upgrades |

## Five-minute test
**terminal**
```shell
# Copy-paste test flow (no AI agent) — mcpcli = zephex
npm install -g zephex
mcpcli init
mcpcli doctor
cd your-app   # folder with package.json + src
mcpcli overview
mcpcli get-context
mcpcli find-code "test"
mcpcli safe lodash
mcpcli check-test
mcpcli check url https://example.com
mcpcli remember "first run used overview + get-context"
mcpcli logout
mcpcli setup   # sign in again
mcpcli update --check
```

## See also
- [CLI without an AI agent](https://zephex.dev/docs/cli-without-agent)
- [Terminal tools complete guide](https://zephex.dev/docs/terminal-tools-complete-guide)
- [Connect MCP](https://zephex.dev/docs/connect-mcp)


Canonical HTML: https://zephex.dev/docs/cli-commands