Core documentation content is fully readable without JavaScript. The table of contents, assistant, and some copy buttons enhance the experience but are not required.

CLI

Install Methods — Pick the one that fits your environment

Start with curl if you have no Node. Use npx/pnpm/bun only when Node 22.5+ is already on the machine. Full CLI install, upgrade, Windows, Linux, and agent notes: /docs/zephex-cli.

How big is the download? The curl installer fetches the npm tarball only (~3 MB, ~13 MB unpacked). If Node 22.5+ is missing it also downloads a private Node once (~50 MB compressed). Prefer that over npm install -g zephex / bare npx zephex until the next slim publish — those commands currently also install unused server libraries (~260 MB, a few minutes).

Install & upgrade the Zephex CLI is the page to share with an agent or to search for later: curl installer, upgrade commands, Windows / Linux, and how agents should run zephex.

Decision flowchart

              Do you have Node.js 22.5+ already?
                            │
              ┌─────────────┴─────────────┐
            YES                           NO
              │                            │
              ▼                            ▼
     Editor or terminal?            curl install.sh
              │                     (bundles Node)
        ┌─────┴─────┐
    terminal     editor
        │           │
        ▼           ▼
  npx -y zephex   npx -y zephex
  @latest         @latest setup --cursor

curl installer — terminal CLI (Mode 2)

This one-liner is the Mode 2 terminal installer — the same zephex shell you type / in. It is not the editor MCP wizard on the homepage (npx -p zephex mcpcli setup). Same account and API key later; different first command.

curl -fsSL https://zephex.dev/cli/install.sh | bash

Same script lives at both URLs (use either):

curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash

What it does

Installs into ~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.
If your system Node is missing or older than 22.5, it downloads a private Node 22 runtime (~50 MB compressed, once) under ~/.zephex/node.
Downloads the zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).
Starts zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).

By operating system

macOS (Intel or Apple Silicon) — Terminal or iTerm. Needs curl (already there). After install, new Terminal windows pick up PATH from ~/.zshrc and ~/.zprofile. The current window still needs:

source ~/.zephex/env.sh

Linux (x64 or arm64) — bash, zsh, or fish. Same curl line. PATH is appended to ~/.bashrc / ~/.profile (and fish config if needed). If you installed as one user and launch the desktop as another, the binary will not be on PATH — stay on the same account.

Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:

irm https://zephex.dev/install.ps1 | iex

WSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.

Cloud shells, phones, other OS

Google Cloud Shell, GitHub Codespaces, Railway / Render shells — use the same curl line. Those boxes often ship Node 18 or 20. The installer notices and downloads a private Node 22 under ~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.
Android (Termux) — curl + bash work. Same installer. Hosted commands still need HTTPS out to zephex.dev.
iPhone / iPad — there is no native zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.
Windows ARM (Surface, Snapdragon) — PowerShell installer downloads the win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.

What the CLI talks to

Install download — Vercel serves install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.
Sign-in — browser or QR hits zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600).
Tool commands (/overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.
Sentry — Railway captures hosted tool / API errors (tagged with CLI version). The local zephex process does not send your repo to Sentry.

After install — first commands

source ~/.zephex/env.shcd your-appzephex# type /overview   or   /help

Hosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.

Upgrade

The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:

zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bash

Check what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.

This vs the homepage npx line

curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.
npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.
You can use both with one API key. Install the CLI first, then zephex connect --cursor when you want the editor.

Uninstall

zephex uninstall           # PATH + credentialszephex uninstall --full    # delete entire ~/.zephex

If something looks stuck

command not found: zephex — source ~/.zephex/env.sh, then open a new tab.
Piped curl into bash: the installer cannot keep PATH in that parent shell. That is why it prints the source line.
Only run the script from zephex.dev— never a random gist.
Offline or corporate TLS intercept: the script needs HTTPS to zephex.dev (npm package) and, if Node is missing, nodejs.org.

More paths: all install methods · macOS · Linux · Windows · terminal CLI

Method 1 — npx (no global install)

One command. Needs Node 22.5+ already on the machine (Cloud Shell and many laptop defaults are still 18/20 — use the curl installer there). Downloads zephex from npm to a temp folder and runs it. Nothing stays on your system. Prefer npx -y zephex@latest so you do not get a stale cache.

# Recommended — always latest, skip npx cache and confirm promptnpx -y zephex@latest setup # Connect one editor (global config — works in every project)npx -y zephex@latest setup --cursornpx -y zephex@latest setup --antigravitynpx -y zephex@latest setup --opencode # After setup — verify and fix stdio pinsnpx -y zephex@latest doctornpx -y zephex@latest listnpx -y zephex@latest repair

Pros: No install. Pin @latest to avoid stale cache. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). Type npx each time unless you install globally.

Global by default: setup writes user-level config (~/.cursor/mcp.json, ~/.config/opencode/opencode.json, etc.) and removes conflicting project-level Zephex entries. Add --project only when you want workspace-scoped config.

Method 2 — npm global install

Standard global install. Adds zephex to your PATH so you can type zephex without npx.

# Install oncenpm install -g zephex # Then run anywherezephex setupzephex listzephex tools # Update laternpm install -g zephex@latest

Pros: Type zephex instead of npx zephex. Faster startup (no download).

Cons: One install per Node version. May need sudo on some systems.

Method 3 — Bun

If you use Bun as your runtime, install zephex globally with Bun's package manager.

# Installbun install -g zephex # Runzephex setup # Or run via bunx (no install)bunx zephex setup

Pros: Bun is faster than Node for installs. Same binary as the npm version.

Cons: Requires Bun runtime installed.

Method 4 — pnpm

For pnpm users.

# Install globallypnpm add -g zephex # Runzephex setup # Or via pnpx (no install)pnpm dlx zephex setup

Method 5 — Docker

For users without Node.js, or those who want everything sandboxed. Run Zephex in a container without touching your host system.

Quick start with Docker

# Pull the latest imagedocker pull node:22-alpine # Run zephex setup inside a container, mounting your home dirdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup

This mounts your home directory into the container so the wizard can write the editor config files (~/.cursor/mcp.json, ~/.claude.json, etc.) to your real machine.

Run a specific command

# List installed editorsdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex list # Run doctordocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex doctor

Make it easier with a shell alias

# Add to ~/.bashrc or ~/.zshrcalias zephex='docker run -it --rm -v "$HOME:/root" -w /root node:22-alpine npx -y zephex' # Then use like normalzephex setupzephex listzephex doctor

Build your own image

If you don't want to download the package every time, build a thin image with Zephex pre-installed:

FROM node:22-alpineRUN npm install -g zephexENTRYPOINT ["zephex"]

# Build it oncedocker build -t zephex-cli . # Run any commanddocker run -it --rm -v "$HOME:/root" -w /root zephex-cli setupdocker run -it --rm -v "$HOME:/root" -w /root zephex-cli list

Pros: No Node.js required on the host. Everything sandboxed. Cleanup is just deleting the container/image.

Cons: Slower startup (container boot). Need Docker installed. Volume mounts get tricky on Windows.

Method 6 — Manual JSON config (no Node.js, no Docker)

If you can't (or don't want to) install Node.js or Docker, you can write the editor config file by hand. The Zephex CLI is just a convenience — the actual MCP connection is HTTP-based.

Step 1: Get an API key

Sign in at zephex.dev/dashboard/keys with GitHub or Google. Click "Create Key", copy the value (starts with mcp_prod_).

Step 2: Find your editor's MCP config file

Editor             Config file path
──────────────────────────────────────────────────────────────────────────
Cursor             ~/.cursor/mcp.json
Claude Code        ~/.claude.json
VS Code            <project>/.vscode/mcp.json
Codex              ~/.codex/config.toml
OpenCode           ~/.config/opencode/opencode.json
Windsurf           ~/.codeium/windsurf/mcp_config.json
Zed                ~/.config/zed/settings.json
Warp               ~/.agents/.mcp.json
Gemini CLI         ~/.gemini/settings.json
Kiro               ~/.kiro/settings/mcp.json
Cline (VS Code)    Library/Application Support/Code/User/globalStorage/
                     saoudrizwan.claude-dev/settings/cline_mcp_settings.json
JetBrains          <project>/.junie/mcp/mcp.json
Kilo Code          Library/Application Support/Code/User/globalStorage/
                     kilocode.kilo-code/settings/mcp_settings.json
Amp                ~/.config/amp/settings.json
Continue           ~/.continue/config.yaml
GitHub Copilot CLI ~/.copilot/mcp-config.json
Factory Droid      ~/.factory/mcp.json
Claude Desktop     Library/Application Support/Claude/claude_desktop_config.json
Antigravity        ~/.gemini/antigravity/mcp_config.json
TRAE               <project>/.trae/mcp.json

Step 3: Add the Zephex entry

For most editors (Cursor, Claude Code, Windsurf, Zed, Kiro, Cline, Kilo, Copilot, Droid, Claude Desktop, Antigravity, TRAE):

{  "mcpServers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For VS Code (note servers not mcpServers):

{  "servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Zed (note context_servers):

{  "context_servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Antigravity (note serverUrl not url):

{  "mcpServers": {    "zephex": {      "serverUrl": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Codex (TOML format, not JSON):

[mcp_servers.zephex]url = "https://zephex.dev/mcp" [mcp_servers.zephex.http_headers]Authorization = "Bearer YOUR_API_KEY_HERE"

Step 4: Restart your editor

Quit completely and reopen. The Zephex tools will appear in your editor's tool list.

Pros: No Node.js, no Docker, nothing installed. Works in airgapped or restricted environments.

Cons: You manage the file by hand. To update keys, you edit the file. You don't get the wizard's nice 3-step picker.

Comparison table

Method        Speed     Disk    Node?    Docker?    Best for
──────────────────────────────────────────────────────────────────────────────
npx           ●●○       ~0      Yes      No         Trying it once
npm -g        ●●●       ~5MB    Yes      No         Daily use, fast startup
bun -g        ●●●       ~5MB    Bun      No         Bun runtime users
pnpm -g       ●●●       ~5MB    Yes      No         pnpm workspace users
Docker        ●○○       ~120MB  No       Yes        No Node, sandboxed
Manual JSON   ●●●       ~0      No       No         No Node, no Docker, airgapped

Updating Zephex

If installed via curl / install.sh

Re-run the one-liner or zephex update. That refreshes the npm package under ~/.zephex. Pin with ZEPHEX_VERSION=2.5.13 before the curl if you must stay on one release. Full notes in curl installer above.

zephex update# orcurl -fsSL https://zephex.dev/cli/install.sh | bash

If installed via npx

Always use @latest to bypass the npx cache:

npx zephex@latest setup

If installed via npm/bun/pnpm

# npmnpm install -g zephex@latest # bunbun install -g zephex@latest # pnpmpnpm add -g zephex@latest

If installed via Docker

# Pull a fresh node image (zephex is downloaded fresh each time with -y)docker pull node:22-alpine # Or rebuild your custom image if you made onedocker build -t zephex-cli --no-cache .

If installed via manual JSON

Nothing to update — you're calling the live https://zephex.dev/mcp endpoint directly. Just keep the API key valid and it works forever.

Uninstall

Remove just the Zephex config from your editors

# Remove from one editornpx zephex disconnect --cursor # Remove from every editornpx zephex disconnect --all # Full cleanup (config + skill + rule files)npx zephex reset --all

Uninstall the CLI itself

# npmnpm uninstall -g zephex # bunbun uninstall -g zephex # pnpmpnpm remove -g zephex # Docker — delete the imagedocker rmi zephex-cli

Common pitfalls (read before re-running setup)

Stale npm cache: use npx -y zephex@latest, not plain npx zephex.
Re-running setup too often: each OAuth run can mint a new API key — free tier allows 3 keys.
Editor not restarted: fully quit (Cmd+Q on Mac), not just close the window.
Works in terminal, fails in editor: GUI apps lack nvm/Homebrew on PATH — run npx -y zephex@latest repair.
Works in one repo, not another: project-level .vscode/mcp.json, opencode.json, or .mcp.json shadowing global — run global setup again or check npx -y zephex@latest list.
Antigravity: global path only (~/.gemini/antigravity/mcp_config.json); quit app fully and start a new agent session.

Full decision tree: MCP troubleshooting.

Where to next

Setup Walkthrough — visual guide to the wizard flow
CLI Commands Reference — every command explained
Supported Editors — config path for each editor
Plans — Free / Pro / Max tier comparison

CLI

Install Methods — Pick the one that fits your environment

Start with curl if you have no Node. Use npx/pnpm/bun only when Node 22.5+ is already on the machine. Full CLI install, upgrade, Windows, Linux, and agent notes: /docs/zephex-cli.

Install & upgrade the Zephex CLI is the page to share with an agent or to search for later: curl installer, upgrade commands, Windows / Linux, and how agents should run zephex.

Decision flowchart

              Do you have Node.js 22.5+ already?
                            │
              ┌─────────────┴─────────────┐
            YES                           NO
              │                            │
              ▼                            ▼
     Editor or terminal?            curl install.sh
              │                     (bundles Node)
        ┌─────┴─────┐
    terminal     editor
        │           │
        ▼           ▼
  npx -y zephex   npx -y zephex
  @latest         @latest setup --cursor

curl installer — terminal CLI (Mode 2)

curl -fsSL https://zephex.dev/cli/install.sh | bash

Same script lives at both URLs (use either):

curl -fsSL https://zephex.dev/cli/install.sh | bash# aliascurl -fsSL https://zephex.dev/install.sh | bash

What it does

Installs into ~/.zephex (or %USERPROFILE%\.zephex on Windows) — not into your project.
If your system Node is missing or older than 22.5, it downloads a private Node 22 runtime (~50 MB compressed, once) under ~/.zephex/node.
Downloads the zephex npm tarball only (~3 MB today, ~13 MB unpacked) into ~/.zephex/npm-global and links zephex + mcpcli. It does not run npm install -g — that would also pull unused server libraries (~260 MB).
Starts zephex init --terminal so you can sign in in the browser. It does not write Cursor / Claude / VS Code MCP config. Editor wiring is zephex connect --cursor (or npx -y zephex@latest setup --cursor).

By operating system

source ~/.zephex/env.sh

Windows — do not pipe the bash installer in cmd.exe. Use PowerShell:

irm https://zephex.dev/install.ps1 | iex

WSL or Git Bash: use the macOS/Linux curl line inside that Linux environment. Mixing C:\Users\…\.zephex with /home/you/.zephex is the usual break.

Cloud shells, phones, other OS

Google Cloud Shell, GitHub Codespaces, Railway / Render shells — use the same curl line. Those boxes often ship Node 18 or 20. The installer notices and downloads a private Node 22 under ~/.zephex/node instead of failing. Do not use npx zephex setup there unless node -v is already 22.5+.
Android (Termux) — curl + bash work. Same installer. Hosted commands still need HTTPS out to zephex.dev.
iPhone / iPad — there is no native zephex binary. Use the web terminal in Safari, or SSH into a Mac/Linux box that already has the CLI.
Windows ARM (Surface, Snapdragon) — PowerShell installer downloads the win-arm64 Node build. WSL on ARM uses the Linux arm64 curl line.

What the CLI talks to

Install download — Vercel serves install.sh / install.ps1. The CLI itself comes from the npm registry, not from Railway.
Sign-in — browser or QR hits zephex.dev/cli/auth (Vercel). Your user_id and key name are written to Supabase. The API key is stored only in ~/.zephex/credentials.json (mode 0600).
Tool commands (/overview, /architecture, …) go to the hosted MCP proxy on Railway (https://zephex.dev/mcp is the public URL). Credits and tool names are stored per user_id in usage_events.
Sentry — Railway captures hosted tool / API errors (tagged with CLI version). The local zephex process does not send your repo to Sentry.

After install — first commands

source ~/.zephex/env.shcd your-appzephex# type /overview   or   /help

Hosted tools need a live API key (dashboard keys or the browser sign-in the installer opens). /help and /learn work without a key. /frontend /auth /database /overview do not.

Upgrade

The curl script always installs npm zephex@latest (unless you pin ZEPHEX_VERSION). Re-run it, or:

zephex update # or re-run the installer (installs npm zephex@latest into ~/.zephex)curl -fsSL https://zephex.dev/cli/install.sh | bash # pin a versionZEPHEX_VERSION=2.5.13 curl -fsSL https://zephex.dev/cli/install.sh | bash

Check what you have: zephex info or zephex --version. If which zephex points at an old global npm (not ~/.zephex/bin/zephex), source ~/.zephex/env.sh or reopen the terminal.

This vs the homepage npx line

curl -fsSL https://zephex.dev/cli/install.sh | bash — install the terminal (Mode 2). No Node required on the machine first.
npx -p zephex mcpcli setup — editor MCP wizard (Mode 1). Needs Node already. Writes Cursor / Claude config.
You can use both with one API key. Install the CLI first, then zephex connect --cursor when you want the editor.

Uninstall

zephex uninstall           # PATH + credentialszephex uninstall --full    # delete entire ~/.zephex

If something looks stuck

command not found: zephex — source ~/.zephex/env.sh, then open a new tab.
Piped curl into bash: the installer cannot keep PATH in that parent shell. That is why it prints the source line.
Only run the script from zephex.dev— never a random gist.
Offline or corporate TLS intercept: the script needs HTTPS to zephex.dev (npm package) and, if Node is missing, nodejs.org.

More paths: all install methods · macOS · Linux · Windows · terminal CLI

Method 1 — npx (no global install)

# Recommended — always latest, skip npx cache and confirm promptnpx -y zephex@latest setup # Connect one editor (global config — works in every project)npx -y zephex@latest setup --cursornpx -y zephex@latest setup --antigravitynpx -y zephex@latest setup --opencode # After setup — verify and fix stdio pinsnpx -y zephex@latest doctornpx -y zephex@latest listnpx -y zephex@latest repair

Pros: No install. Pin @latest to avoid stale cache. No PATH changes.

Cons: First run takes ~5 seconds (downloads from npm). Type npx each time unless you install globally.

Method 2 — npm global install

Standard global install. Adds zephex to your PATH so you can type zephex without npx.

# Install oncenpm install -g zephex # Then run anywherezephex setupzephex listzephex tools # Update laternpm install -g zephex@latest

Pros: Type zephex instead of npx zephex. Faster startup (no download).

Cons: One install per Node version. May need sudo on some systems.

Method 3 — Bun

If you use Bun as your runtime, install zephex globally with Bun's package manager.

# Installbun install -g zephex # Runzephex setup # Or run via bunx (no install)bunx zephex setup

Pros: Bun is faster than Node for installs. Same binary as the npm version.

Cons: Requires Bun runtime installed.

Method 4 — pnpm

For pnpm users.

# Install globallypnpm add -g zephex # Runzephex setup # Or via pnpx (no install)pnpm dlx zephex setup

Method 5 — Docker

For users without Node.js, or those who want everything sandboxed. Run Zephex in a container without touching your host system.

Quick start with Docker

# Pull the latest imagedocker pull node:22-alpine # Run zephex setup inside a container, mounting your home dirdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex setup

This mounts your home directory into the container so the wizard can write the editor config files (~/.cursor/mcp.json, ~/.claude.json, etc.) to your real machine.

Run a specific command

# List installed editorsdocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex list # Run doctordocker run -it --rm \  -v "$HOME:/root" \  -w /root \  node:22-alpine \  npx -y zephex doctor

Make it easier with a shell alias

# Add to ~/.bashrc or ~/.zshrcalias zephex='docker run -it --rm -v "$HOME:/root" -w /root node:22-alpine npx -y zephex' # Then use like normalzephex setupzephex listzephex doctor

Build your own image

If you don't want to download the package every time, build a thin image with Zephex pre-installed:

FROM node:22-alpineRUN npm install -g zephexENTRYPOINT ["zephex"]

# Build it oncedocker build -t zephex-cli . # Run any commanddocker run -it --rm -v "$HOME:/root" -w /root zephex-cli setupdocker run -it --rm -v "$HOME:/root" -w /root zephex-cli list

Pros: No Node.js required on the host. Everything sandboxed. Cleanup is just deleting the container/image.

Cons: Slower startup (container boot). Need Docker installed. Volume mounts get tricky on Windows.

Method 6 — Manual JSON config (no Node.js, no Docker)

If you can't (or don't want to) install Node.js or Docker, you can write the editor config file by hand. The Zephex CLI is just a convenience — the actual MCP connection is HTTP-based.

Step 1: Get an API key

Sign in at zephex.dev/dashboard/keys with GitHub or Google. Click "Create Key", copy the value (starts with mcp_prod_).

Step 2: Find your editor's MCP config file

Editor             Config file path
──────────────────────────────────────────────────────────────────────────
Cursor             ~/.cursor/mcp.json
Claude Code        ~/.claude.json
VS Code            <project>/.vscode/mcp.json
Codex              ~/.codex/config.toml
OpenCode           ~/.config/opencode/opencode.json
Windsurf           ~/.codeium/windsurf/mcp_config.json
Zed                ~/.config/zed/settings.json
Warp               ~/.agents/.mcp.json
Gemini CLI         ~/.gemini/settings.json
Kiro               ~/.kiro/settings/mcp.json
Cline (VS Code)    Library/Application Support/Code/User/globalStorage/
                     saoudrizwan.claude-dev/settings/cline_mcp_settings.json
JetBrains          <project>/.junie/mcp/mcp.json
Kilo Code          Library/Application Support/Code/User/globalStorage/
                     kilocode.kilo-code/settings/mcp_settings.json
Amp                ~/.config/amp/settings.json
Continue           ~/.continue/config.yaml
GitHub Copilot CLI ~/.copilot/mcp-config.json
Factory Droid      ~/.factory/mcp.json
Claude Desktop     Library/Application Support/Claude/claude_desktop_config.json
Antigravity        ~/.gemini/antigravity/mcp_config.json
TRAE               <project>/.trae/mcp.json

Step 3: Add the Zephex entry

For most editors (Cursor, Claude Code, Windsurf, Zed, Kiro, Cline, Kilo, Copilot, Droid, Claude Desktop, Antigravity, TRAE):

{  "mcpServers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For VS Code (note servers not mcpServers):

{  "servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Zed (note context_servers):

{  "context_servers": {    "zephex": {      "url": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Antigravity (note serverUrl not url):

{  "mcpServers": {    "zephex": {      "serverUrl": "https://zephex.dev/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY_HERE"      }    }  }}

For Codex (TOML format, not JSON):

[mcp_servers.zephex]url = "https://zephex.dev/mcp" [mcp_servers.zephex.http_headers]Authorization = "Bearer YOUR_API_KEY_HERE"

Step 4: Restart your editor

Quit completely and reopen. The Zephex tools will appear in your editor's tool list.

Pros: No Node.js, no Docker, nothing installed. Works in airgapped or restricted environments.

Cons: You manage the file by hand. To update keys, you edit the file. You don't get the wizard's nice 3-step picker.

Comparison table

Method        Speed     Disk    Node?    Docker?    Best for
──────────────────────────────────────────────────────────────────────────────
npx           ●●○       ~0      Yes      No         Trying it once
npm -g        ●●●       ~5MB    Yes      No         Daily use, fast startup
bun -g        ●●●       ~5MB    Bun      No         Bun runtime users
pnpm -g       ●●●       ~5MB    Yes      No         pnpm workspace users
Docker        ●○○       ~120MB  No       Yes        No Node, sandboxed
Manual JSON   ●●●       ~0      No       No         No Node, no Docker, airgapped

Updating Zephex

If installed via curl / install.sh

zephex update# orcurl -fsSL https://zephex.dev/cli/install.sh | bash

If installed via npx

Always use @latest to bypass the npx cache:

npx zephex@latest setup

If installed via npm/bun/pnpm

# npmnpm install -g zephex@latest # bunbun install -g zephex@latest # pnpmpnpm add -g zephex@latest

If installed via Docker

# Pull a fresh node image (zephex is downloaded fresh each time with -y)docker pull node:22-alpine # Or rebuild your custom image if you made onedocker build -t zephex-cli --no-cache .

If installed via manual JSON

Nothing to update — you're calling the live https://zephex.dev/mcp endpoint directly. Just keep the API key valid and it works forever.

Uninstall

Remove just the Zephex config from your editors

# Remove from one editornpx zephex disconnect --cursor # Remove from every editornpx zephex disconnect --all # Full cleanup (config + skill + rule files)npx zephex reset --all

Uninstall the CLI itself

# npmnpm uninstall -g zephex # bunbun uninstall -g zephex # pnpmpnpm remove -g zephex # Docker — delete the imagedocker rmi zephex-cli

Common pitfalls (read before re-running setup)

Stale npm cache: use npx -y zephex@latest, not plain npx zephex.
Re-running setup too often: each OAuth run can mint a new API key — free tier allows 3 keys.
Editor not restarted: fully quit (Cmd+Q on Mac), not just close the window.
Works in terminal, fails in editor: GUI apps lack nvm/Homebrew on PATH — run npx -y zephex@latest repair.
Works in one repo, not another: project-level .vscode/mcp.json, opencode.json, or .mcp.json shadowing global — run global setup again or check npx -y zephex@latest list.
Antigravity: global path only (~/.gemini/antigravity/mcp_config.json); quit app fully and start a new agent session.

Full decision tree: MCP troubleshooting.

Where to next

Setup Walkthrough — visual guide to the wizard flow
CLI Commands Reference — every command explained
Supported Editors — config path for each editor
Plans — Free / Pro / Max tier comparison

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Install Methods — Pick the one that fits your environment

Decision flowchart

curl installer — terminal CLI (Mode 2)

What it does

By operating system

Cloud shells, phones, other OS

What the CLI talks to

After install — first commands

Upgrade

This vs the homepage npx line

Uninstall

If something looks stuck

Method 1 — npx (no global install)

Method 2 — npm global install

Method 3 — Bun

Method 4 — pnpm

Method 5 — Docker

Quick start with Docker

Run a specific command

Make it easier with a shell alias

Build your own image

Method 6 — Manual JSON config (no Node.js, no Docker)

Step 1: Get an API key

Step 2: Find your editor's MCP config file

Step 3: Add the Zephex entry

Step 4: Restart your editor

Comparison table

Updating Zephex

If installed via curl / install.sh

If installed via npx

If installed via npm/bun/pnpm

If installed via Docker

If installed via manual JSON

Uninstall

Remove just the Zephex config from your editors

Uninstall the CLI itself

Common pitfalls (read before re-running setup)

Where to next

Quick Links

API Reference

Troubleshooting

Community

Plugins

Pricing

Install Methods — Pick the one that fits your environment

Decision flowchart

curl installer — terminal CLI (Mode 2)

What it does

By operating system

Cloud shells, phones, other OS

What the CLI talks to

After install — first commands

Upgrade

This vs the homepage npx line

Uninstall

If something looks stuck

Method 1 — npx (no global install)

Method 2 — npm global install

Method 3 — Bun

Method 4 — pnpm

Method 5 — Docker

Quick start with Docker

Run a specific command

Make it easier with a shell alias

Build your own image

Method 6 — Manual JSON config (no Node.js, no Docker)

Step 1: Get an API key

Step 2: Find your editor's MCP config file

Step 3: Add the Zephex entry

Step 4: Restart your editor

Comparison table

Updating Zephex

If installed via curl / install.sh

If installed via npx