Metadata-Version: 2.4
Name: deyta-cli
Version: 0.1.1
Summary: A unified command-line tool for Deyta's services, wrapping Khora persistent memory for AI agents.
Project-URL: Homepage, https://github.com/DeytaHQ/deyta-cli
Project-URL: Repository, https://github.com/DeytaHQ/deyta-cli
Project-URL: Issues, https://github.com/DeytaHQ/deyta-cli/issues
Author-email: "AllTheData Inc. (Deyta)" <dev@deyta.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,cli,embeddings,khora,memory,rag,typer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: khora[embedded]>=0.19.0
Requires-Dist: packaging>=24.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=15.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: typer>=0.26.7
Requires-Dist: uvicorn[standard]>=0.34.0
Description-Content-Type: text/markdown

# Deyta CLI

A unified command-line tool for Deyta's services. Today it wraps
[Khora](https://github.com/DeytaHQ/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+
- `OPENAI_API_KEY` in the environment (Khora uses it for embeddings and entity extraction)
- 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:

```bash
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:

```bash
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:

```bash
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):**

```bash
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)

```bash
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)

```bash
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 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

- `./deyta.toml` — project config: backend, server port, default ontology, namespace
  name→UUID aliases, active namespace. Commit this.
- `./.deyta/` — runtime state for a detached daemon (pid/port, logs). Gitignored.
- `~/.config/deyta/config.toml` — contexts (local/cloud). `auth.json` holds cloud tokens.

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

## 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](RELEASING.md) for the one-time setup and the release steps.
