Command Reference

# Send a notification
zeph notify --title "Deploy done" --body "v2.1.0 shipped"

# Send with priority
zeph notify --title "Build failed" --priority high --url https://ci.example.com/123

# List recent pushes
zeph list
zeph list --limit 10 --type note

# Dismiss a push
zeph dismiss push_01JXY...
zeph dismiss --all

# Rename the current agent session (shows in the app's Agents list)
zeph rename "Prod deploy"
zeph rename --clear                # reset to the default name

# Test connection
zeph test

# Run an agent in a named tmux session, so the listener can reach it
zeph cc                       # claude
zeph codex                    # codex
zeph cursor                   # cursor-agent (Cursor CLI, not the IDE)
zeph gemini                   # gemini

# Run the resident listener (foreground; background it as you like)
zeph listener
zeph listener --ws-url wss://...   # override config

# JSON output
zeph notify --title "Hello" --json

Commands

Notify options

The defaults are tuned for hook-driven invocations — for example a Stop hook calling zeph notify --title "Task done" with no body. You see which project and branch finished without writing per-IDE wrappers. Pass --body "" explicitly to suppress it.

Listener options

The listener reconnects with exponential backoff plus jitter, from 1 second to a 30-second cap. The heartbeat is a ping every 25 seconds with a 10-second pong timeout. On an authentication failure close (4001, 4002, 4003) the listener exits with code 3 instead of looping forever — fix the key and restart.

List options

Global options

Mute and push mode

Both live as state files under ${XDG_STATE_HOME:-~/.local/state}/zeph, keyed by a cksum hash of the project directory. Claude Code's /zeph-mute, /zeph-quiet, /zeph-loud, and /zeph-normal write them; the CLI reads them — mute on every notify, push mode on --auto.

Notifications are silently skipped when a mute file exists for the current project:

STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/zeph"
HASH=$(printf '%s' "$PROJECT_DIR" | cksum | cut -d' ' -f1)

# Mute (created by /zeph-mute in the Claude Code plugin)
mkdir -p "$STATE_DIR" && touch "$STATE_DIR/muted-$HASH"

# Unmute
rm -f "$STATE_DIR/muted-$HASH"

Push mode is a one-word file — quiet, loud, or normal — resolved in this order, first hit wins:

Row 5 changed. An install with no dial anywhere used to be normal. It is now quiet, so upgrading turns the routine per-turn push off until you run /zeph-normal.

Row 4 is why the hooks this CLI installs are unaffected: they name normal themselves, since a hook that supplies no turn counts also supplies no high marker, and quiet would make it permanently silent rather than merely quieter. Row 4 sits below the state files on purpose — the flag names a default, it does not override a dial the user set.

A dial file that exists but reads empty resolves to normal, not to row 5. An empty file is a failed write, and resolving breakage to silence leaves no symptom to debug.

Mute has no -default form on purpose: it is keyed on presence, not content, so a global mute could never be lifted for a single project.

Legacy /tmp/zeph-muted-<hash> files are still honored when owned by the current user — the state directory moved out of world-writable /tmp.

The CLI checks CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR, and WINDSURF_PROJECT_DIR, and falls back to the cwd.

Exit codes

Environment variables