cortexdb-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/.gitignore

@@ -69,3 +69,14 @@ dist/
 # Scratch/debug text files at root
 /*.txt
 /*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/
+
+# doc-claims verifier scratch output
+tools/verifier_out*/

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-cli
-Version: 0.2.0
+Version: 0.4.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

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/README.md

@@ -1,90 +1,90 @@
-# 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
+# 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

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB CLI — command-line interface for the v1 memory API."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/cortexdb_cli/client.py

@@ -1,92 +1,92 @@
-"""HTTP client for the CortexDB v1 API.
-
-Thin wrapper around httpx that reads credentials + endpoint from the CLI
-context and stamps every request with both `Authorization: Bearer …` and
-`X-Cortex-Actor: …`. The actor header is mandatory on v1 — missing it
-returns 401 ACTOR_MISMATCH no matter how valid the token is.
-
-We deliberately don't depend on the cortexdbai SDK: keeping the CLI a
-straight HTTP client makes the install fast and lets us pin httpx
-independently from the SDK's release cadence.
-"""
-
-from __future__ import annotations
-
-from contextlib import contextmanager
-from typing import Any, Generator
-
-import httpx
-
-from cortexdb_cli import __version__
-
-DEFAULT_ENDPOINT = "https://api-v1.cortexdb.ai"
-
-
-class CortexClient:
-    """Synchronous HTTP client for the CortexDB v1 API."""
-
-    def __init__(
-        self,
-        endpoint: str,
-        api_key: str,
-        actor: str = "",
-        timeout: float = 30.0,
-    ) -> None:
-        self.endpoint = endpoint.rstrip("/")
-        self.api_key = api_key
-        self.actor = actor
-        headers: dict[str, str] = {
-            "Content-Type": "application/json",
-            "User-Agent": f"cortexdb-cli/{__version__}",
-        }
-        if api_key:
-            headers["Authorization"] = f"Bearer {api_key}"
-        if actor:
-            headers["X-Cortex-Actor"] = actor
-        self._http = httpx.Client(
-            base_url=self.endpoint,
-            headers=headers,
-            timeout=timeout,
-        )
-
-    def close(self) -> None:
-        self._http.close()
-
-    def get(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
-        return self._http.get(path, params=params)
-
-    def post(
-        self,
-        path: str,
-        json: dict[str, Any] | None = None,
-        params: dict[str, Any] | None = None,
-    ) -> httpx.Response:
-        return self._http.post(path, json=json, params=params)
-
-    def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
-        return self._http.delete(path, params=params)
-
-
-def signup(endpoint: str = DEFAULT_ENDPOINT, timeout: float = 30.0) -> dict[str, Any]:
-    """Call POST /v1/auth/signup and return {token, user_id, scope, expires_at, tier}.
-
-    The endpoint is public — no auth required. Free tier; 7-day TTL.
-    """
-    with httpx.Client(timeout=timeout) as http:
-        resp = http.post(f"{endpoint.rstrip('/')}/v1/auth/signup", json={})
-        resp.raise_for_status()
-        return resp.json()
-
-
-@contextmanager
-def get_client(ctx: dict[str, Any]) -> Generator[CortexClient, None, None]:
-    """Create a CortexClient from CLI context."""
-    client = CortexClient(
-        endpoint=ctx.get("endpoint", DEFAULT_ENDPOINT),
-        api_key=ctx.get("api_key", ""),
-        actor=ctx.get("actor", ""),
-    )
-    try:
-        yield client
-    finally:
-        client.close()
+"""HTTP client for the CortexDB v1 API.
+
+Thin wrapper around httpx that reads credentials + endpoint from the CLI
+context and stamps every request with both `Authorization: Bearer …` and
+`X-Cortex-Actor: …`. The actor header is mandatory on v1 — missing it
+returns 401 ACTOR_MISMATCH no matter how valid the token is.
+
+We deliberately don't depend on the cortexdbai SDK: keeping the CLI a
+straight HTTP client makes the install fast and lets us pin httpx
+independently from the SDK's release cadence.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Generator
+
+import httpx
+
+from cortexdb_cli import __version__
+
+DEFAULT_ENDPOINT = "https://api-v1.cortexdb.ai"
+
+
+class CortexClient:
+    """Synchronous HTTP client for the CortexDB v1 API."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        actor: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+        self.actor = actor
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "User-Agent": f"cortexdb-cli/{__version__}",
+        }
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        if actor:
+            headers["X-Cortex-Actor"] = actor
+        self._http = httpx.Client(
+            base_url=self.endpoint,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        return self._http.get(path, params=params)
+
+    def post(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        return self._http.post(path, json=json, params=params)
+
+    def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        return self._http.delete(path, params=params)
+
+
+def signup(endpoint: str = DEFAULT_ENDPOINT, timeout: float = 30.0) -> dict[str, Any]:
+    """Call POST /v1/auth/signup and return {token, user_id, scope, expires_at, tier}.
+
+    The endpoint is public — no auth required. Free tier; 7-day TTL.
+    """
+    with httpx.Client(timeout=timeout) as http:
+        resp = http.post(f"{endpoint.rstrip('/')}/v1/auth/signup", json={})
+        resp.raise_for_status()
+        return resp.json()
+
+
+@contextmanager
+def get_client(ctx: dict[str, Any]) -> Generator[CortexClient, None, None]:
+    """Create a CortexClient from CLI context."""
+    client = CortexClient(
+        endpoint=ctx.get("endpoint", DEFAULT_ENDPOINT),
+        api_key=ctx.get("api_key", ""),
+        actor=ctx.get("actor", ""),
+    )
+    try:
+        yield client
+    finally:
+        client.close()

{cortexdb_cli-0.2.0 → cortexdb_cli-0.4.0}/cortexdb_cli/commands/admin.py

@@ -1,83 +1,83 @@
-"""cortexdb admin — health, usage, layer stats."""
-
-from __future__ import annotations
-
-import click
-
-from cortexdb_cli.client import get_client
-from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import (
-    is_json_mode,
-    print_health,
-    print_ontology,
-    print_usage,
-    spinner,
-)
-
-
-@click.group("admin")
-def admin_group() -> None:
-    """Diagnostics — reachability, identity, rate-limit, layer status."""
-
-
-@admin_group.command("health")
-@click.pass_context
-@handle_errors
-def admin_health(ctx: click.Context) -> None:
-    """Auth + reachability check (GET /v1/auth/whoami)."""
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        resp = client.get("/v1/auth/whoami")
-        resp.raise_for_status()
-        body = resp.json()
-        # Normalise into the shape print_health expects.
-        body.setdefault("status", "ok")
-        print_health(body, cfg)
-
-
-@admin_group.command("usage")
-@click.pass_context
-@handle_errors
-def admin_usage(ctx: click.Context) -> None:
-    """Tier, capabilities, rate-limit headroom, token expiry."""
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Loading usage..."):
-                resp = client.get("/v1/auth/whoami")
-        else:
-            resp = client.get("/v1/auth/whoami")
-        resp.raise_for_status()
-        body = resp.json()
-        # Fold rate-limit + expiry response headers into the body so the
-        # output formatter can render them in one block.
-        for k in (
-            "X-RateLimit-Limit",
-            "X-RateLimit-Reset",
-            "X-RateLimit-Remaining",
-            "X-Cortex-Token-Expires-In",
-            "X-Cortex-Token-Expires-At",
-        ):
-            if k in resp.headers:
-                body[k] = resp.headers[k]
-        print_usage(body, cfg)
-
-
-@admin_group.command("layers")
-@click.pass_context
-@handle_errors
-def admin_layers(ctx: click.Context) -> None:
-    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
-
-    Stability: experimental — the endpoint is gated by the
-    `admin.layers.stats` capability and may not be present on the free tier.
-    """
-    cfg = ctx.obj
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Loading layer stats..."):
-                resp = client.get("/v1/admin/layers/stats")
-        else:
-            resp = client.get("/v1/admin/layers/stats")
-        resp.raise_for_status()
-        print_ontology(resp.json(), cfg)
+"""cortexdb admin — health, usage, layer stats."""
+
+from __future__ import annotations
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import (
+    is_json_mode,
+    print_health,
+    print_ontology,
+    print_usage,
+    spinner,
+)
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Diagnostics — reachability, identity, rate-limit, layer status."""
+
+
+@admin_group.command("health")
+@click.pass_context
+@handle_errors
+def admin_health(ctx: click.Context) -> None:
+    """Auth + reachability check (GET /v1/auth/whoami)."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Normalise into the shape print_health expects.
+        body.setdefault("status", "ok")
+        print_health(body, cfg)
+
+
+@admin_group.command("usage")
+@click.pass_context
+@handle_errors
+def admin_usage(ctx: click.Context) -> None:
+    """Tier, capabilities, rate-limit headroom, token expiry."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading usage..."):
+                resp = client.get("/v1/auth/whoami")
+        else:
+            resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Fold rate-limit + expiry response headers into the body so the
+        # output formatter can render them in one block.
+        for k in (
+            "X-RateLimit-Limit",
+            "X-RateLimit-Reset",
+            "X-RateLimit-Remaining",
+            "X-Cortex-Token-Expires-In",
+            "X-Cortex-Token-Expires-At",
+        ):
+            if k in resp.headers:
+                body[k] = resp.headers[k]
+        print_usage(body, cfg)
+
+
+@admin_group.command("layers")
+@click.pass_context
+@handle_errors
+def admin_layers(ctx: click.Context) -> None:
+    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
+
+    Stability: experimental — the endpoint is gated by the
+    `admin.layers.stats` capability and may not be present on the free tier.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading layer stats..."):
+                resp = client.get("/v1/admin/layers/stats")
+        else:
+            resp = client.get("/v1/admin/layers/stats")
+        resp.raise_for_status()
+        print_ontology(resp.json(), cfg)