CLI Reference

dk is the command-line client for Dakera. It stores and recalls agent memories, searches them, manages sessions, namespaces and API keys, explores knowledge graphs and runs administrative tasks against a Dakera server over its REST API. This page is the reference for dk 0.8.1, the current release, for developers and operators who work from a terminal or in scripts.

The last section covers the subcommands of the server binary itself (dakera --check-config, dakera downgrade, dakera models), which you run against a deployment rather than through dk.

Source: github.com/dakera-ai/dakera-cli  ·  v0.8.1 release notes

Prerequisites: a running Dakera server

dk needs a Dakera server to talk to. To start one locally with data kept on a Docker volume:

Docker

docker run -d \
  --name dakera \
  -p 3000:3000 \
  -e DAKERA_ROOT_API_KEY=dk-mykey \
  -e DAKERA_STORAGE=filesystem \
  -v dakera-data:/data \
  ghcr.io/dakera-ai/dakera:0.12.2

Docker Compose (from dakera-deploy)

git clone https://github.com/Dakera-AI/dakera-deploy.git
cd dakera-deploy/docker
DAKERA_ROOT_API_KEY=dk-mykey DAKERA_PORT=3000 docker compose up -d

# Verify the server is healthy
curl http://localhost:3000/health
# → {"service":"dakera","status":"healthy","version":"0.12.2",…}

For Kubernetes and Helm deployments see dakera-deploy.

Installation

Homebrew (macOS / Linux)

brew install dakera-ai/tap/dk

APT (Debian / Ubuntu)

curl -fsSL https://dakera-ai.github.io/apt-repo/KEY.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/dakera-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/dakera-archive-keyring.gpg] https://dakera-ai.github.io/apt-repo stable main" \
  | sudo tee /etc/apt/sources.list.d/dakera.list
sudo apt-get update && sudo apt-get install -y dk

YUM / DNF (Fedora / RHEL / CentOS)

sudo tee /etc/yum.repos.d/dakera.repo << 'EOF'
[dakera]
name=Dakera AI
baseurl=https://dakera-ai.github.io/rpm-repo/
enabled=1
gpgcheck=0
EOF
sudo dnf install -y dk

Install script (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dakera-ai/dakera-cli/releases/download/v0.8.1/dakera-cli-installer.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/dakera-ai/dakera-cli/releases/download/v0.8.1/dakera-cli-installer.ps1 | iex"

Binary download

Pre-built archives for macOS (arm64, x64), Linux (x64) and Windows (x64), with SHA-256 checksums, are on the v0.8.1 release page. Extract the archive and put dk on your PATH.

Cargo

cargo install dakera-cli

Quick start

Six commands from a fresh install to storing and searching memories:

# 1. Provide the API key (dk reads it from the environment only)
export DAKERA_API_KEY=dk-mykey

# 2. Interactive setup: server URL and default namespace
dk init

# 3. Verify connectivity to your Dakera server
dk health

# 4. Store your first memory
dk memory store my-agent "The user prefers concise responses" --importance 0.8

# 5. Recall by semantic query
dk memory recall my-agent "user preferences" --top-k 5

# 6. Search one agent's memories with filters
dk memory search my-agent "user preferences" --type episodic

dk init checks the server and writes the default profile (server URL and default namespace) to ~/.dakera/config.toml, so you do not need --url on every command. The API key is never written to the config file: keep DAKERA_API_KEY set in the shell or environment that runs dk.

Configuration

Environment variables

Config file

dk init creates ~/.dakera/config.toml with a default profile; dk config profile add adds more. You can also edit it by hand:

active_profile = "default"

[profiles.default]
url = "http://localhost:3000"
default_namespace = "default"

[profiles.staging]
url = "https://staging.example.com"
default_namespace = "staging"

Run dk config (or dk config --show) to print the configuration in effect.

Named profiles

Switch between environments without touching environment variables:

# Add a profile for a staging server
dk config profile add staging --url https://staging.example.com --namespace staging

# Switch the active profile
dk config profile use staging

# Or pass --profile per command without switching
dk --profile staging namespace list

# List all saved profiles
dk config profile list

Precedence

For the server URL: --url > DAKERA_URL > the active profile in the config file (chosen by --profile, then DAKERA_PROFILE, then active_profile) > http://localhost:3000.

Global flags

Global flags go before the command group (dk --format json memory recall …); placed after a subcommand they are rejected.

# JSON output for scripting
dk --format json memory recall my-agent "recent tasks"

# Compact output for piping
dk --format compact namespace list | jq '.[].name'

# Verbose: show HTTP request/response details
dk --verbose memory store my-agent "new memory"

Memory

The core feature of Dakera. Memories are stored per-agent and retrieved by semantic similarity. Each memory has a type that controls its lifecycle:

Store

# Store with default type (episodic) and importance (0.5)
dk memory store my-agent "Completed onboarding for user Alice"

# Semantic memory: factual preference, higher importance
dk memory store my-agent "User prefers dark mode" --type semantic --importance 0.8

# Procedural: how-to knowledge
dk memory store my-agent "To restart the service: systemctl restart dakera" --type procedural --importance 0.9

# Working memory: short-term context, attach to a session
dk memory store my-agent "Currently debugging auth issue" --type working --session-id sess-abc123

Importance ranges from 0.0 (low) to 1.0 (critical) and defaults to 0.5. It weighs into recall ranking and into decay. The TTLs above are the defaults of a namespace's memory policy; change them with dk namespace policy set.

Recall (semantic search)

# Recall top 5 memories matching a query
dk memory recall my-agent "user preferences"

# Return more results
dk memory recall my-agent "authentication flow" --top-k 10

# Filter by memory type
dk memory recall my-agent "debugging" --type episodic --top-k 5

Search (filtered search within one agent)

# Search one agent's memories (default top-k 10)
dk memory search my-agent "dark mode" --top-k 10

# Filter by type
dk memory search my-agent "onboarding" --type episodic

Get a memory by ID

dk memory get my-agent mem-abc123

Update

# Update content
dk memory update my-agent mem-abc123 --content "User now prefers light mode"

# Change memory type
dk memory update my-agent mem-abc123 --type semantic

Forget (delete)

# Delete a single memory
dk memory forget my-agent mem-abc123

Batch forget

# Preview what would be deleted (always dry-run first)
dk memory batch-forget my-agent --min-importance 0.3 --dry-run

# Delete low-importance memories older than 90 days
dk memory batch-forget my-agent --min-importance 0.3 --max-age-days 90

# Delete all working memories for a specific agent
dk memory batch-forget my-agent --type working

Update importance scores

# Boost importance for a set of memories
dk memory importance my-agent --ids mem-1,mem-2,mem-3 --value 0.9

Consolidate

# Preview similar memories that would be merged
dk memory consolidate my-agent --dry-run

# Merge with a higher similarity threshold (stricter)
dk memory consolidate my-agent --threshold 0.9

# Consolidate only semantic memories
dk memory consolidate my-agent --type semantic --dry-run

Feedback

# Signal that a memory was useful (raises its importance)
dk memory feedback my-agent mem-abc123 upvote

# Signal that it was not (lowers its importance), or flag it for decay
dk memory feedback my-agent mem-abc123 downvote
dk memory feedback my-agent mem-abc123 flag

The signal is one of upvote, downvote, flag, positive or negative; upvote and downvote change the memory's importance and flag marks it for decay. Feedback signals are used to tune recall quality over time.

Text search (BM25)

dk text search runs a BM25 search in one namespace (--namespace is required). For one agent's memories use dk memory search.

# BM25 full-text search in a namespace
dk text search "temporal reasoning" --namespace my-ns --limit 20

# Hybrid search (dk sends no query vector, so the server ranks by BM25 alone)
dk memory hybrid-search my-ns "temporal reasoning" --top-k 20

Sessions

Sessions group related memories and provide a shared context window for an agent conversation.

# Start a new session
dk session start my-agent

# Start with metadata
dk session start my-agent --metadata '{"task":"onboarding","user":"alice"}'

# End a session with a summary
dk session end sess-abc123 --summary "Completed user onboarding flow"

# Get session details
dk session get sess-abc123

# List sessions (with filters)
dk session list --agent-id my-agent --active-only
dk session list --agent-id my-agent --limit 20

# View all memories associated with a session
dk session memories sess-abc123

Agents

Inspect agents stored in the system — their memories, sessions, and aggregate statistics.

# List all agents
dk agent list

# Memory and session statistics for an agent
dk agent stats my-agent

# List memories for an agent
dk agent memories my-agent
dk agent memories my-agent --type episodic --limit 20

# List sessions for an agent
dk agent sessions my-agent
dk agent sessions my-agent --active-only --limit 10

Namespaces

Namespaces partition memories into isolated vector spaces. Each namespace can have its own dimension, TTL policies, and rate limits.

Basic operations

# List all namespaces
dk namespace list

# Get details for a namespace
dk namespace get my-ns

# Create a namespace (--dimension is required; --distance defaults to cosine)
dk namespace create my-ns --dimension 1536
dk namespace create my-ns --dimension 1536 --distance dot

# Delete a namespace (preview first)
dk namespace delete my-ns --dry-run
dk namespace delete my-ns --yes

Namespace policy

Control how memories age, decay, deduplicate and are rate-limited within a namespace. All flags are optional: dk reads the current policy and changes only the flags you supply. A v0.12.0 server refuses --rate-limit-enabled true unless at least one per-minute cap is set.

# View current policy
dk namespace policy get my-ns

# Set TTLs (in seconds)
dk namespace policy set my-ns \
  --working-ttl 7200 \
  --episodic-ttl 1296000 \
  --semantic-ttl 31536000 \
  --procedural-ttl 63072000

# Set decay curves per memory type
dk namespace policy set my-ns \
  --working-decay exponential \
  --episodic-decay power_law \
  --semantic-decay logarithmic \
  --procedural-decay flat

# Enable spaced repetition (TTL extends on each recall hit)
dk namespace policy set my-ns --spaced-repetition-factor 1.5 --spaced-repetition-base-interval 86400

# Enable background DBSCAN deduplication
dk namespace policy set my-ns \
  --consolidation-enabled true \
  --consolidation-threshold 0.92 \
  --consolidation-interval-hours 24

# Enable per-namespace rate limiting
dk namespace policy set my-ns \
  --rate-limit-enabled true \
  --rate-limit-stores-per-minute 100 \
  --rate-limit-recalls-per-minute 200

Knowledge graph

Build and explore semantic relationships between memories, summarize clusters, and deduplicate near-identical content.

Graph from a seed memory

# Build a graph starting from one memory
dk knowledge graph my-agent --memory-id mem-abc123

# Control traversal depth and similarity cutoff
dk knowledge graph my-agent --memory-id mem-abc123 --depth 3 --min-similarity 0.75

Full knowledge graph

# Full graph for an agent (all memories as nodes)
dk knowledge full-graph my-agent

# Limit graph size
dk knowledge full-graph my-agent --max-nodes 200 --max-edges 50 --min-similarity 0.7

# Adjust cluster grouping threshold
dk knowledge full-graph my-agent --cluster-threshold 0.85

Summarize

# Summarize two or more memories into a new memory (the server has no dry run: the summary is always stored)
dk knowledge summarize my-agent --memory-ids mem-1,mem-2,mem-3 --target-type semantic

Deduplicate

# Preview duplicates above default threshold
dk knowledge deduplicate my-agent --dry-run

# Set a stricter threshold (higher = more similar required)
dk knowledge deduplicate my-agent --threshold 0.95 --dry-run

# Deduplicate only episodic memories
dk knowledge deduplicate my-agent --type episodic --dry-run

API keys

Key management (dk keys) needs a super_admin key with no namespace restriction.

Create and manage API keys for authenticating agents and services against your Dakera server.

# Create a key (name is required, other flags are optional)
dk keys create my-service-key --permissions write
dk keys create ci-reader --permissions read --expires 90

# List all keys
dk keys list

# Inspect a key
dk keys get key-abc123

# View usage statistics for a key
dk keys usage key-abc123

# Rotate a key — generates a new secret, invalidates the old one
dk keys rotate key-abc123

# Temporarily suspend a key without deleting it
dk keys deactivate key-abc123

# Permanently delete a key
dk keys delete key-abc123

Admin and operations

Cluster status, index management, cache, server configuration, quotas, slow queries and backups. Against a v0.12.0 server these commands need an admin key with no namespace restriction (a key pinned to namespaces may still optimize and rebuild its own namespaces); restoring a backup needs a super_admin key with no namespace restriction. See Upgrading to v0.12.

Cluster

dk admin cluster-status
dk admin cluster-nodes

Index management

# Compact indexes and reclaim storage for a namespace
dk admin optimize my-ns

# View index statistics
dk admin index-stats my-ns

# Rebuild indexes (typically after large imports)
dk admin rebuild-indexes my-ns

Cache

# View cache statistics
dk admin cache-stats

# Clear all caches
dk admin cache-clear

# Clear cache for a specific namespace only
dk admin cache-clear --namespace my-ns

Server configuration

# Get current server configuration
dk admin config-get

# Update a configuration value
dk admin config-set --key query_timeout_ms --value 5000
dk admin config-set --key rate_limit_enabled --value true

Namespace quotas

# View all namespace quotas
dk admin quotas-get

# Set a namespace quota, or the default quota without -n (a hard quota is enforced since v0.12: 413)
dk admin quotas-set -n my-ns -d '{"max_vectors": 50000}'

Performance diagnostics

# View the 20 slowest queries
dk admin slow-queries

# Show queries slower than 500ms
dk admin slow-queries --min-duration 500

# Limit output
dk admin slow-queries --limit 10 --min-duration 100

Backups

# Create a full backup (data + schema)
dk admin backup-create

# Name it and wait for the background job to end
dk admin backup-create --name nightly --wait

# List all backups
dk admin backup-list

# Restore from a specific backup
dk admin backup-restore bkp-abc123

# Delete an old backup
dk admin backup-delete bkp-abc123

TTL configuration

Memory TTLs are set per type with dk namespace policy set (for example --episodic-ttl 2592000). dk admin configure-ttl was removed in 0.8.0: the server has no such route.

Index management

Fine-grained control over vector and full-text indexes for a namespace.

# Vector index statistics
dk index stats --namespace my-ns

# Full-text index statistics
dk index fulltext-stats --namespace my-ns

# Preview a rebuild (does not make changes)
dk index rebuild --namespace my-ns --dry-run

# Rebuild the vector index
dk index rebuild --namespace my-ns --index-type vector --yes

# Rebuild both indexes
dk index rebuild --namespace my-ns --index-type all --yes

Shell completions

Install shell completions so you get tab-complete for commands, subcommands, and dynamic values like namespace and agent names.

# Install completions automatically
dk completion bash --install
dk completion zsh --install
dk completion fish --install

# Print to stdout (for manual installation)
dk completion bash
dk completion zsh
dk completion fish

Dynamic completion queries your live server to suggest namespace and agent names.

Exit codes

Every dk command exits with a typed code. Use $? in scripts to detect specific failure modes:

With --format json (or compact), errors are written to stderr as a JSON object with error (true), code (machine string), exit_code (integer) and message:

# Check specific exit code in a script
dk --format json memory recall my-agent "recent tasks"
if [ $? -eq 2 ]; then
  echo "Cannot reach Dakera server"
fi

Safety features

The CLI is designed for safe use in production pipelines.

All command groups

dk 0.8.1 targets a v0.12.2 server and also works against v0.12.1, v0.12.0 and v0.11.108; the commands that need v0.12.2 (dk whoami, dk agent create, dk keys edit, dk keys rotate --grace, dk session touch, dk admin derivations-*, dk admin session-idle-timeout) say so on an older server, and the commands that call v0.12 routes (dk capabilities, dk attachment, dk admin encryption-*, dk health ready|live) say so when run against v0.11. Permission requirements for dk admin and dk keys are listed in their sections.

New in 0.8.1

• dk whoami: the key the CLI authenticates with (GET /v1/auth/whoami): scope, grants, unrestricted, grant syntax version and inert grants.
• dk agent create <agent_id>: create an agent before its first memory (POST /v1/agents); an existing agent is reported and left unchanged.
• dk keys edit <key_id> (alias patch): --name, --namespaces a,b (p* prefix patterns allowed), --all-namespaces, --no-namespaces; with -n <namespace> it edits a namespace key.
• dk keys rotate --grace <duration>: the old key keeps working for up to 7 days; the new key id and the old key's deadline are shown.
• dk session touch <session_id> and dk session start --idle-timeout <duration> (0 = never); dk admin session-idle-timeout [<duration>] shows or sets the server-wide timeout. Durations accept s, m, h, d.
• --preview <chars> on dk agent memories, dk session memories and dk knowledge full-graph; --include-derived on dk agent memories.
• dk admin derivations-status and dk admin derivations-drain [--timeout] (global admin key).
• Fixed: dk keys rotate prints the new key; dk session memories reports the server's total.

With a v0.12.2 server, sessions end after 4 hours without activity by default, keys no longer need a _dakera_sessions grant, validation is stricter (400, exit code 5) and dk agent memories leaves sentence sub-memories out unless --include-derived is given.

New in 0.8.0

• dk capabilities: the server's active model, search mode, scoring strategy, query languages and opt-in features (exit code 3 on a pre-v0.12 server).
• dk health ready and dk health live; dk health reports a starting server (503) as such, with exit code 6.
• dk attachment upload|list|download|delete|transcribe|index|job (opt-in on the server: DAKERA_ATTACHMENTS, DAKERA_VISION), with --wait for background jobs.
• dk admin embed-migration, encryption-status, encryption-rotate (the new key is read from an environment variable, --new-key-env), encryption-reseal, and the backup commands backup-get, backup-download, backup-upload, backup-restore-status, backup-schedule.
• --lang on dk memory store|recall|search|update, --attachment-ref on dk memory store, dk memory batch-store and dk memory extract.
• Exit codes follow the HTTP status of an error answer: 401 and 403 exit 4, 400, 409, 413, 415 and 422 exit 5, every 5xx exits 6. See the changelog for the full list.

Server binary commands (dakera)

These are subcommands of the server binary itself (dakera, in the server image), not of dk. Run them with the server's environment and volumes, for example docker run --rm <env and volumes> ghcr.io/dakera-ai/dakera:0.12.0 <command>.

dakera models honors HF_HOME, HF_ENDPOINT, HF_HUB_OFFLINE and the proxy variables. See Models and Docker.

Run dk --help for the full command reference. Run dk <group> --help for subcommand details and flag descriptions.