zepctl CLI Reference | Zep Documentation

zepctl is a command-line interface for administering Zep projects. It provides comprehensive access to Zep’s context engineering platform, enabling you to manage users, threads, knowledge graphs, and data operations from the terminal.

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

Variable	Description
`ZEP_API_KEY`	API key for authentication
`ZEP_API_URL`	API endpoint URL (default: `https://api.getzep.com`)
`ZEP_PROFILE`	Override current profile
`ZEP_OUTPUT`	Default output format

Configuration File

Location: ~/.zepctl/config.yaml

1 current-profile: production
2 profiles:
3   - name: production
4     # API keys are stored securely in the system keychain
5   - name: development
6     api-url: https://api.dev.getzep.com  # Optional: only if using non-default URL
7 defaults:
8   output: table
9   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.

Global Flags

Flag	Short	Description
`--api-key`	`-k`	Override API key
`--api-url`		Override API URL
`--profile`	`-p`	Use specific profile
`--output`	`-o`	Output format: `table`, `json`, `yaml`, `wide`
`--quiet`	`-q`	Suppress non-essential output
`--verbose`	`-v`	Enable verbose output
`--help`	`-h`	Display 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]

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

Flag	Description
`--page`	Page number (default: 1)
`--page-size`	Results per page (default: 50)
`--order-by`	Order by field: `created_at`, `updated_at`, `user_id`, `thread_id`
`--asc`	Sort in ascending order (default: descending)

Message Format

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

1 {
2   "messages": [
3     {
4       "role": "user",
5       "name": "Alice",
6       "content": "Hello, I need help with my account"
7     },
8     {
9       "role": "assistant",
10       "content": "I'd be happy to help!"
11     }
12   ]
13 }

graph

Manage knowledge graphs.

$ # 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"

Add Data Flags

Flag	Description
`--type`	Data type: `text`, `json`, `message` (default: `text`)
`--data`	Inline data string
`--file`	Path to data file
`--stdin`	Read data from stdin
`--user`	Add to user graph
`--batch`	Enable batch processing
`--wait`	Wait for ingestion to complete

Add Fact Flags

Flag	Description
`--user`	Add to user graph
`--graph`	Add to standalone graph
`--fact`	The fact relating the two nodes (required)
`--fact-name`	Edge name, should be UPPER_SNAKE_CASE (required)
`--source-node`	Source node name (required)
`--target-node`	Target node name (required)
`--valid-at`	When the fact becomes true (ISO 8601)
`--invalid-at`	When the fact stops being true (ISO 8601)
`--source-attrs`	Source node attributes as JSON
`--edge-attrs`	Edge attributes as JSON
`--target-attrs`	Target node attributes as JSON

Search Flags

Flag	Description
`--user`	Search user graph
`--graph`	Search standalone graph
`--scope`	Search scope: `edges`, `nodes`, `episodes` (default: `edges`)
`--limit`	Maximum results (default: 10)
`--reranker`	Reranker: `rrf`, `mmr`, `cross_encoder`
`--mmr-lambda`	MMR diversity/relevance balance (0-1)
`--min-score`	Minimum relevance score
`--node-labels`	Comma-separated node labels to include
`--edge-types`	Comma-separated edge types to include
`--exclude-node-labels`	Comma-separated node labels to exclude
`--exclude-edge-types`	Comma-separated edge types to exclude
`--property-filter`	Property filter (repeatable): `property:op:value` or `property:IS NULL`
`--date-filter`	Date 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

1 {
2   "episodes": [
3     {"type": "text", "data": "User prefers morning meetings"},
4     {"type": "json", "data": "{\"preference\": \"dark_mode\"}"},
5     {"type": "message", "data": "Alice: I love hiking on weekends"}
6   ]
7 }

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>
> 
> # 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>
> 
> # 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

1 entities:
2   Customer:
3     description: "A customer of the business"
4     fields:
5       tier:
6         description: "Customer tier level"
7       account_number:
8         description: "Customer account number"
9   Product:
10     description: "A product or service"
11     fields:
12       sku:
13         description: "Product SKU"
14 
15 edges:
16   PURCHASED:
17     description: "Customer purchased a product"
18     source_types: [Customer]
19     target_types: [Product]
20   INTERESTED_IN:
21     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]

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:

Format	Description
`table`	Human-readable table (default)
`json`	JSON output for scripting
`yaml`	YAML output
`wide`	Extended 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

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

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