Zephr Docs

CLI commands

Generated reference — do not edit by hand.

Generated from the routed CLI command switch and checked command metadata.

CommandGroupDescription
connectBootstrapJ1 cold-start: auth, project, MCP config, admission, recall
hostsConnectEmit a host-pack from the declarative platform-integration schema
connect-hooksBootstrapLifecycle-hook installation surface; real installer is zephr hook install --write
initBootstrapFirst-run: OAuth login, project setup, zephrd install
loginBootstrapAuthenticate via device flow (RFC 8628)
healthStateCheck zephrd status and MCP handshake
recallSourceQuick recall test against your memories
timelineMemoryChronological session context (recall ladder L2) — handles, never full content
observationsMemoryRecall ladder L3: fetch verbatim L0 observations by explicit ID
packContinuityExport a signed Memory Pack of a worktree's beliefs
unpackContinuityVerify and import a Memory Pack into a worktree
handoffContinuityMint a signed Continuity v1.1 handoff packet
resumeContinuityImport a handoff via the shared import pipeline
receiptsContinuityExport the installation's Slipstream audit receipts
audit-packContinuityAssemble a per-day audit pack with covering Merkle roots and proofs
uninstallExtensibilityRemove local Zephr data (preserves SQLite backups)
roleTrustList available agent roles
statusStateShow runtime state, daemon health, and current project
mcpBootstrapWrite the Zephr MCP server into agent CLI configs
importConnectDetect local agent-tool config and push an adopt manifest to the cloud engine.
hookExtensibilityShow the lifecycle hook capability matrix
doctorStateRun on-box diagnostics (binary, daemon, handshakes)
rememberEvidenceCapture a belief (composed-of the on-box store)
noteEvidenceCapture a quick human note as an L0 observation (opt-in tap)
tapsExtensibilityDev-native capture taps: honest readiness, ingest drain, shell hook snippet
whyEvidenceExplain provenance of a belief version
preflightEvidencePlan-time advisory verification (shape + belief-graph link check)
verifyEvidenceVerify a belief's structural (T1) + consistency (T2)
verify-claimEvidenceAlias for verify
proveContinuityVerify a Continuity packet and emit a provenance assertion
grepSourceSearch files in an admitted worktree (gitignore-aware)
searchSourceUnified search across admitted worktrees
daemonStateStart the zephrd sidecar daemon
upgradeStateCheck current vs latest zephrd release (no download)
integrationsConnectList installed integration connections + status
notificationsConnectList the notification feed (newest first)
shareSourceMint a signed read-only URL for a memory excerpt (7d TTL)
workspaceConnectPortable agent workspace (Phase 1: Tier-1 deep surface)
profileConnectSwitchable agent-config bundles (fleet-profile manager)
powerConnectHost-lane preview: print official knobs; --yes writes Codex TOML only
sourcesConnectDeclare a loopback openai-compatible source (IPv4/IPv6 loopback only)
agentExtensibilityCreate, run, list and inspect autonomous agents.
syncConnectThe unified reconciliation loop over the canonical WorkspaceSnapshot.
reviewTrustRun an LLM-augmented governed review of a code change.
skillsSurfacesShow a skill's header + markdown body
toolsSurfacesList the daemon's tool catalog (tier + pin)
memorySurfacesRender the scope lattice as a live tree
continuitySurfacesPer-agent state + convergence score
signalConnectProvision an encrypted webhook secret + register producers
extensionConnectValidate a zephr.extension.json + verify the sha512 pin
agent-cardConnectValidate (fetch + SSRF-safe reachability + schema) and
activateStateProject-grounded MCP/skill activation plan (read-only/dry-run, config via get|set|reset)
filesSourceUser-file vault (list / read-markdown / governed erase / upload-init)
constraintTrustHuman-gated governance constraint surface (ZEP-1941 W6): CRUD, promote/demote, evaluate-shadow, confirm-from-edge, waiver create. Durable writes go through injected @zephr-ai/governance ports.
podSurfacesCompute-plane pods — list, show, launch, terminate, pause, resume, logs, exec, mcp, acp, egress-audit (devpod is a deprecated alias handled inside the CLI)
devpodSurfacesPhase-2 devpod stub — enqueue profile materialization for a fleet profile
piConnectDetect, project, and launch Pi (pi.dev); mint a signed handoff on exit [--mode] [--profile] [--dry-run]
dshStateInspect or launch the local DeepSeek Harness loadout
tasteSurfacesPerson-scoped coding conventions — enable / disable / export / reset
usageStateAccount + review-specific spend from the billing ledger (usage review)
sessionStateSession tooling: per-session token ledger (tokens, cache split, compactions)

Usage

Every form zephr --help lists, grouped by command.

connect

UsageDescription
zephr connect [--force]J1 cold-start: auth, project, MCP config, admission, recall

hosts

UsageDescription
zephr hosts install <platform> [--target <dir>] [--yes] [--dry-run] [--json]Render + install a host pack (config-safe merge)
zephr hosts emit <platform> [--target <dir>] [--json]Alias for install (local render + write)
zephr hosts update <platform> [--target <dir>] [--yes] [--json]Re-render a pack, preserving user edits (merge)
zephr hosts uninstall <platform> [--target <dir>] [--yes] [--json]Remove only Zephr-managed artifacts (marker-scoped)
zephr hosts doctor [<platform>] [--target <dir>] [--json]Report installed host-pack health
zephr hosts dry-run <platform> [--target <dir>] [--json]Plan an install without writing anything
zephr hosts receipts [--target <dir>] [--json]Show the host lifecycle receipt register

connect-hooks

UsageDescription
zephr connect-hooksInstall claude-code session-capture hooks (alias for hook install --write)

init

UsageDescription
zephr init [--test]First-run: OAuth login, project setup, zephrd install

login

UsageDescription
zephr login [--test]Authenticate via device flow (RFC 8628)

health

UsageDescription
zephr healthCheck zephrd status and MCP handshake

recall

UsageDescription
zephr recall <query>Quick recall test against your memories

pack

UsageDescription
zephr pack <worktreeId> <outputPath>Export a signed Memory Pack of a worktree's beliefs
zephr pack export <scope> <outputPath>Alias: export a Memory Pack for a scope
zephr pack import <file> [scope]Alias: verify and import a Memory Pack

unpack

UsageDescription
zephr unpack <packPath> [worktreeId]Verify and import a Memory Pack into a worktree

handoff

UsageDescription
zephr handoff <worktreeId> [--file <path>|--registry|--claim-code]Mint a signed Continuity v1.1 handoff envelope

resume

UsageDescription
zephr resume <claim-code|packet-id|file-path>Import a handoff via the shared import pipeline

receipts

UsageDescription
zephr receipts export [--out <path>] [--limit <n>]Export the installation's Slipstream audit receipts

uninstall

UsageDescription
zephr uninstall [--force]Remove local Zephr data (preserves SQLite backups)

role

UsageDescription
zephr role listList available agent roles
zephr role show <slug>Show role details
zephr role use <slug>Set active role

status

UsageDescription
zephr status [--json]Show connection + role status

mcp

UsageDescription
zephr mcp install[--client <name|all>] [--dry-run] [--yes] [--skip-verify]Write the Zephr MCP server into agent CLI configs
zephr mcp listShow MCP client config targets and their state
zephr mcp uninstall [--client <name|all>] [--yes]Remove only Zephr's MCP entries (marker-scoped)
zephr mcp update [--client <name|all>] [--yes]Re-pin the Zephr MCP entry (config-safe merge)
zephr mcp receipts [--json]Show the MCP lifecycle receipt register

hook

UsageDescription
zephr hook matrixShow the lifecycle hook capability matrix
zephr hook install [--client <name|all>] [--json] [--write] [--project-dir <dir>]Plan (or write) phase-1 lifecycle hooks per client
zephr hook update [--client <name|all>] [--write]Re-plan/re-write hooks (config-safe, idempotent)
zephr hook dry-run [--client <name|all>] [--json]Preview the install plan without writing
zephr hook uninstall [--client <name|all>] [--json]Remove only Zephr-managed hook files
zephr hook probe [--client <name|all>] [--version <v>] [--json]Canary probe: detect a stale hook matrix/binary
zephr hook drain [--json]Persist hook-spool JSONL into local L0/L1 (not during connect)

doctor

UsageDescription
zephr doctor [--json]Run on-box diagnostics (binary, daemon, handshakes, host packs)

remember

UsageDescription
zephr remember <text> [--worktree <id>] [--kind <kind>] [--json]Capture a belief (composed-of the on-box store)

taps

UsageDescription
zephr taps status [--json]Per-tap readiness (disabled taps report "absent", never "ready")
zephr taps drain [--json]One ingest pass over every enabled tap into local L0
zephr taps install-hookPrint the shell-hook snippet to eval from your shell rc

why

UsageDescription
zephr why --claim-id <id> [--worktree <id>] [--json]Explain provenance of a belief version

verify

UsageDescription
zephr verify --claim-id <id> [--worktree <id>] [--json]Verify a belief's structural (T1) + consistency (T2)

verify-claim

UsageDescription
zephr verify-claim --claim <id> [--worktree <id>] [--json]Alias for verify

prove

UsageDescription
zephr prove <packet.json> [--out <path>]Emit a C2PA-aligned (NOT certified) provenance assertion

grep

UsageDescription
zephr grep --pattern <regex> [--worktree <id>] [--types ts,tsx] [--max 50] [--context 0]Search files in an admitted worktree (gitignore-aware)
UsageDescription
zephr search --query <query> [--worktree <id>] [--mode auto|lexical|structural|semantic|hybrid]Unified search across admitted worktrees

daemon

UsageDescription
zephr daemon startStart the zephrd sidecar daemon
zephr daemon stopStop the zephrd sidecar daemon
zephr daemon statusShow daemon reachability + uptime
zephr daemon logsTail the daemon log file

upgrade

UsageDescription
zephr upgrade [--check]Check current vs latest zephrd release (no download)

integrations

UsageDescription
zephr integrations list [--json]List installed integration connections + status
zephr integrations status [--json]Health snapshot per installed integration
zephr integrations install <id> [--channel <kind>:<target>]Headless install (creates a channel binding)
zephr integrations remove <id>Disconnect (remove) an integration connection

notifications

UsageDescription
zephr notifications list [--limit N] [--json]List the notification feed (newest first)
zephr notifications read [--all] | <id...>Mark notifications read (--all, or by id)
zephr notifications subscribe --channel <kind>:<target> [--event <type>]Create a channel binding for this installation

share

UsageDescription
zephr share --text <text> [--id <id>] [--ttl <days>] [--base-url <url>] [--json|--human]Mint a signed read-only URL for a memory excerpt (7d TTL)

workspace

UsageDescription
zephr workspace import|push|showPortable agent workspace (Phase 1: Tier-1 deep surface)

profile

UsageDescription
zephr profile list|show|switch|clone|try|keep|revert|export|importSwitchable agent-config bundles (fleet-profile manager)

power

UsageDescription
zephr power on|off|status [--host <dialect>] [--yes]Host-lane preview: print official knobs; --yes writes Codex TOML only

sources

UsageDescription
zephr sources add --kind openai-compatible --base-url <loopback> [--probe] [--test]Declare a loopback openai-compatible source (IPv4/IPv6 loopback only)

skills

UsageDescription
zephr skills show <name>Show a skill's header + markdown body
zephr skills install <src>Install a skill from path or git URL [--scope] [--pin]
zephr skills check [--fix]Validate skills against the extended manifest schema
zephr skills syncDiff-preview then sync discovered skills
zephr skills publish <path>Publish a skill [--validate] [--fix]

tools

UsageDescription
zephr tools listList the daemon's tool catalog (tier + pin)
zephr tools describe <name>Show a tool's schema, side effects, examples
zephr tools run <name>Run a daemon tool [--args] [--input=@file] [--output fmt]
zephr tools validateDetect schema drift between local catalog and daemon

memory

UsageDescription
zephr memory treeRender the scope lattice as a live tree
zephr memory show <id>Walk the supersession lineage for <id>
zephr memory driftFind stale claims (user-configurable threshold)
zephr memory auditExport the signed memory ledger
zephr memory export <worktree-id> --output <path>Write a Memory Pack for a worktree
zephr memory retract <claim-id> --reason <text> [--confirm]Retract a memory (destructive when confirmed)
zephr memory forget (--before T | --person P | --app A | --topic T) --subject <id> [--holder <id>] [--dry-run]Preview or erase one data subject's matching memories
zephr memory cascade --capture <id> [--limit N] [--offset N] [--apply --confirm <digest>]Preview a cascade; apply is gated by --confirm <digest>

continuity

UsageDescription
zephr continuity reportPer-agent state + convergence score
zephr continuity conflictDivergent claims with resolution hints
zephr continuity retract <id>Retract across agents [--reason TEXT]
zephr continuity migrateMigrate from mem0|zep|openmemory|cursor|copilot|letta|langmem|cognee|chatgpt

signal

UsageDescription
zephr signal connect [github] --secret <hex>Provision an encrypted webhook secret + register producers
zephr signal list [--json]List registered signal producers + provisioning state

extension

UsageDescription
zephr extension install <manifest> --artifact <path|url>Validate a zephr.extension.json + verify the sha512 pin
zephr extension list [--json]List installed extensions
zephr extension uninstall <id>Revoke an extension (sets revoked_at, keeps the row)

agent-card

UsageDescription
zephr agent-card register <url> --consent-token <uuid> [--name <name>]Validate (fetch + SSRF-safe reachability + schema) and
zephr agent-card list [--json]List registered Agent Cards (active + revoked)
zephr agent-card revoke <id>Revoke an Agent Card (sets revoked_at, keeps the row)
zephr agent-card list|register|revokeA2A Agent Card catalog (consumer/hub)

files

UsageDescription
zephr files ls|read|rm|uploadUser-file vault (list / read-markdown / governed erase / byte upload)

constraint

UsageDescription
zephr constraint create|promote|shadow|smoke|helpGovernance constraint ladder (ZEP-1941 W6)

pod

UsageDescription
zephr pod list|show|launch|terminate|pause|resume|logs|exec|service|mcp|acp|egress-auditCompute-plane pods (devpod is a deprecated alias)

devpod

UsageDescription
zephr devpod launch --profile <id>Phase-2 stub: enqueue profile materialization

pi

UsageDescription
zephr pi [--mode <mode>] [--profile <id>] [--dry-run]Detect, project, launch Pi (pi.dev); mint a handoff on exit

dsh

UsageDescription
zephr dsh [--doctor|--dry-run] [--] [args]Launch local DeepSeek Harness

taste

UsageDescription
zephr taste enable|disable|list|open|push|pull|distill|lint|resetPerson-scoped coding conventions (not workspace)

usage

UsageDescription
zephr usage review [--json] [--reject]Account + review-specific spend from the billing ledger

session

UsageDescription
zephr session ledger <id> [--json] [--transcript <path>]Guest-mode session token ledger (hook spool + transcript)