Skip to navigation
IntegrationsDeveloper Tools

zepctl CLI reference

Administer users, threads, Context Graphs, and data from a terminal

zepctl is a command-line interface for administering Zep projects. It provides full access to Zep, enabling you to manage users, threads, Context Graphs, and data operations from the terminal.

zepctl uses the v3 API and the v3 identifier model. The user, thread, and graph commands, and the --user and --graph flags, address resources by the user_id, thread_id, and graph_id values that an application gave them in v3. zepctl cannot address a user, thread, or graph that the v4 API created, because such a resource has no legacy name. Refer to Migrating from v3 for the v4 identifier model.

Installation

Homebrew (macOS/Linux)

brew tap getzep/zepctl https://github.com/getzep/zepctl.git
brew install zepctl

Binary Download

Download the appropriate binary for your platform from the releases page.

macOS users: If you see “zepctl cannot be opened because the developer cannot be verified”, run:

xattr -d com.apple.quarantine /path/to/zepctl

Quick Start

# Configure your API key (you will be prompted to enter it securely)
zepctl config add-profile production
# Verify connection
zepctl project get
# List users
zepctl user list

Authentication

Environment Variables

VariableDescription
ZEP_API_KEYAPI key for authentication
ZEP_API_URLAPI endpoint URL (default: https://api.getzep.com)
ZEP_PROFILEOverride current profile
ZEP_OUTPUTDefault output format
ZEP_PROJECTOverride the active project UUID

Configuration File

Location: ~/.zepctl/config.yaml

current-profile: production
profiles:
  - name: production
    # API keys are stored securely in the system keychain
  - name: development
    api-url: https://api.dev.getzep.com  # Optional: only if using non-default URL
defaults:
  output: table
  page-size: 50

API keys are stored in the system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) rather than in the config file. For CI/CD environments without keychain access, use the ZEP_API_KEY environment variable.

Interactive login

Use bearer-token authentication for policy-set, API-key, and interactive project commands:

zepctl auth login
zepctl auth status
zepctl auth logout

Use zepctl auth login --no-browser in a headless shell.

Global Flags

FlagShortDescription
--api-key-kOverride API key
--api-urlOverride API URL
--profile-pUse specific profile
--projectOverride the active project UUID for this command
--output-oOutput format: table, json, yaml, wide
--quiet-qSuppress non-essential output
--verbose-vEnable verbose output
--help-hDisplay help

Commands

config

Manage zepctl configuration including profiles and defaults.

# View current configuration
zepctl config view
# List all profiles
zepctl config get-profiles
# Switch active profile
zepctl config use-profile <name>
# Add a new profile (prompts for API key)
zepctl config add-profile <name> [--api-url URL]
# Remove a profile
zepctl config delete-profile <name> [--force]
# Set the active project
zepctl config set-project [uuid]

project

Get project information.

zepctl project get

user

Manage users in your Zep project.

# List users
zepctl user list [--page N] [--page-size N]
# Get user details
zepctl user get <user-id>
# Create a new user
zepctl user create <user-id> [--email EMAIL] [--first-name NAME] [--last-name NAME] \
  [--metadata JSON] [--metadata-file PATH]
# Update an existing user
zepctl user update <user-id> [--email EMAIL] [--first-name NAME] [--last-name NAME] \
  [--metadata JSON] [--metadata-file PATH]
# Delete a user (includes all associated data)
zepctl user delete <user-id> [--force]
# List user threads
zepctl user threads <user-id>
# Get user graph node
zepctl user node <user-id>

Deleting a user removes all associated threads, graph data, and knowledge. This supports RTBF (Right to Be Forgotten) compliance.

thread

Manage conversation threads.

# List all threads
zepctl thread list [--page N] [--page-size N] [--order-by FIELD] [--asc]
# Create a new thread
zepctl thread create <thread-id> --user <user-id>
# Get thread messages
zepctl thread get <thread-id> [--last N]
# Delete a thread
zepctl thread delete <thread-id> [--force]
# List thread messages
zepctl thread messages <thread-id> [--last N] [--limit N]
# Add messages to a thread
zepctl thread add-messages <thread-id> --file messages.json [--batch] [--wait]
zepctl thread add-messages <thread-id> --stdin [--batch] [--wait]
# Get thread context
zepctl thread context <thread-id>

List Flags

FlagDescription
--pagePage number (default: 1)
--page-sizeResults per page (default: 50)
--order-byOrder by field: created_at, updated_at, user_id, thread_id
--ascSort in ascending order (default: descending)

Message Format

When adding messages via --file or --stdin, use this JSON format:

{
  "messages": [
    {
      "role": "user",
      "name": "Alice",
      "content": "Hello, I need help with my account"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help!"
    }
  ]
}

graph

Manage user graphs and shared Context Graphs. Use --user for a graph that is addressed with user_id. Use --graph or a positional graph ID for a shared Context Graph that is addressed with graph_id.

# List all graphs
zepctl graph list [--page N] [--page-size N]
# Create a new graph
zepctl graph create <graph-id>
# Delete a graph
zepctl graph delete <graph-id> [--force]
# Clone a graph
zepctl graph clone --source-user USER_ID --target-user NEW_USER_ID
zepctl graph clone --source-graph GRAPH_ID --target-graph NEW_GRAPH_ID
# Add data to a graph
zepctl graph add <graph-id> --type text --data "User prefers dark mode"
zepctl graph add --user <user-id> --type json --file data.json
zepctl graph add --user <user-id> --batch --file episodes.json --wait
# Add a fact triple to a graph
zepctl graph add-fact --user <user-id> --fact "Alice knows Bob" --fact-name KNOWS \
  --source-node "Alice" --target-node "Bob"
zepctl graph add-fact --graph <graph-id> --fact "Alice works at Acme" --fact-name WORKS_AT \
  --source-node "Alice" --target-node "Acme" \
  --source-attrs '{"role": "engineer"}' --edge-attrs '{"since": "2020"}' \
  --target-attrs '{"industry": "tech"}'
# Search a graph
zepctl graph search "query" --user <user-id> --scope edges
zepctl graph search "query" --graph <graph-id> --scope nodes --limit 20
zepctl graph search "query" --user <user-id> --property-filter "status:=:active"
zepctl graph search "query" --user <user-id> --date-filter "created_at:>:2024-01-01"
# Detect structural patterns
zepctl graph detect-patterns --user <user-id>
zepctl graph detect-patterns --graph <graph-id> --limit 20

Add Data Flags

FlagDescription
--typeData type: text, json, message (default: text)
--dataInline data string
--filePath to data file
--stdinRead data from stdin
--userAdd to user graph
--batchEnable batch processing
--waitWait for ingestion to complete

Add Fact Flags

FlagDescription
--userAdd to user graph
--graphAdd to shared Context Graph
--factThe fact relating the two nodes (required)
--fact-nameEdge name, should be UPPER_SNAKE_CASE (required)
--source-nodeSource node name (required)
--target-nodeTarget node name (required)
--valid-atWhen the fact becomes true (ISO 8601)
--invalid-atWhen the fact stops being true (ISO 8601)
--source-attrsSource node attributes as JSON
--edge-attrsEdge attributes as JSON
--target-attrsTarget node attributes as JSON

Search Flags

FlagDescription
--userSearch user graph
--graphSearch shared Context Graph
--scopeSearch scope: edges, nodes, episodes, observations, thread_summaries, or auto (default: edges)
--limitMaximum results (default: 10)
--rerankerReranker: rrf, mmr, cross_encoder
--mmr-lambdaMMR diversity/relevance balance (0-1)
--max-charactersCharacter budget for scope=auto
--return-raw-resultsInclude selected raw results with scope=auto
--node-labelsComma-separated node labels to include
--edge-typesComma-separated edge types to include
--exclude-node-labelsComma-separated node labels to exclude
--exclude-edge-typesComma-separated edge types to exclude
--property-filterProperty filter (repeatable): property:op:value or property:IS NULL
--date-filterDate filter (repeatable): field:op:date or field:IS NULL

Property Filter Syntax

Property filters allow filtering by node/edge attributes:

--property-filter "property_name:operator:value"
--property-filter "property_name:IS NULL"
--property-filter "property_name:IS NOT NULL"

Supported operators: =, ==, <>, !=, >, <, >=, <=, IS NULL, IS NOT NULL

Values are automatically parsed as boolean (true/false), integer, float, or string.

Date Filter Syntax

Date filters allow filtering by temporal fields:

--date-filter "field:operator:date"
--date-filter "field:IS NULL"
--date-filter "field:IS NOT NULL"

Supported fields: created_at, valid_at, invalid_at, expired_at

Batch Episode Format

{
  "episodes": [
    {"type": "text", "data": "User prefers morning meetings"},
    {"type": "json", "data": "{\"preference\": \"dark_mode\"}"},
    {"type": "message", "data": "Alice: I love hiking on weekends"}
  ]
}

node

Manage graph nodes.

# List nodes
zepctl node list --user <user-id> [--limit N] [--cursor UUID]
zepctl node list --graph <graph-id>
# Get node details
zepctl node get <uuid>
# Update a node
zepctl node update <uuid> --name "New Name" --summary "New summary"
# Get node edges
zepctl node edges <uuid>
# Get node episodes
zepctl node episodes <uuid>
# Delete a node
zepctl node delete <uuid> [--force]

edge

Manage graph edges (facts/relationships).

# List edges
zepctl edge list --user <user-id> [--limit N] [--cursor UUID]
zepctl edge list --graph <graph-id>
# Get edge details
zepctl edge get <uuid>
# Update an edge
zepctl edge update <uuid> --fact "Updated fact" --name "NEW_RELATION"
# Delete an edge
zepctl edge delete <uuid> [--force]

episode

Manage graph episodes (source data).

# List episodes
zepctl episode list --user <user-id> [--last N]
zepctl episode list --graph <graph-id>
# Get episode details
zepctl episode get <uuid>
# Get episode mentions
zepctl episode mentions <uuid>
# Delete an episode
zepctl episode delete <uuid> [--force]

task

Monitor async operations (batch imports, cloning, etc.).

# Get task status
zepctl task get <task-id>
# Wait for task completion
zepctl task wait <task-id> [--timeout 5m] [--poll-interval 1s]

ontology

Manage graph schema definitions.

# Get ontology definitions
zepctl ontology get
# Set ontology from file
zepctl ontology set --file ontology.yaml

Ontology File Format

entities:
  Customer:
    description: "A customer of the business"
    fields:
      tier:
        description: "Customer tier level"
      account_number:
        description: "Customer account number"
  Product:
    description: "A product or service"
    fields:
      sku:
        description: "Product SKU"
edges:
  PURCHASED:
    description: "Customer purchased a product"
    source_types: [Customer]
    target_types: [Product]
  INTERESTED_IN:
    description: "Customer expressed interest"

summary-instructions

Manage user summary instructions.

# List instructions
zepctl summary-instructions list [--user USER_ID]
# Add instructions
zepctl summary-instructions add --name NAME --instruction "Text" [--user USER_IDS]
zepctl summary-instructions add --name NAME --file instructions.txt [--user USER_IDS]
# Delete instructions
zepctl summary-instructions delete <name> [--force] [--user USER_IDS]

observation

List and inspect derived observations:

zepctl observation list --user <user-id> [--limit N] [--cursor UUID]
zepctl observation list --graph <graph-id>
zepctl observation get <uuid>

thread-summary

List incremental thread summaries:

zepctl thread-summary list --user <user-id> [--limit N] [--cursor UUID]
zepctl thread-summary list --graph <graph-id>

policy-set and api-key

These commands require zepctl auth login and an active project:

zepctl policy-set list
zepctl policy-set create --file path/to/spec.yaml
zepctl policy-set validate --file path/to/spec.yaml
zepctl api-key list
zepctl api-key settings set <key-uuid> --mode <off|report_only|enforce>
zepctl api-key policy-sets attach <key-uuid> <policy-set-uuid>
zepctl api-key evaluate <key-uuid> --action <name>

Examples

Export All Users

zepctl user list -o json | jq '.users[].user_id'

Bulk User Creation

cat users.json | jq -c '.[]' | while read user; do
  zepctl user create $(echo $user | jq -r '.user_id') \
    --email "$(echo $user | jq -r '.email')" \
    --first-name "$(echo $user | jq -r '.first_name')"
done

Migrate User Data

# Clone user graph to test environment
zepctl graph clone --source-user prod_user_123 --target-user test_user_123
# Verify clone
zepctl node list --user test_user_123 -o json | jq '.nodes | length'

Monitor Batch Import

# Start batch import
TASK_ID=$(zepctl graph add --user user_123 --batch --file data.json -o json | jq -r '.task_id')
# Wait for completion
zepctl task wait $TASK_ID --timeout 10m

Delete User (RTBF Compliance)

# Preview what will be deleted
zepctl user get $USER_ID
zepctl user threads $USER_ID
# Delete user and all associated data
zepctl user delete $USER_ID --force

Search with Advanced Filters

# Search with cross-encoder reranking
zepctl graph search "critical decisions" --user user_123 --reranker cross_encoder
# Search nodes excluding certain labels
zepctl graph search "product" --graph graph_456 --scope nodes \
  --exclude-node-labels "Assistant,Document"
# Search with property filters
zepctl graph search "query" --user user_123 \
  --property-filter "status:=:active" \
  --property-filter "age:>:30"
# Search for edges with null validity dates
zepctl graph search "query" --user user_123 \
  --date-filter "valid_at:IS NULL" \
  --date-filter "created_at:>:2024-01-01"
# Combine multiple filter types
zepctl graph search "preferences" --user user_123 \
  --node-labels "Person,Product" \
  --property-filter "verified:=:true" \
  --date-filter "expired_at:IS NULL"

Output Formats

All commands support multiple output formats via the --output flag:

FormatDescription
tableHuman-readable table (default)
jsonJSON output for scripting
yamlYAML output
wideExtended table with additional columns
# JSON output for scripting
zepctl user list -o json
# YAML output
zepctl user get user_123 -o yaml

Shell Completions

Enable tab completion for commands, flags, and arguments.

Bash

Requires the bash-completion package.

# Load completions in current session
source <(zepctl completion bash)
# Install permanently (Linux)
zepctl completion bash > /etc/bash_completion.d/zepctl
# Install permanently (macOS with Homebrew)
zepctl completion bash > $(brew --prefix)/etc/bash_completion.d/zepctl

Zsh

# Enable completions if not already configured
echo "autoload -U compinit; compinit" >> ~/.zshrc
# Load completions in current session
source <(zepctl completion zsh)
# Install permanently (Linux)
zepctl completion zsh > "${fpath[1]}/_zepctl"
# Install permanently (macOS with Homebrew)
zepctl completion zsh > $(brew --prefix)/share/zsh/site-functions/_zepctl

Fish

# Load completions in current session
zepctl completion fish | source
# Install permanently
zepctl completion fish > ~/.config/fish/completions/zepctl.fish

PowerShell

# Load completions in current session
zepctl completion powershell | Out-String | Invoke-Expression
# Install permanently (add to your PowerShell profile)
zepctl completion powershell > zepctl.ps1
# Then add `. /path/to/zepctl.ps1` to your profile

Start a new shell session after installing completions for changes to take effect.