CLI & SDK

Your agent works, hits a decision, and asks your phone. You tap a button (or type a reply), and the answer lands back in the live session — so the agent keeps going.

@zeph-to/cli is the terminal side of that round trip:

• ZephHook SDK — native fetch, no runtime dependencies. Send, list, and dismiss pushes.
• zeph CLI — one-command setup for 8 agents, push sending, and the resident listener that lets your phone drive Claude Code / Codex / Cursor / Gemini sessions.

Quick start

Install the CLI globally, then run setup:

npm install -g @zeph-to/cli
zeph install

zeph install opens a browser sign-in on a fresh machine — the web app issues an API key and a hook as a matched pair, and the CLI writes them to ~/.zeph/config.json. No copy-paste. It then installs rules, hooks, and MCP for every detected agent.

Re-running is safe: a saved login is reused untouched, so a re-run just refreshes the agent integrations. To switch accounts, zeph install --relogin forces a fresh sign-in.

Why global instead of npx

zeph cc — driving a session from your phone — needs zeph on your PATH, and the agent hooks this installs resolve as $(command -v zeph || npx …). A global binary skips an npx cold start on every notification.

For notifications only, with no phone control, npx @zeph-to/cli install is a lighter alternative that skips the global binary.

Install variants

# Headless box with no browser: paste credentials from another machine's ~/.zeph/config.json
zeph install --key ak_... --hook hook_...

# Skip the interactive agent picker
zeph install --only claude,cursor

# Switch account — force a fresh browser sign-in over a saved login
zeph install --relogin

# Refresh credentials only, without re-installing agents. This assumes you already ran
# `zeph install` once; on its own it does NOT wire MCP into agents.
zeph login

Send your first push

zeph notify --title "Deploy done" --body "v2.1.0 shipped"

What happens after install

The hooks fire in every session of each configured agent. zeph cc is the phone-control bridge, not the notification switch.

In Claude Code the routine per-turn push starts off — quiet is the default. /zeph-normal turns it on for a project, /zeph-loud pushes on every turn, /zeph-mute silences a project entirely, and /zeph-status shows what is in effect. See Mute and push mode.

~/.zeph/config.json is the single source of truth — the CLI, the MCP server, the plugin hooks, and the listener all read it. You never need ZEPH_API_KEY-style environment variables for a normal setup; they exist as overrides for a second account or CI.

Supported agents

zeph install detects and configures these automatically:

Remote control via zeph listener covers a smaller set — Claude Code, Codex, Cursor, and Gemini, the four that can be driven inside tmux. The wrapper just spawns each in a named tmux session, and the setup is identical but for one gap: Cursor has no remote-origin hook, so a zeph cursor session never enters sticky REMOTE mode on its own. See Remote Control.

Requirements

• Node.js 18 or newer (uses native fetch).
• tmux — required for zeph cc / codex / cursor / gemini and for zeph listener.
• The ZephHook SDK has no runtime dependencies. The CLI depends on @inquirer/prompts for the interactive zeph install picker and on ws for the listener's WebSocket subscription.