CLI Reference

Zeph uses clap for argument parsing. Run zeph --help for the full synopsis.

Usage

zeph [OPTIONS] [COMMAND]

Subcommands

When no subcommand is given, Zeph starts the agent loop.

zeph db

Manage database schema migrations.

zeph db migrate                    # apply pending migrations
zeph db migrate --status           # check what would be applied

zeph init

Generate a config.toml through a guided wizard.

zeph init                          # write to ./config.toml (default)
zeph init --output ~/.zeph/config.toml  # specify output path

Options:

zeph skill

Manage external skills. Installed skills are stored in ~/.config/zeph/skills/.

# Install from git
zeph skill install https://github.com/user/zeph-skill-example.git

# Install from local path
zeph skill install /path/to/my-skill

# List installed skills
zeph skill list

# Verify integrity and promote trust
zeph skill verify my-skill
zeph skill trust my-skill trusted

# Remove a skill
zeph skill remove my-skill

zeph memory

Manage conversation history and advanced memory subsystems.

# Back up all conversation data
zeph memory export backup.json

# Restore on another machine
zeph memory import backup.json

# Inspect trajectory entries
zeph memory trajectory

# Inspect memory tree state
zeph memory tree

The snapshot format is versioned (currently v1). Import uses INSERT OR IGNORE — re-importing the same file is safe and skips existing records.

zeph agents

Manage sub-agent definition files. See Managing Definitions for examples and field details.

# List all definitions (project and user scope)
zeph agents list

# Inspect a single definition
zeph agents show code-reviewer

# Create a project-scoped definition
zeph agents create reviewer --description "Code review helper"

# Create a user-scoped (global) definition
zeph agents create helper --description "General helper" --dir ~/.config/zeph/agents/

# Edit with $EDITOR
zeph agents edit reviewer

# Delete without confirmation prompt
zeph agents delete reviewer --yes

zeph vault

Manage age-encrypted secrets without manual age CLI invocations.

Default paths (created by vault init):

• Key file: ~/.config/zeph/vault-key.txt
• Vault file: ~/.config/zeph/secrets.age

Override with --vault-key and --vault-path global flags.

zeph vault init
zeph vault set ZEPH_CLAUDE_API_KEY sk-ant-...
zeph vault set ZEPH_TELEGRAM_TOKEN 123:ABC
zeph vault list
zeph vault get ZEPH_CLAUDE_API_KEY
zeph vault rm ZEPH_TELEGRAM_TOKEN

zeph migrate-config

Update an existing config file with all parameters added since it was last generated. Missing sections are appended as commented-out blocks with documentation. Existing values are never modified.

# Preview what would be added
zeph migrate-config --config config.toml --diff

# Apply in place
zeph migrate-config --config config.toml --in-place

# Print migrated config to stdout
zeph migrate-config --config config.toml

See Migrate Config for a full walkthrough.

zeph router

Inspect or reset the Thompson Sampling router state file.

Both subcommands accept --state-path <PATH> to override the default location (~/.zeph/router_thompson_state.json).

zeph router stats
zeph router reset
zeph router stats --state-path /custom/path.json

zeph schedule

Manage cron-based scheduled jobs from the command line. Requires the scheduler feature. All commands read the same SQLite database used by the running agent.

# List all scheduled jobs
zeph schedule list

# Add a daily cleanup job at 03:00 UTC
zeph schedule add "0 3 * * *" "run memory cleanup"

# Add with an explicit name and task kind
zeph schedule add "0 3 * * *" "run memory cleanup" --name daily-cleanup --kind memory_cleanup

# Show details of a job
zeph schedule show daily-cleanup

# Remove a job
zeph schedule remove daily-cleanup

schedule add options:

See Scheduler for the full list of built-in task kinds, cron expression formats, and how jobs are persisted.

zeph ingest

Ingest a document or directory of documents into semantic memory. Chunks the content and stores embeddings in the configured Qdrant collection.

# Ingest a single file
zeph ingest path/to/doc.md

# Ingest a directory with custom chunk settings
zeph ingest ./docs --chunk-size 500 --chunk-overlap 50 --collection my_docs

zeph classifiers

Manage ML classifier model weights. Requires the classifiers feature.

# Download all configured classifier models
zeph classifiers download

# Download only the prompt-injection classifier
zeph classifiers download --model injection

# Download a specific HuggingFace repo
zeph classifiers download --repo protectai/deberta-v3-base-prompt-injection-v2

# Increase download timeout (default: 600 seconds)
zeph classifiers download --timeout-secs 1200

classifiers download options:

Model files are cached in ~/.cache/huggingface/hub/. Run this before starting the agent to avoid slow first-inference downloads.

zeph sessions

Manage ACP session history. Requires the acp feature.

zeph sessions list
zeph sessions resume abc123
zeph sessions delete abc123

Interactive Commands

The following /-prefixed commands are available during an interactive session:

/agent

Manage sub-agents. See Sub-Agent Orchestration for details.

> /agent list
> /agent spawn code-reviewer Review the auth module
> /agent status
> /agent cancel a1b2
> /agent resume a1b2 Fix the remaining warnings
> @code-reviewer Review the auth module   # shorthand for /agent spawn

/lsp

Show LSP context injection status. Requires the lsp-context feature and mcpls configured under [[mcp.servers]].

> /lsp

/experiment

Manage experiment sessions. Requires the experiments feature. See Experiments for details.

> /experiment start
> /experiment start 50
> /experiment status
> /experiment stop
> /experiment report
> /experiment best

/log

Display the current file logging configuration and recent log entries.

> /log

See Logging for configuration details.

/migrate-config

Show a diff of config changes that migrate-config would apply. Opens the command palette entry config:migrate.

> /migrate-config

To apply changes, use the CLI: zeph migrate-config --config <path> --in-place.

See Migrate Config for details.

/new

Reset the current conversation while preserving session state (provider, skills, memory backend). Starts a fresh conversation with a new conversation ID without restarting the agent.

> /new

This is useful when you want to change topics without carrying over stale context from a long session.

/debug-dump

Enable debug dump mid-session without restarting.

> /debug-dump
> /debug-dump /tmp/my-session-debug

See Debug Dump for the file layout and how to read dumps.

Global Options

Examples

# Start the agent with defaults
zeph

# Start with a custom config
zeph --config ~/.zeph/config.toml

# Start with TUI dashboard
zeph --tui

# Start with age-encrypted secrets (default paths)
zeph --vault age

# Start with age-encrypted secrets (custom paths)
zeph --vault age --vault-key key.txt --vault-path secrets.age

# Initialize vault and store a secret
zeph vault init
zeph vault set ZEPH_CLAUDE_API_KEY sk-ant-...

# Generate a new config interactively
zeph init

# Start as headless daemon with A2A endpoint
zeph --daemon

# Connect TUI to a running daemon
zeph --connect http://localhost:3000