deyta-cli 0.3.1

A unified command-line tool for Deyta's services, wrapping Khora persistent memory for AI agents.

Deyta CLI

A unified command-line tool for Deyta's services. Today it wraps Khora (persistent memory for AI agents); the command surface is built so future services and a cloud platform slot in without breaking existing commands.

How it works

Khora is an in-process Python library, not a server. The CLI runs a local daemon (deyta serve — a FastAPI app holding one Khora instance open) and talks to it over HTTP. The CLI itself never imports Khora. The target server is resolved per command:

--host flag  >  DEYTA_HOST env  >  active context  >  http://localhost:8787

That resolution is the local↔cloud seam: switching to a cloud platform later is a new context, not new commands.

Requirements

• Python 3.13+
• DEYTA_OPENAI_API_KEY in ~/.config/deyta/.env (Khora uses it for embeddings and entity extraction; deyta init prompts for it)
• Docker — only for the postgres backend (deyta db up); the embedded backend needs none

Install

deyta is a CLI, so install it as an isolated tool rather than into a project environment. This puts the deyta command on your PATH and keeps its dependencies from colliding with anything else:

uv tool install deyta-cli      # recommended
# or:
pipx install deyta-cli

Both create a dedicated environment just for Deyta and expose deyta everywhere — no virtualenv to activate. To upgrade later: uv tool upgrade deyta-cli (or pipx upgrade deyta-cli).

One-line install (curl):

If you'd rather not pick a tool, this script does it for you:

curl -fsSL https://raw.githubusercontent.com/DeytaHQ/deyta-cli/main/install.sh | sh

It picks an installer in order: uv if present (uv also fetches a Python 3.13 runtime, so you don't need a matching Python first); else pipx if you already have it and Python 3.13+; otherwise it asks before installing uv (and aborts with instructions if you decline) — it never modifies your system silently. Pin a version with DEYTA_VERSION=0.2.0, or set DEYTA_YES=1 to skip the uv prompt in CI.

Prefer to read before you pipe to a shell? Download, inspect, then run:

curl -fsSLO https://raw.githubusercontent.com/DeytaHQ/deyta-cli/main/install.sh
less install.sh        # review it
sh install.sh

This is a convenience wrapper, not a separate channel — it installs the same PyPI package as uv tool / pipx below.

macOS (Homebrew):

brew tap deytahq/deyta
brew trust deytahq/deyta    # current Homebrew requires trusting any third-party tap
brew install deyta

This installs into its own virtualenv (using prebuilt wheels for the native dependencies) and puts deyta on your PATH. Upgrade with brew upgrade deyta.

The brew trust step is a Homebrew default for all non-official taps, not something specific to Deyta — without it Homebrew refuses to load the formula.

Avoid pip install deyta-cli. Bare pip installs into whatever Python environment happens to be active, so the deyta command only works while that environment is activated — and it can clash with other packages. Use uv tool / pipx for CLIs.

From source (development)

git clone https://github.com/DeytaHQ/deyta-cli && cd deyta-cli
uv sync                        # creates .venv with all deps
uv run deyta --help            # run without activating the venv

Quickstart (embedded, no Docker)

deyta init                 # choose "embedded (sqlite_lance, no Docker)"
deyta up                   # start the whole stack in the background (datastores if postgres, then the daemon)

deyta ns create demo       # create a namespace; becomes active
deyta ingest ./docs        # walk files, chunk + remember (Rich progress)
deyta query "your question"

deyta down                 # stop the stack when you're done

deyta up is the one-command path; deyta serve still exists if you'd rather run the daemon in the foreground (and deyta db up to manage just the datastores).

Commands

Command	Purpose
deyta init	Scaffold deyta.toml (pick backend, ontology defaults)
deyta serve [--port] [--detach]	Start the daemon (foreground by default)
deyta status / deyta stop	Inspect / stop a detached daemon
deyta up / deyta down	Bring the whole local stack up/down (datastores + server)
deyta db up|down|status|logs	Manage Postgres + Neo4j (Docker; postgres backend)
deyta ns create|list|get|delete|use	Manage namespaces (namespace is the long form)
deyta memory remember|recall|forget|ingest	Khora primitives
deyta ingest <path>	Shorthand for memory ingest
deyta query "<text>"	Shorthand for memory recall (--mode, -k, --json, --context)
deyta config	Interactive TUI editor for deyta.toml settings
deyta config get|set <key>	Read/write a single config value (dot notation, e.g. llm.model)
deyta config path	Print the resolved config file path
deyta context use|list|current	Switch between local and (future) cloud
deyta login / logout	Cloud auth (not yet available)
deyta version [--no-check]	Show installed CLI + Khora versions; flag PyPI updates
deyta update [--yes] [--dry-run]	Upgrade whichever of the CLI / Khora is outdated

Backends

• embedded (sqlite_lance) — SQLite + LanceDB, fully in-process, zero infra. Default for quickstart.
• postgres — Postgres + pgvector + Neo4j via deyta db up (vendored Docker Compose, pinned to pgvector/pgvector:pg17 and neo4j:2025.12.1).

Configuration & state

• ~/.config/deyta/deyta.toml — main config: backend, server port, LLM settings, default ontology, namespace aliases, active namespace.
• ~/.config/deyta/.env — secrets (DEYTA_OPENAI_API_KEY, optionally DEYTA_API_KEY).
• ~/.config/deyta/config.toml — contexts (local/cloud). auth.json holds cloud tokens.
• ~/.config/deyta/daemon.json — runtime state for a detached daemon (pid/port).

deyta config opens an interactive editor for deyta.toml — arrow keys to navigate, Enter to edit a value inline, s to save, q to quit. For scripting: deyta config get llm.model / deyta config set llm.model gpt-4o.

Ontology: deyta init writes a generic default entity_types / relationship_types so deyta ingest works with no flags; override per run with --entity-types / --relationship-types.

Server API key (optional)

Set DEYTA_API_KEY to require Bearer-token authentication on every request. When the variable is unset the server accepts unauthenticated requests (the default for local-only use). deyta init prompts for this; you can also add it directly to ~/.config/deyta/.env:

DEYTA_API_KEY=your-secret-here

Clients must then send Authorization: Bearer your-secret-here on each request. The TypeScript SDK already sends the apiKey you pass at construction, so no SDK changes are needed — just pass the same value.

Releasing

The package builds with hatchling; the deyta command comes from the [project.scripts] entry point in pyproject.toml. Pushing a vX.Y.Z tag publishes to PyPI (via GitHub Actions Trusted Publishing) and bumps the Homebrew tap. See RELEASING.md for the one-time setup and the release steps.