# Zephex CLI — Download & Install

**Last updated:** June 2026  
**Canonical npm package:** [`zephex`](https://www.npmjs.com/package/zephex)  
**Site:** [zephex.dev](https://zephex.dev) · **Docs:** [install methods](https://zephex.dev/docs/install-methods)

This file is the living install + account reference for the **terminal MCP CLI** (`mcpcli`, `zephex`, `zphx`, …). Add notes here as we ship more editors or commands.

---

## One sentence

Install Node → `npm install -g zephex` → `mcpcli init` → browser login at **zephex.dev/cli/auth** → run tools from any project folder with **one command** (no `npx`).

```bash
mcpcli ask "what stack is this" --path github:docker/mcp-registry
mcpcli find-code "auth"
mcpcli read-code --mode outline src/index.ts
```

---

## npm packages (same engine)

| Package | Commands after install |
|---------|------------------------|
| **`zephex`** (recommended) | `zephex`, `mcpcli`, `zepx`, `zphx`, `mcpz`, `zepcli`, `zephx` |
| **`@tanstratum/mcpcli`** | `mcpcli`, `zephex` |
| **`@tanstratum/zphx`** | `zphx`, `mcpcli`, `zephex` |
| **`@tanstratum/zepx`** | `zepx`, `mcpcli`, `zephex` |
| **`@tanstratum/mcpz`** | `mcpz`, `mcpcli`, `zephex` |
| **`@tanstratum/zepcli`** | `zepcli`, `mcpcli`, `zephex` |
| **`@tanstratum/zephx`** | `zephx`, `mcpcli`, `zephex` |

All ship the **same** `cli.js` + `tools/server.js`. Pick one package; every bin name works.

---

## Install methods

### 1. npx (no global install)

```bash
npx zephex init
npx -p zephex mcpcli setup
npx zephex@latest get-context
```

### 2. npm global (recommended for daily use)

```bash
npm install -g zephex
mcpcli init
mcpcli get-context
```

### 3. pnpm / bun

```bash
pnpm dlx zephex mcpcli setup
bunx zephex init --terminal
bun install -g zephex && mcpcli setup
```

### 4. Update CLI

```bash
mcpcli update              # check npm vs installed
mcpcli update --apply      # npm install -g zephex@latest
mcpcli skills --upgrade    # refresh agent skill files after update
```

### 5. Docker

See [docs/cli-docker](https://zephex.dev/docs/cli-docker).

### 6. Editor MCP only (no terminal CLI)

Create a key at [zephex.dev/dashboard/keys](https://zephex.dev/dashboard/keys) and paste into editor settings — [connect MCP guide](https://zephex.dev/docs/connect-mcp).

---

## First run

```bash
npm install -g zephex
mcpcli init                  # wizard: terminal and/or editor
# OR
mcpcli init --terminal       # terminal tools only
mcpcli init --cursor         # Cursor + terminal credentials
```

Browser opens **https://zephex.dev/cli/auth** (user login — not documentation).

---

## Connect MCP to editors (22+)

`connect` = `setup` = `login` (same OAuth flow).

```bash
mcpcli connect --cursor
mcpcli connect --claude-code      # alias → claude
mcpcli connect --vscode
mcpcli connect --vs-code          # alias
mcpcli connect --opencode
mcpcli connect --codex
mcpcli connect --factory-ai       # alias → droid
mcpcli connect --zed
mcpcli connect --windsurf
mcpcli connect --gemini
mcpcli connect --warp
mcpcli connect --kiro
mcpcli connect --cline
mcpcli connect --jetbrains
mcpcli connect --crush
mcpcli connect --hermes
mcpcli connect --kilo
mcpcli connect --amp
mcpcli connect --continue
mcpcli connect --copilot
mcpcli connect --claude-desktop
mcpcli connect --antigravity
mcpcli connect --trae
mcpcli connect --roo
mcpcli connect --terminal         # ~/.zephex only, no editor file
```

Full flag list: `mcpcli connect --help`

---

## Disconnect & reconnect

```bash
mcpcli list                       # what's installed
mcpcli disconnect --cursor        # remove + revoke key
mcpcli disconnect --all             # every editor
mcpcli reconnect --vscode           # fresh key + re-setup
mcpcli reconnect --claude-code
mcpcli repair                     # fix broken stdio pins
mcpcli doctor
```

Help: `mcpcli disconnect --help` · `mcpcli reconnect --help`

---

## Logout

```bash
mcpcli logout                     # terminal only (~/.zephex)
mcpcli logout --all               # terminal + disconnect all editors
```

`logout` ≠ `disconnect`. See [docs/cli-account](https://zephex.dev/docs/cli-account).

---

## Terminal MCP tools (9 in CLI)

After `npm install -g zephex`, from **any project folder** — no `npx`:

```bash
mcpcli get-context
mcpcli find-code "auth"
mcpcli read-code --mode outline src/lib/auth.ts
mcpcli deps
mcpcli learn
mcpcli ask "where is login handled"
mcpcli ask "what stack is this" --path github:docker/mcp-registry
```

`mcpcli` = `zephex` = `zepx` = `zphx` (same binary). Use whichever name you prefer.

`audit_headers` is **editor-only** (10th MCP tool). Full list: `mcpcli help tools`.

---

## Verify install

```bash
mcpcli info
mcpcli update --check
mcpcli doctor
mcpcli status
cd your-app && mcpcli get-context
```

---

## Repo / dev build

```bash
cd mcp-proxy
bun run build
node dist/cli.js init --help
npm link                          # optional: global dev binary
```

---

## Related docs in this repo

| File | Purpose |
|------|---------|
| [summary.md](./summary.md) | Handoff index — what we built |
| [cli-june-2026-complete-handoff.md](./cli-june-2026-complete-handoff.md) | **Master narrative** — 10 tools, account lifecycle, agent CLI, docs |
| [cli-power-mode-discovery-summary.md](./cli-power-mode-discovery-summary.md) | learn, ask, deps, history |
| [docs/cli-command-reference.md](./docs/cli-command-reference.md) | All commands |
| [dashboard-docs-cli-summary.md](./dashboard-docs-cli-summary.md) | zephex.dev docs pages |

---

## Agent CLI parity audit (June 2026)

**What “agent CLI” means here:** one global binary (`mcpcli` / `zephex`) for terminal MCP tools — no `npx` after `npm install -g zephex`. Same pattern as `gh`, `railway`, `vercel`.

| Area | Fixed |
|------|--------|
| **Invoke prefix** | `cli-invoke-prefix.ts` — help/errors match how you ran the CLI |
| **Tool --help** | ask, find-code, read-code, get-context, scope-task, architecture |
| **Human output footers** | find/read/deps/architecture/scope/history formatters |
| **Doctor fixes** | setup/reconnect/repair hints use `mcpcli` |
| **Dashboard docs** | cli-account, cli-init, cli-without-agent, cli-docs-inventory |
| **Login URL** | Always `https://zephex.dev/cli/auth` (backend: `/api/cli/session`) |

**Both commands work:** `mcpcli ask "…"` = `zephex ask "…"` = `zphx ask "…"` (same `cli.js`).

---

## What we shipped (June 2026)

Terminal **account lifecycle** — same `cli.js` in every npm package (`zephex`, `@tanstratum/mcpcli`, `@tanstratum/zphx`, …):

| Command | Purpose |
|---------|---------|
| `init` | First-run wizard; marks `~/.zephex/onboarding.json` |
| `connect` | Alias for `setup` / `login`; 22+ editor flags + aliases (`--claude-code`, `--vs-code`, `--factory-ai`) |
| `disconnect` | Remove editor MCP config + revoke API key |
| `reconnect` | Quiet disconnect + fresh OAuth setup |
| `logout` | Clear `~/.zephex`; `--all` also disconnects every editor |
| `update --apply` | Compare npm registry vs installed; run `npm install -g zephex@latest` |
| `list` | Per-editor install status (Crush, Hermes, Roo, ChatGPT, …) |

**Not new MCP tools** — still 9 terminal tools + `audit_headers` editor-only. This work is connect/disconnect UX parity across all bin names.

**Source:** `src/lib/editor-registry.ts` · `src/lib/cli-account-help.ts` · `src/commands/{init,connect,disconnect,reconnect,update,logout}.ts`

**Handoff:** [summary.md](./summary.md) (CLI Account Lifecycle section)

---

## User install journey — where each step stops

Use this to verify on **macOS, Windows, or Linux** (Node 20+).

| Step | Command | Success | Stops here if… |
|------|---------|---------|----------------|
| 1 | `node -v` | Shows v20+ | Node not installed → [nodejs.org](https://nodejs.org) first |
| 2 | `npm install -g zephex` | No errors | npm missing, proxy, or permissions (try `npm i -g zephex` as admin on Windows) |
| 3 | `mcpcli --version` | Shows 2.5.x | Wrong PATH — restart terminal; check `which mcpcli` (Mac/Linux) or `where mcpcli` (Windows) |
| 4 | `zephex --version` | Same version | Same binary — if this fails but mcpcli works, reinstall |
| 5 | `mcpcli init` | Browser opens **zephex.dev/cli/auth** | Network/firewall blocks zephex.dev |
| 6 | Complete browser login | CLI prints “credentials saved” | User closed browser early — run `mcpcli setup` again |
| 7 | `mcpcli connect --cursor` | Writes editor MCP config | Editor not installed — pick another flag or `mcpcli init --terminal` |
| 8 | `cd your-app && mcpcli get-context` | Project brief | Wrong folder (no package.json) — `cd` into app root |
| 9 | `mcpcli ask "what stack is this"` | Routed tool output | No API key — repeat step 5–6 |
| 10 | `mcpcli logout` | Clears `~/.zephex` | N/A — editors still connected |
| 11 | `mcpcli disconnect --all` | Revokes keys + removes configs | N/A |
| 12 | `mcpcli update --apply` | npm upgrades zephex | Not logged into npm / 2FA — needs `NPM_OTP` |

**Windows paths:** credentials at `%USERPROFILE%\.zephex\credentials.json` · VS Code MCP at `%APPDATA%\Code\User\mcp.json`

**One-shot (no global install):** `npx -p zephex mcpcli init` — downloads each run; stops if Node missing.

**Find the package:** [npmjs.com/package/zephex](https://www.npmjs.com/package/zephex) · scoped: `@tanstratum/mcpcli`

---

## Maintainer verify (after changes)

```bash
cd mcp-proxy
bun run build
bun test ./src/__tests__/editor-registry.test.ts
bun test ./src/__tests__/cli-invoke-prefix.test.ts
bun test ./src/__tests__/cli-dispatch.test.ts
bun test ./src/__tests__/cli-project-errors.test.ts
bun test ./src/__tests__/disconnect-revoke.test.ts
cd dashboard && bun test ./src/__tests__/cli-without-agent-content.test.ts

# Smoke (both bins — same dist/cli.js)
node dist/cli.js ask --help
node dist/cli.js connect --help
node dist/cli.js logout --help
node dist/cli.js update --help
```

---

## Notes (add below as we ship)

<!-- Add release notes, version pins, Homebrew, etc. -->