Skip to content

cli.mdx

Latest commit

 

History

History
824 lines (613 loc) · 23.7 KB

cli.mdx

File metadata and controls

824 lines (613 loc) · 23.7 KB
Raw
title zepctl CLI Reference
description Command-line interface for administering Zep projects

zepctl CLI

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

zepctl supports two authentication modes that coexist on the same profile:

  • API key (long-lived): pass via ZEP_API_KEY or store per-profile in the system keychain. Used for headless / CI scenarios.
  • Bearer token (OAuth / Kinde): obtained interactively via zepctl auth login and stored as a refresh token in the system keychain. Required for the ABAC management commands (policy-set, api-key) and the config set-project interactive flow.

Commands that require bearer auth use the bearer token even if an API key is also present.

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
ZEP_PROJECT Override 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.example.com
    # Optional per-profile OAuth overrides; otherwise build-time defaults apply.
    oauth-issuer: https://your-tenant.kinde.com
    oauth-client-id: <client-id>
    oauth-audience: <audience>
    project-uuid: <project-uuid>
    account-uuid: <account-uuid>
environments:
  # Named presets that can be applied to profiles via `--env`.
  - name: dev
    api-url: https://api.example.com
    oauth-issuer: https://your-tenant.kinde.com
    oauth-client-id: <client-id>
    oauth-audience: <audience>
defaults:
  output: table
  page-size: 50
API keys and OAuth refresh tokens 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

# Open a browser to authenticate, then auto-select a project
zepctl auth login

# Bootstrap an isolated dev profile against a configured environment preset
zepctl --profile dev auth login --env dev

# Print the authorization URL instead of opening a browser (headless / SSH)
zepctl auth login --no-browser

# Check current credentials and bearer token expiration
zepctl auth status

# Revoke refresh token and clear bearer token for the current profile
zepctl auth logout

Global Flags

Flag Short Description
--api-key -k Override API key
--api-url Override API URL
--profile -p Use specific profile
--project Override active project UUID for this command
--output -o Output format: table, json, yaml, wide
--quiet -q Suppress non-essential output
--verbose -v Enable verbose output
--config Path to config file (default: $HOME/.zepctl/config.yaml)
--help -h Display help

Commands

config

Manage zepctl configuration including profiles, environment presets, and the active project.

# Profiles
zepctl config view
zepctl config get-profiles
zepctl config use-profile <name>
zepctl config add-profile <name> [--api-url URL] [--env <name>] [--no-api-key]
zepctl config update-profile [name] [flags]
zepctl config delete-profile <name> [--force]

# Active project for the current profile
zepctl config set-project [uuid]     # interactive if uuid omitted

# Environment presets (reusable api-url + OAuth settings)
zepctl config get-environments
zepctl config add-environment <name> [flags]
zepctl config update-environment <name> [flags]
zepctl config delete-environment <name> [--force]

Profile Flags

add-profile and update-profile accept the same field flags. On update, only flags explicitly passed are applied; pass an empty string to clear a field.

Flag Description
--api-key API key (stored in system keychain)
--api-url API endpoint URL
--env Apply a named environment preset (replaces api-url/OAuth fields). Per-field flags override the preset.
--oauth-issuer OIDC issuer override for auth login
--oauth-client-id OAuth client ID override for auth login
--oauth-audience OAuth audience for the bearer token aud claim
--project Project UUID (update only)
--account Account UUID (update only)
--no-api-key (add-profile only) Create a bearer-only profile with no API key, skipping the prompt

Environment Preset Flags

Flag Description
--api-url API URL for the environment
--oauth-issuer OIDC issuer
--oauth-client-id OAuth client ID
--oauth-audience OAuth audience for bearer token aud claim
--force (delete-environment only) Skip confirmation prompt

auth

Manage bearer-token authentication for the current profile.

# Open a browser to authenticate, store refresh + access tokens, auto-select a project
zepctl auth login

# Headless: print the authorization URL instead of opening a browser
zepctl auth login --no-browser

# Create a new profile against a named environment preset on first login
zepctl --profile dev auth login --env dev

# Revoke refresh token and clear bearer token from the keychain
zepctl auth logout

# Show profile, API URL, OIDC issuer, masked API key, and bearer expiration
zepctl auth status
`auth login` auto-selects a project after authentication: if the account has exactly one project, it is selected automatically; otherwise the CLI prompts for a choice. ABAC management commands (`policy-set`, `api-key`) require a valid bearer token.

project

Get project information.

zepctl project get

user

Manage users in your Zep project.

# List users
zepctl user list [--page N] [--page-size N] [--search TERM] [--order-by FIELD] [--asc]

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

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

graph

Manage knowledge graphs.

# List all graphs
zepctl graph list [--page N] [--page-size N] [--order-by FIELD] [--asc]

# 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 in a graph
zepctl graph detect-patterns --user <user-id>
zepctl graph detect-patterns --graph <graph-id> --limit 20 --min-occurrences 3
zepctl graph detect-patterns --user <user-id> --recency-weight 30_days
zepctl graph detect-patterns --graph <graph-id> --node-labels "Person,Company"
zepctl graph detect-patterns --user <user-id> --query "purchase history" --query-limit 20

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
--source-labels Comma-separated labels for the source node
--target-labels Comma-separated labels for the target node

Detect Patterns Flags

Flag Description
--user Detect patterns in user graph
--graph Detect patterns in standalone graph
--limit Maximum patterns to return (default: 50, max: 200)
--min-occurrences Minimum occurrence count to report (default: 2)
--recency-weight Recency decay: none, 7_days, 30_days, 90_days
--node-labels Comma-separated node labels for seed selection
--edge-types Comma-separated edge types for seed selection
--node-uuids Comma-separated node UUIDs for seed selection
--query Hybrid-search query for seed-node discovery; forces triple-frequency detection with edge resolution. Mutually exclusive with --node-labels/--edge-types/--node-uuids
--query-limit Max seed nodes from query (max 50, only with --query)
--edge-limit Max resolved edges per pattern (max 100, only with --query)

Search Flags

Flag Description
--user Search user graph
--graph Search standalone graph
--scope Search scope: edges, nodes, episodes, observations, thread_summaries, auto (default: edges)
--limit Maximum results (default: 10)
--reranker Reranker: rrf, mmr, cross_encoder
--mmr-lambda MMR diversity/relevance balance (0-1)
--max-characters Max total characters across selected results (scope=auto, max 50000)
--return-raw-results When scope=auto, include raw graph results alongside the materialized context block
--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

{
  "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"
zepctl node update <uuid> --labels "Person,Employee" --attrs '{"role": "engineer"}'

# 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"
zepctl edge update <uuid> --valid-at "2024-01-01" --attrs '{"confidence": 0.9}'

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

observation

List and inspect derived observation nodes (read-only).

# List observations
zepctl observation list --user <user-id> [--limit N] [--cursor UUID]
zepctl observation list --graph <graph-id>

# Get observation details
zepctl observation get <uuid>

thread-summary

List incremental thread summaries.

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

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]

policy-set

Manage ABAC policy sets -- reusable bundles of access rules attached to API keys. Requires a bearer token (auth login) and operates on the currently-selected project (including validate, which calls the server).

# List policy sets in the active project
zepctl policy-set list

# Get a single policy set (table output renders the spec as indented YAML)
zepctl policy-set get <uuid>

# Create / update from a YAML file
zepctl policy-set create --file path/to/spec.yaml
zepctl policy-set update <uuid> --file path/to/spec.yaml

# Validate a YAML spec without persisting it
zepctl policy-set validate --file path/to/spec.yaml

# Delete (prompts unless --force; --force is required in non-interactive contexts)
zepctl policy-set delete <uuid> [--force]
`validate` exits 0 on success, 1 if validation fails (errors printed to stderr), and 2 on client or transport errors.

api-key

Configure ABAC enforcement on individual API keys and dry-run policy decisions. All api-key commands require a bearer token.

# List API keys (UUID, name, masked key, role)
zepctl api-key list

# Per-key ABAC settings
zepctl api-key settings get <key-uuid>
zepctl api-key settings set <key-uuid> --mode <off|report_only|enforce>

# Policy set attachments
zepctl api-key policy-sets list <key-uuid>
zepctl api-key policy-sets attach <key-uuid> <policy-set-uuid>
zepctl api-key policy-sets detach <key-uuid> <policy-set-uuid>

# Dry-run a policy decision against the key's live configuration
zepctl api-key evaluate <key-uuid> --action <name>
zepctl api-key explain  <key-uuid> --action <name>

Flags

Flag Description
--mode (settings set) ABAC enforcement mode: off, report_only, enforce
--action (evaluate, explain) Required. Action name to evaluate (e.g. thread.get)

evaluate returns the final outcome (allow / deny), the ABAC and ABAC-shadow decisions, whether the role would have allowed the action, and whether the disagreement would be logged. explain returns everything evaluate does plus the registry entry's read-only flag and the full evaluator trace (matched policies per set, set modes, and skipped sets).

Both `evaluate` and `explain` always exit 0 on a successful API call regardless of allow/deny outcome -- inspect the JSON or table output to check the decision.

Example:

# Switch a key to report-only mode, attach a policy set, then check the decision
zepctl api-key settings set abcd1234-... --mode report_only
zepctl api-key policy-sets attach abcd1234-... efgh5678-...
zepctl api-key evaluate abcd1234-... --action thread.get -o json

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

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