⚡ dakera-cli

Command-line interface for Dakera AI — inspect and manage a Dakera memory instance from the terminal.

The Dakera memory engine scores 88.2% Recall@20 on LoCoMo (1,536 evaluated questions · LLM-judged retrieval recall) — benchmark details

Run Dakera

You need a running Dakera server to connect to. The fastest way:

docker run -d \
  --name dakera \
  -p 3000:3000 \
  -e DAKERA_ROOT_API_KEY=dk-mykey \
  ghcr.io/dakera-ai/dakera:latest

For persistent storage (recommended):

curl -sSfL https://raw.githubusercontent.com/Dakera-AI/dakera-deploy/main/docker-compose.yml \
  -o docker-compose.yml
DAKERA_ROOT_API_KEY=dk-mykey docker compose up -d

curl http://localhost:3000/health  # → {"status":"ok"}

Full deployment guide (Docker Compose, Kubernetes, Helm): dakera-deploy

Install

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

Cargo

# From crates.io (compiles from source)
cargo install dakera-cli

# Pre-built binary via cargo-binstall (faster)
cargo binstall dakera-cli

Binary download

Pre-built binaries for macOS (arm64/x64), Linux (x64/arm64), and Windows are available on the releases page.

Platform	File
macOS (Apple Silicon)	`dakera-cli-aarch64-apple-darwin.tar.gz`
macOS (Intel)	`dakera-cli-x86_64-apple-darwin.tar.gz`
Linux x64	`dakera-cli-x86_64-unknown-linux-musl.tar.gz`
Linux arm64	`dakera-cli-aarch64-unknown-linux-musl.tar.gz`
Windows x64	`dakera-cli-x86_64-pc-windows-msvc.zip`

Quick Start

# 1. Configure the CLI (server URL + API key)
dk init

# 2. Verify connectivity
dk health

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

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

# 5. Full-text BM25 search
dk text search "user preferences" --namespace default

Configuration

Environment variables

Variable	Description	Default
`DAKERA_URL`	Server base URL	`http://localhost:3000`
`DAKERA_API_KEY`	API key for authentication	—
`DAKERA_PROFILE`	Named profile to use	active profile in config

Config file

dk init creates ~/.dakera/config.toml (one profile per server):

active_profile = "default"

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

The API key is never stored in it: dk reads it from DAKERA_API_KEY only. dk writes the file readable by its owner only (0600, in a 0700 directory) and warns on stderr when it finds the file readable by other users. dk config shows the key masked (dk_…9876), never in full, and whether the server URL uses TLS; a key sent over plain http:// to a host other than the loopback interface gets a warning on stderr. TLS certificates are always verified (system trust store).

Named profiles

dk config profile add staging --url https://staging.example.com:3000
dk config profile use staging
dk --profile staging namespace list

Precedence

Environment variables > CLI flags > config file > defaults.

Global Flags

Flag	Short	Default	Description
`--url`	`-u`	`http://localhost:3000`	Server URL
`--format`	`-f`	`table`	Output format: `table`, `json`, `compact`
`--verbose`	`-v`	false	Log HTTP requests and response timing
`--profile`	`-p`	—	Named server profile

dk --format json memory recall my-agent "recent tasks"
dk --format compact namespace list | jq '.[].name'
dk --verbose memory store my-agent "new memory"

Commands

`dk health`

Check server health and connectivity. Reads the server's JSON directly, so a v0.12 server that is still loading its models (/health answers 503 with a Retry-After header) is reported as such, with exit code 6 — never as healthy.

dk health                  # status; lists degraded components, config warnings, embed migration
dk health --detailed       # + live / ready probes, version, build, uptime, diagnostics
dk health ready            # GET /health/ready  (exit 6 and the reason/downloads while starting)
dk health live             # GET /health/live

`dk capabilities`

What the connected server supports (GET /v1/capabilities, Dakera v0.12+): the active embedding model, search mode, scoring strategy, query languages (lang) and which opt-in features are on (attachments, speech to text, image indexing, records). A v0.11 server has no such route: the command exits 3 and says so.

dk capabilities
dk --format json capabilities

`dk whoami`

The API key this CLI authenticates with, as the server reads it (GET /v1/auth/whoami, Dakera v0.12.2): scope, namespace grants, whether it is unrestricted, its grant syntax version and the grants that match nothing (inert: a pre-v0.12.2 foo*, or _dakera_sessions).

dk whoami
dk --format json whoami

`dk attachment`

Files that agent memories can point at (Dakera v0.12, opt-in: the server answers 501 FEATURE_DISABLED until DAKERA_ATTACHMENTS is set; image indexing also needs DAKERA_VISION). dk capabilities shows what is on.

dk attachment upload _dakera_agent_my-agent note.wav    # media type guessed from the extension
dk attachment list _dakera_agent_my-agent
dk attachment download _dakera_agent_my-agent sha256:<hex> -o note.wav
dk attachment delete _dakera_agent_my-agent sha256:<hex>   # 409 while a memory references it

# Speech to text: a WAV attachment becomes a memory (a background job)
dk attachment transcribe uploads sha256:<hex> --agent-id my-agent --tag voice --wait
# Visual memory from a PNG (needs DAKERA_VISION)
dk attachment index uploads sha256:<hex> --agent-id my-agent --content "page 3" --wait
dk attachment job uploads sha256:<hex> job_1a2b3c4d_0 --kind transcribe

A memory can only reference an attachment stored in its own namespace, _dakera_agent_<agent_id>; transcribe and index copy an attachment from any namespace you can read into the agent's. --wait polls the job (progress goes to stderr) and exits 5 if the job fails with a 400, 6 on a 5xx.

`dk document`

Import a document as chunk memories of an agent (Dakera v0.12.3): each chunk keeps its heading path and page, so dk memory recall can cite it (a SOURCE column, document in JSON). Text, Markdown and HTML are sent as text; PDF and DOCX (and text that is not UTF-8) are uploaded as an attachment to the agent's namespace (--namespace to pick another) and imported from there, which needs DAKERA_ATTACHMENTS on the server. The format comes from the extension (.txt, .md, .html, .pdf, .docx; - reads stdin as text) unless --media-type says otherwise.

dk document import guide.md --agent docs-bot --wait
dk document import manual.pdf --agent docs-bot --document-id manual-v3 --tag manual --wait
dk document import notes.txt --agent docs-bot --chunk-tokens 300 --overlap 30 --strategy fixed
cat page.html | dk document import - --agent docs-bot --media-type text/html --title "Release notes"
dk document job job_17_3 --agent docs-bot      # Pending / Running (progress) / Completed / Failed
dk document list --agent docs-bot --limit 20    # then --cursor <next_cursor>
dk document show manual-v3 --agent docs-bot     # the document and its chunks (pages, headings)
dk document delete manual-v3 --agent docs-bot   # every chunk memory of it

Re-importing the same --document-id replaces the document (unchanged chunks are kept as they are). Other flags: --title, --session-id, --type, --importance, --lang, --decompose (also derive sentence sub-memories per chunk), --timeout (with --wait, default 600 s). A server before v0.12.3 has no document routes: dk says so.

`dk namespace`

Manage namespaces.

dk namespace list
dk namespace create my-ns
dk namespace policy --namespace my-ns

`dk memory`

Store, recall, search, and manage agent memories. This is the primary interface to Dakera.

# Store a memory
dk memory store my-agent "The user likes dark mode" --importance 0.8 --type semantic

# Recall by semantic query: at most --top-k ranked results, then a separate "Context"
# section with the session neighbours of those results (which result each belongs to).
# A MATCHED_TEXT column appears when the server collapsed sentence sub-memories into a result.
dk memory recall my-agent "UI preferences" --top-k 10
# --neighborhood separate (default) | inline | off; --include-summaries[=false]
dk memory recall my-agent "UI preferences" --neighborhood off --include-summaries=false
# JSON: {"memories": [...], "context_memories": [...]} (matched_text, context_of, context_of_rank)
dk --format json memory recall my-agent "UI preferences" | jq '.memories[].id'

# Full-text search within an agent's memories
dk memory search my-agent "dark mode" --top-k 5

# Get a specific memory by ID
dk memory get my-agent mem-abc123

# Update a memory
dk memory update my-agent mem-abc123 --content "Updated content"

# The language of the content or query (server v0.12+; `dk capabilities` lists them)
dk memory store my-agent "Anna kommt morgen nach Berlin" --lang de
dk memory recall my-agent "quand part Anna ?" --lang fr

# Link a memory to an uploaded attachment (server v0.12+, DAKERA_ATTACHMENTS)
dk memory store my-agent "Whiteboard from the planning meeting" --attachment-ref sha256:3f2a...

# Store many memories in one request (up to 1000; --file takes a JSON array, '-' = stdin)
dk memory batch-store my-agent -c "Prefers dark mode" -c "Lives in Berlin" --tag prefs
dk memory batch-store my-agent --file memories.json --lang de

# Extract entities from text without storing it
dk memory extract "Anna met Bob in Paris" --entity-types person,location

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

# Batch delete by filters (dry-run first!)
dk memory batch-forget my-agent --min-importance 0.3 --dry-run
dk memory batch-forget my-agent --min-importance 0.3 --max-age-days 90

# Update importance scores
dk memory importance my-agent --ids mem-1,mem-2 --value 0.9

# Consolidate similar memories into summaries
dk memory consolidate my-agent --dry-run

# Submit recall quality feedback (upvote, downvote, flag)
dk memory feedback my-agent mem-abc123 upvote

`dk text`

Full-text (BM25) search across memories.

# Search one namespace (the server has no cross-namespace full-text route)
dk text search "machine learning" --namespace default

# Search within a specific namespace
dk text search "temporal reasoning" --namespace my-ns --limit 20

`dk session`

Manage agent sessions.

dk session start my-agent
dk session start my-agent --idle-timeout 8h   # v0.12.2: own inactivity timeout (0 = never)
dk session touch sess-abc123                  # v0.12.2: keep a quiet session open
dk session end sess-abc123
dk session list --agent-id my-agent --active-only
dk session get sess-abc123
dk session memories sess-abc123 --preview 200 --limit 20

Since Dakera v0.12.2 the server ends a session after 4 hours without activity (storing, recalling or dk session touch); dk session list shows ended_reason (client or idle). Sessions are authorized by their agent: a key needs Write on the agent to start, touch or end its sessions, and dk session end with a read-only key is refused (403).

`dk agent`

View and manage agents.

dk agent list
dk agent create mlx-dev                        # v0.12.2: create before the first memory (idempotent)
dk agent stats my-agent
dk agent memories my-agent --type episodic --limit 20
dk agent memories my-agent --preview 200       # v0.12.2: content previews (CONTENT_LEN, TRUNCATED columns)
dk agent memories my-agent --include-derived   # v0.12.2: also list the derived sentence sub-memories
dk agent sessions my-agent --active-only

Since Dakera v0.12.2 dk agent memories leaves the derived sentence sub-memories out unless --include-derived is given. With --preview N each memory's content is cut to N characters by the server; dk memory get shows a whole memory.

`dk knowledge`

Knowledge graph management and memory summarization.

# Build a knowledge graph from a memory
dk knowledge graph my-agent --memory-id mem-abc123 --depth 3

# Full knowledge graph for an agent
dk knowledge full-graph my-agent --max-nodes 100 --preview 200

# Summarize a set of memories into a new memory
dk knowledge summarize my-agent --memory-ids m1,m2,m3 --dry-run

# Find and remove duplicate memories
dk knowledge deduplicate my-agent --threshold 0.9 --dry-run

`dk index`

Index management.

dk index stats --namespace my-ns
dk index fulltext-stats --namespace my-ns
dk index rebuild --namespace my-ns --dry-run
dk index rebuild --namespace my-ns --index-type vector --yes

`dk keys`

API key management.

dk keys list
dk keys create my-key --permissions read,write
dk keys delete key-abc123
dk keys usage key-abc123

# Dakera v0.12.2
dk keys edit dk_key_1a2b --name ci                             # rename (alias: dk keys patch)
dk keys edit dk_key_1a2b --namespaces '_dakera_agent_mlx-*,docs'  # replace the grants (p* prefix patterns)
dk keys edit dk_key_1a2b --all-namespaces                      # every namespace (sends null)
dk keys edit dk_key_1a2b --no-namespaces                       # no namespace (sends [])
dk keys edit dk_key_1a2b -n team-a --namespaces 'team-a*'      # as a namespace admin
dk keys rotate dk_key_1a2b --grace 1h                          # the old key keeps working for 1h (at most 7d)

dk keys edit needs an unrestricted super_admin key (or, with -n, an admin of that namespace whose grants contain the new ones). Saving the namespaces of a key created before v0.12.2 activates its foo* entries.

`dk admin`

Cluster administration, caching, backups, and server configuration.

# Cluster overview
dk admin cluster-status
dk admin cluster-nodes

# Namespace index management
dk admin optimize my-ns
dk admin index-stats my-ns
dk admin rebuild-indexes my-ns

# Cache management
dk admin cache-stats
dk admin cache-clear
dk admin cache-clear --namespace my-ns

# Server configuration
dk admin config-get
dk admin config-set --key max_connections --value 100

# Namespace quotas (a hard quota is enforced since v0.12: writes over it get 413)
dk admin quotas-get
dk admin quotas-set --data '{"max_vectors": 100000, "enforcement": "hard"}'              # default quota
dk admin quotas-set -n my-ns --data '{"max_vectors": 10000, "enforcement": "soft"}'      # one namespace

# Performance diagnostics
dk admin slow-queries --limit 10

# After an upgrade to v0.12: the one-time background re-embed (also in `dk health`)
dk admin embed-migration

# Encryption at rest (v0.12 keyring): status, rotation per namespace, re-seal
dk admin encryption-status
dk admin encryption-rotate -n my-ns                      # a new random key for one namespace
dk admin encryption-rotate --new-key-env MY_NEW_KEY      # global, from a passphrase in the environment
dk admin encryption-reseal --wait-secs 30

# Backups
dk admin backup-create --name nightly --type full --wait
dk admin backup-list
dk admin backup-get <backup-id>
dk admin backup-schedule                                 # an enabled schedule runs since v0.12
dk admin backup-download <backup-id> -o nightly.json.gz  # super_admin
dk admin backup-upload nightly.json.gz                   # super_admin
dk admin backup-restore <backup-id> -n my-ns --wait      # super_admin; add --overwrite --yes for a point-in-time restore
dk admin backup-restore-status <restore-id>
dk admin backup-delete <backup-id>

# Dakera v0.12.2
dk admin derivations-status                              # derived data owed (sub-memories, full-text, graph edges)
dk admin derivations-drain --timeout 10m                 # derive everything owed now
dk admin session-idle-timeout                            # show the server-wide session idle timeout
dk admin session-idle-timeout 8h                         # set it (0 = never; at most 30d)

All of these need a global key. A key pinned to namespaces gets 403 on node-wide routes even with the admin scope, and backup download, upload and restore need super_admin (see Permissions). The previous backup-create sent no name, which the server requires, and quotas-set called a route that does not exist; both now work.

`dk config`

Show or manage connection profiles.

dk config
dk config profile add staging --url http://staging:3000
dk config profile use staging
dk config profile list

`dk completion`

Generate shell completion scripts.

dk completion bash --install
dk completion zsh --install
dk completion fish --install
dk completion powershell

Dakera v0.12 and compatibility

Breaking in dk 0.8.2: dk --format json|compact memory recall prints one object, {"memories": [...], "context_memories": [...]}, instead of an array of rows: read the ranked results from .memories.

The 0.8.2 additions need a v0.12.3 server; older servers ignore them, as noted:

Command (0.8.2)	v0.12.2 and older	v0.12.3
`dk memory recall` (`--neighborhood separate`, the default)	the server appends its context to the results unmarked: `dk` shows the first `--top-k` and warns how many it left out	at most `--top-k` ranked results, then the Context section with `context_of`
`dk memory recall --include-summaries[=false]`	ignored	yes
`MATCHED_TEXT` column	never shown	when the server collapses derived sentences (`DAKERA_RECALL_COLLAPSE_DERIVED`)
the unknown-field hint (`keys create`, `admin backup-create`, `admin encryption-rotate`)	not needed: unknown fields are ignored	a misspelled field is a `422`, with a hint naming it
`dk document ...`	no route: `dk` says it needs v0.12.3	yes (`DAKERA_DOCUMENTS`, on by default; PDF / DOCX also need `DAKERA_ATTACHMENTS`)
`SOURCE` column / `document` in `memory recall`	never shown	for results that are document chunks
`dk admin` / `dk keys` commands	as before	as before; `POST /ops/shutdown` (no `dk` command) needs a `super_admin` key

dk 0.8.2 works against Dakera v0.11.108 and v0.12.0 – v0.12.3 servers (it uses dakera-client 0.12). The new commands need the server release that has the route or field:

Command	v0.11.108	v0.12.0
everything in 0.7 (`memory`, `namespace`, `session`, `keys`, ...)	yes	yes
`dk health`, `dk health ready`, `dk health live`	yes	yes (+ `degraded`, `config_warnings`, `embed_migration`)
`dk capabilities`	exits 3 (no route)	yes
`dk memory batch-store`, `dk memory extract`	yes	yes
`--lang` (`dk memory store	recall	search
`dk attachment ...`	no	yes, once `DAKERA_ATTACHMENTS` is on
`dk admin embed-migration`, `encryption-status`, `encryption-reseal`	no	yes
other `dk admin` commands (`encryption-rotate`, `backup-`, `quotas-`, ...)	routes that v0.11.108 already had	same routes; v0.12 changes who may call them and what they do (below)

The 0.8.1 commands need a v0.12.2 server; on v0.12.0 / v0.12.1 they fail (404/405, exit 3 or 1) or are ignored, as noted:

Command (0.8.1)	v0.12.0 / v0.12.1	v0.12.2
`dk whoami`, `dk agent create`, `dk session touch`, `dk keys edit`, `dk admin derivations-*`	no route	yes
`dk keys rotate --grace`	the old key is deactivated at once (`dk` warns)	yes
`dk session start --idle-timeout`	ignored (sessions never time out)	yes
`dk admin session-idle-timeout`	says the server predates it	yes
`--preview`, `--include-derived` (`agent memories`, `session memories`, `knowledge full-graph`)	ignored (full content; derived records always listed)	yes

Permissions (v0.12)

Keys pinned to namespaces get 403 on node-wide routes (/admin/*: backups, encryption, quotas, config, cluster), even with the admin scope.
Backup download, upload and restore need a global super_admin key: a backup bundle carries every API key hash, so an admin key can no longer take one (or restore an edited one).

dk turns those answers into a message that says what to do, for example:

✗ Permission denied: Request failed (403 Forbidden) [INSUFFICIENT_SCOPE]: Insufficient scope for this operation (required: super_admin, actual: admin)
  hint: this needs a global super_admin key: since v0.12 backup download, upload and restore are refused to admin keys ...

Errors

v0.12 answers every error with a JSON body ({"error", "code", "status", "details"}) and every 503 carries Retry-After. dk keeps those fields: with --format json the error on stderr gains http_status, server_code, details and retry_after_secs. A 413 (a body over a size limit such as DAKERA_ATTACHMENT_MAX_BYTES, or a hard namespace quota) exits 5; a 501 (a feature that is switched off, FEATURE_DISABLED, or a configuration the server cannot serve) and a 503 exit 6. Retry a 503 after the Retry-After seconds.

Server-side commands (not `dk` commands)

Two operator commands ship in the server binary, not in dk; run them with the server's image, environment and volumes:

# Check a configuration with the new image before upgrading: exits 0 (the server
# would start, warnings included) or 78 (it would refuse). Starts nothing.
docker run --rm <same env and volumes> <v0.12 image> --check-config

# Go back to v0.11.108: run once, after the v0.12 server has stopped. Prints a JSON
# report; exit 0 = the data is v0.11.108's, 1 = something still needs fixing (run it
# again), 78 = it refused and changed nothing.
docker run --rm <same env and volumes> <v0.12 image> downgrade

See the server's docs/v0.12/UPGRADE.md ("Going back to v0.11.108") for what downgrade converts and when it refuses.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Connection error (server unreachable)
3	Not found
4	Permission denied / authentication failure (`401`, `403`)
5	Invalid input (`400`, `409`, `413`, `415`, `422`, or a bad argument)
6	Server-side error (5xx, including `501` feature disabled and `503` busy/starting), or `429` server overloaded (retry after its `Retry-After`)

Scripts can check $? after each command.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
snap		snap
src		src
tests		tests
.claudeignore		.claudeignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
dist-workspace.toml		dist-workspace.toml
rust-toolchain.toml		rust-toolchain.toml

Repo	What it is
dakera-py	Python SDK
dakera-js	TypeScript SDK
dakera-mcp	MCP server · 14 core tools (86+ via profiles)
dakera-deploy	Self-host Dakera

Latest commit

History

Folders and files

Repository files navigation

⚡ dakera-cli

Run Dakera

Install

Homebrew (macOS / Linux)

APT (Debian / Ubuntu)

YUM / DNF (Fedora / RHEL / CentOS)

Cargo

Binary download

Quick Start

Configuration

Environment variables

Config file

Named profiles

Precedence

Global Flags

Commands

dk health

dk capabilities

dk whoami

dk attachment

dk document

dk namespace

dk memory

dk text

dk session

dk agent

dk knowledge

dk index

dk keys

dk admin

dk config

dk completion

Dakera v0.12 and compatibility

Permissions (v0.12)

Errors

Server-side commands (not dk commands)

Exit Codes

Related

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages