Metadata-Version: 2.4
Name: cortexdb-cli
Version: 0.2.0
Summary: Command-line interface for CortexDB — the long-term memory layer for AI.
Project-URL: Homepage, https://cortexdb.ai
Project-URL: Documentation, https://cortexdb.ai/docs
Project-URL: Repository, https://github.com/cortexdb/cortexdb
Project-URL: Issues, https://github.com/cortexdb/cortexdb/issues
Author-email: CortexDB Team <team@cortexdb.ai>
License-Expression: Apache-2.0
Keywords: agents,ai,cli,cortexdb,llm,memory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich-click>=1.7
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# cortexdb-cli

Command-line interface for [CortexDB](https://cortexdb.ai) — the long-term memory layer for AI systems.

Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup
in one command, no email or card; works against the public SaaS or any
self-hosted CortexDB deployment.

## Install

```bash
pip install cortexdb-cli
```

Requires Python 3.10+.

## Quickstart

```bash
# 1. One-time setup — anonymous signup, writes ~/.cortexdb/state.json
cortexdb init

# 2. Store a memory
cortexdb remember "Q3 revenue: $2.4M. We're on track for $10M ARR by year-end."

# 3. Recall it
cortexdb recall "Q3 revenue?"

# 4. Or just type — drops into a REPL
cortexdb
```

The signup token has a 7-day TTL on the free tier. Re-run `cortexdb init`
to refresh, or pass `--api-key` + `--actor` to use a token from your IdP.

## Commands

```
cortexdb init                                 anonymous signup; persist token + actor
cortexdb remember "..."                       store a memory (POST /v1/experience)
cortexdb recall   "..."                       recall a stratified context pack
cortexdb search   "..."                       granular event-level search
cortexdb forget   --memory-id ...             delete with audit
cortexdb episodes {list,get,delete}           episode CRUD
cortexdb entities {list,get,link}             entity rollups over the Facts layer
cortexdb admin    {health,usage,layers}       diagnostics
cortexdb import   data.json                   bulk-load (JSON / JSONL / CSV / TXT)
cortexdb export   -o backup.json              export memories
cortexdb config   {show,set}                  view / edit ~/.cortexdb/config.toml
cortexdb                                      interactive REPL
```

## Configuration

Three layers, in precedence order:

1. **CLI flags** — `--api-key`, `--endpoint`, `--actor`, `--scope`, `--profile`
2. **Environment** — `CORTEXDB_API_KEY`, `CORTEXDB_URL`, `CORTEXDB_ACTOR`, `CORTEXDB_SCOPE`
3. **Persisted state**:
   - `~/.cortexdb/config.toml` — endpoint, profile names (human-editable)
   - `~/.cortexdb/state.json` — token, actor, scope, expiry (managed by `init`, 0600 on POSIX)

The state.json format matches the cortexdb-mcp 0.3.0 server's, so you can
copy state across to use both tools from the same anonymous identity.

## Pipe-friendly

Auto-detects when stdout isn't a TTY and emits JSON:

```bash
cortexdb recall "Q3 revenue" | jq .context_block
cortexdb entities list      | jq '.[].subject'
echo "remember this"        | cortexdb remember -
```

Force JSON mode any time with `--json`.

## Auth notes

- The v1 API requires both `Authorization: Bearer <PASETO>` and `X-Cortex-Actor`.
  The CLI stamps both on every request — you never need to pass them by hand.
- 401s show the specific error code (`TOKEN_EXPIRED`, `actor_mismatch`, …)
  and the remediation: usually `cortexdb init`.
- 403s cite the missing capability and the policy tier that denied. If a
  recall returns `diagnostics.read denied`, pass `--diagnostics none` —
  free-tier tokens don't carry the `diagnostics.read` capability.

## License

Apache-2.0
