cortexdb-cli 0.5.1__tar.gz → 0.5.3__tar.gz

{cortexdb_cli-0.5.1 → cortexdb_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-cli
-Version: 0.5.1
+Version: 0.5.3
 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
@@ -62,8 +62,22 @@ cortexdb recall "Q3 revenue?"
 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.
+The signup token has a 7-day TTL on the free tier.
+
+**Re-running `cortexdb init` does not refresh it.** `init` reuses an existing
+identity and changes nothing; against an expired one it refuses and exits 3.
+That is deliberate: a new identity is a new *brain*, and memories written
+under the old actor stay where they are, unreachable from the new config.
+
+When a token expires you have two safe options:
+
+- `cortexdb init --api-key <token> --actor <actor>` — keep the same brain
+  with a token you already hold (e.g. from your IdP).
+- `cortexdb init --force` — deliberately start a NEW brain. The previous
+  identity is backed up to `state.json.replaced` first.
+
+For a second brain alongside the first, isolate instead of replacing:
+`cortexdb --config-dir <dir> init`, or set `CORTEXDB_HOME`.
 
 ## Commands
 
@@ -112,7 +126,9 @@ Force JSON mode any time with `--json`.
 - 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`.
+  and the remediation. Note that `TOKEN_EXPIRED` is **not** fixed by re-running
+  `cortexdb init` — see the identity note above; that would mint a different
+  brain rather than restore access to yours.
 - 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.

{cortexdb_cli-0.5.1 → cortexdb_cli-0.5.3}/README.md

@@ -1,90 +1,106 @@
-# 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-running `cortexdb init` does not refresh it.** `init` reuses an existing
+identity and changes nothing; against an expired one it refuses and exits 3.
+That is deliberate: a new identity is a new *brain*, and memories written
+under the old actor stay where they are, unreachable from the new config.
+
+When a token expires you have two safe options:
+
+- `cortexdb init --api-key <token> --actor <actor>` — keep the same brain
+  with a token you already hold (e.g. from your IdP).
+- `cortexdb init --force` — deliberately start a NEW brain. The previous
+  identity is backed up to `state.json.replaced` first.
+
+For a second brain alongside the first, isolate instead of replacing:
+`cortexdb --config-dir <dir> init`, or set `CORTEXDB_HOME`.
+
+## 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. Note that `TOKEN_EXPIRED` is **not** fixed by re-running
+  `cortexdb init` — see the identity note above; that would mint a different
+  brain rather than restore access to yours.
+- 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.5.1 → cortexdb_cli-0.5.3}/cortexdb_cli/__init__.py

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

cortexdb_cli-0.5.3/cortexdb_cli/commands/init.py

@@ -0,0 +1,230 @@
+"""cortexdb init - anonymous signup + config persistence."""
+
+from __future__ import annotations
+
+import click
+import httpx
+
+from datetime import datetime, timezone
+
+from cortexdb_cli.client import DEFAULT_ENDPOINT, signup
+from cortexdb_cli.config import config_path, resolve_config_dir, save_config
+from cortexdb_cli.output import console, err_console
+from cortexdb_cli.state import load_state, save_state, state_path
+
+
+def _inherit_group_flag(
+    ctx: click.Context,
+    name: str,
+    own_value: str | None,
+) -> str | None:
+    """Fall back to a flag given at the GROUP level (`cortexdb --endpoint ...
+    init`) when init's own flag wasn't supplied.
+
+    Users reasonably write global flags before the subcommand; Click parses
+    them into the group's params and, before 0.4.1, init silently ignored
+    them - `cortexdb --endpoint X --api-key Y init` performed an anonymous
+    signup against the DEFAULT endpoint. Only the parent's RAW params are
+    consulted (never merged config), so a stale config.toml can't leak into
+    a fresh init. If both levels are set and disagree, init's own flag wins
+    with a warning.
+    """
+    parent = ctx.parent
+    group_value = parent.params.get(name) if parent is not None else None
+    if own_value is not None and group_value is not None and own_value != group_value:
+        console.print(
+            f"[warning]--{name.replace('_', '-')} given both before and after "
+            f"`init` with different values; using {own_value!r}.[/warning]"
+        )
+        return own_value
+    return own_value if own_value is not None else group_value
+
+
+def _existing_identity() -> tuple[dict, str] | None:
+    """Return `(state, status)` for a usable identity already on disk.
+
+    KAN-145/156: `init` used to mint and overwrite unconditionally. Running
+    it twice in one directory replaced a working identity with a brand-new
+    anonymous one - and because the actor and scope change, everything
+    written under the old identity becomes unreachable from this machine.
+    Nothing warned, and nothing had to fail for it to happen: the second
+    `init` looked exactly as successful as the first.
+
+    `status` is "valid" or "expired"; both are treated as "do not silently
+    replace this", because an expired token still names the brain the user's
+    data is in.
+    """
+    state = load_state()
+    if not state.get("token"):
+        return None
+    expires = state.get("expires_at")
+    status = "valid"
+    if expires:
+        try:
+            when = datetime.fromisoformat(str(expires).replace("Z", "+00:00"))
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            if when <= datetime.now(timezone.utc):
+                status = "expired"
+        except (TypeError, ValueError):
+            # An unparseable expiry is not evidence of expiry. Prefer the
+            # conservative reading: something is here, do not clobber it.
+            status = "valid"
+    return state, status
+
+
+def _report_existing(state: dict, status: str) -> None:
+    console.print(f"  [success]Existing identity reused[/success] ({status})")
+    console.print(f"  [success]Actor:[/success] {state.get('user_id', '?')}")
+    console.print(f"  [success]Default scope:[/success] {state.get('scope', '?')}")
+    if state.get("expires_at"):
+        console.print(f"  [dim]Token expires: {state['expires_at']}[/dim]")
+    console.print(f"")
+    console.print(f"[dim]State directory: {resolve_config_dir()}[/dim]")
+
+
+@click.command("init")
+@click.option(
+    "--endpoint",
+    default=None,
+    help=f"CortexDB v1 API base URL.  [default: {DEFAULT_ENDPOINT}]",
+)
+@click.option(
+    "--api-key",
+    default=None,
+    help="Existing PASETO bearer token. If set, skips anonymous signup.",
+)
+@click.option(
+    "--actor",
+    default=None,
+    help="X-Cortex-Actor value. Required when --api-key is set.",
+)
+@click.option(
+    "--scope",
+    default=None,
+    help="Default scope path. Defaults to the actor.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Replace an existing identity. Backs the old one up first. "
+    "A new identity is a NEW brain: memories written under the old actor "
+    "stay where they are and are no longer reachable from this config.",
+)
+@click.pass_context
+def init_cmd(
+    ctx: click.Context,
+    endpoint: str | None,
+    api_key: str | None,
+    actor: str | None,
+    scope: str | None,
+    force: bool,
+) -> None:
+    """Set up CortexDB CLI.
+
+    \b
+    Without flags:      anonymous signup (free tier, 7-day token TTL).
+    With --api-key:     register an existing token + actor (e.g. from your IdP).
+    """
+    # Global-flag inheritance: `cortexdb --endpoint X init` == `cortexdb init --endpoint X`.
+    endpoint = _inherit_group_flag(ctx, "endpoint", endpoint) or DEFAULT_ENDPOINT
+    api_key = _inherit_group_flag(ctx, "api_key", api_key)
+    actor = _inherit_group_flag(ctx, "actor", actor)
+    scope = _inherit_group_flag(ctx, "scope", scope)
+
+    console.print("\n[header]CortexDB CLI setup[/header]\n")
+
+    # Guard BEFORE any signup call or state write. `init` is read-only when a
+    # usable identity already exists: reuse and report it, never replace it
+    # silently. Reminting is a data-reachability event, not a retry.
+    existing = _existing_identity()
+    if existing and not force:
+        state, status = existing
+        if status == "valid":
+            _report_existing(state, status)
+            console.print(
+                "\n[dim]Nothing changed. Use --force to replace this identity, "
+                "or --config-dir / CORTEXDB_HOME for a separate one.[/dim]\n"
+            )
+            return
+        # Expired: still refuse. The token names the brain the user's data is
+        # in, so a silent remint strands it. Say so and make them choose.
+        err_console.print(
+            f"[error]The stored token for {state.get('user_id', '?')} has expired "
+            f"({state.get('expires_at')}).[/error]"
+        )
+        err_console.print(
+            "Refusing to mint a new identity automatically: a new identity is a "
+            "NEW brain, and memories written under the old actor would no longer "
+            "be reachable from this config."
+        )
+        err_console.print(
+            "  To deliberately start a new brain:  cortexdb init --force"
+        )
+        err_console.print(
+            "  To use a token you already hold:    "
+            "cortexdb init --api-key <token> --actor <actor>"
+        )
+        raise SystemExit(3)
+
+    if existing and force:
+        backup = state_path().with_suffix(".json.replaced")
+        try:
+            backup.write_text(
+                state_path().read_text(encoding="utf-8"), encoding="utf-8", newline="\n"
+            )
+            console.print(
+                f"[warning]Replacing the existing identity; "
+                f"previous state saved to {backup}[/warning]"
+            )
+        except OSError as exc:
+            console.print(
+                f"[warning]Could not back up existing state ({exc}); continuing[/warning]"
+            )
+
+    if api_key:
+        if not actor:
+            raise click.UsageError("--actor is required when --api-key is supplied.")
+        # Pure config write - no signup call.
+        save_config("default", {"endpoint": endpoint})
+        save_state(
+            {
+                "token": api_key,
+                "user_id": actor,
+                "scope": scope or actor,
+                "source": "explicit",
+            }
+        )
+        console.print(f"[success]Saved token + actor to {state_path()}[/success]")
+        console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
+        return
+
+    # Anonymous signup path.
+    console.print(f"  Endpoint: [bold]{endpoint}[/bold]")
+    console.print("  No email, no card - free tier, 7-day token TTL.\n")
+
+    try:
+        resp = signup(endpoint)
+    except httpx.HTTPError as exc:
+        console.print(f"[error]Signup failed: {exc}[/error]")
+        raise SystemExit(2) from exc
+
+    state = {
+        "token": resp["token"],
+        "user_id": resp["user_id"],
+        "scope": resp.get("scope") or resp["user_id"],
+        "expires_at": resp.get("expires_at"),
+        "tier": resp.get("tier", "free"),
+        "source": "signup",
+    }
+    save_state(state)
+    save_config("default", {"endpoint": endpoint})
+
+    console.print(f"  [success]Token minted[/success]  (expires {resp.get('expires_at', '?')})")
+    console.print(f"  [success]Actor:[/success] {resp['user_id']}")
+    console.print(f"  [success]Default scope:[/success] {state['scope']}")
+    console.print(f"\n[dim]State written to {state_path()}[/dim]")
+    console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
+    console.print("Try it:\n")
+    console.print('  [bold]cortexdb remember "Q3 revenue: $2.4M"[/bold]')
+    console.print('  [bold]cortexdb recall   "Q3 revenue?"[/bold]\n')

{cortexdb_cli-0.5.1 → cortexdb_cli-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cortexdb-cli"
-version = "0.5.1"
+version = "0.5.3"
 description = "Command-line interface for CortexDB — the long-term memory layer for AI."
 readme = "README.md"
 license = "Apache-2.0"

cortexdb_cli-0.5.1/cortexdb_cli/commands/init.py

@@ -1,129 +0,0 @@
-"""cortexdb init - anonymous signup + config persistence."""
-
-from __future__ import annotations
-
-import click
-import httpx
-
-from cortexdb_cli.client import DEFAULT_ENDPOINT, signup
-from cortexdb_cli.config import config_path, save_config
-from cortexdb_cli.output import console
-from cortexdb_cli.state import save_state, state_path
-
-
-def _inherit_group_flag(
-    ctx: click.Context,
-    name: str,
-    own_value: str | None,
-) -> str | None:
-    """Fall back to a flag given at the GROUP level (`cortexdb --endpoint ...
-    init`) when init's own flag wasn't supplied.
-
-    Users reasonably write global flags before the subcommand; Click parses
-    them into the group's params and, before 0.4.1, init silently ignored
-    them - `cortexdb --endpoint X --api-key Y init` performed an anonymous
-    signup against the DEFAULT endpoint. Only the parent's RAW params are
-    consulted (never merged config), so a stale config.toml can't leak into
-    a fresh init. If both levels are set and disagree, init's own flag wins
-    with a warning.
-    """
-    parent = ctx.parent
-    group_value = parent.params.get(name) if parent is not None else None
-    if own_value is not None and group_value is not None and own_value != group_value:
-        console.print(
-            f"[warning]--{name.replace('_', '-')} given both before and after "
-            f"`init` with different values; using {own_value!r}.[/warning]"
-        )
-        return own_value
-    return own_value if own_value is not None else group_value
-
-
-@click.command("init")
-@click.option(
-    "--endpoint",
-    default=None,
-    help=f"CortexDB v1 API base URL.  [default: {DEFAULT_ENDPOINT}]",
-)
-@click.option(
-    "--api-key",
-    default=None,
-    help="Existing PASETO bearer token. If set, skips anonymous signup.",
-)
-@click.option(
-    "--actor",
-    default=None,
-    help="X-Cortex-Actor value. Required when --api-key is set.",
-)
-@click.option(
-    "--scope",
-    default=None,
-    help="Default scope path. Defaults to the actor.",
-)
-@click.pass_context
-def init_cmd(
-    ctx: click.Context,
-    endpoint: str | None,
-    api_key: str | None,
-    actor: str | None,
-    scope: str | None,
-) -> None:
-    """Set up CortexDB CLI.
-
-    \b
-    Without flags:      anonymous signup (free tier, 7-day token TTL).
-    With --api-key:     register an existing token + actor (e.g. from your IdP).
-    """
-    # Global-flag inheritance: `cortexdb --endpoint X init` == `cortexdb init --endpoint X`.
-    endpoint = _inherit_group_flag(ctx, "endpoint", endpoint) or DEFAULT_ENDPOINT
-    api_key = _inherit_group_flag(ctx, "api_key", api_key)
-    actor = _inherit_group_flag(ctx, "actor", actor)
-    scope = _inherit_group_flag(ctx, "scope", scope)
-
-    console.print("\n[header]CortexDB CLI setup[/header]\n")
-
-    if api_key:
-        if not actor:
-            raise click.UsageError("--actor is required when --api-key is supplied.")
-        # Pure config write - no signup call.
-        save_config("default", {"endpoint": endpoint})
-        save_state(
-            {
-                "token": api_key,
-                "user_id": actor,
-                "scope": scope or actor,
-                "source": "explicit",
-            }
-        )
-        console.print(f"[success]Saved token + actor to {state_path()}[/success]")
-        console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
-        return
-
-    # Anonymous signup path.
-    console.print(f"  Endpoint: [bold]{endpoint}[/bold]")
-    console.print("  No email, no card - free tier, 7-day token TTL.\n")
-
-    try:
-        resp = signup(endpoint)
-    except httpx.HTTPError as exc:
-        console.print(f"[error]Signup failed: {exc}[/error]")
-        raise SystemExit(2) from exc
-
-    state = {
-        "token": resp["token"],
-        "user_id": resp["user_id"],
-        "scope": resp.get("scope") or resp["user_id"],
-        "expires_at": resp.get("expires_at"),
-        "tier": resp.get("tier", "free"),
-        "source": "signup",
-    }
-    save_state(state)
-    save_config("default", {"endpoint": endpoint})
-
-    console.print(f"  [success]Token minted[/success]  (expires {resp.get('expires_at', '?')})")
-    console.print(f"  [success]Actor:[/success] {resp['user_id']}")
-    console.print(f"  [success]Default scope:[/success] {state['scope']}")
-    console.print(f"\n[dim]State written to {state_path()}[/dim]")
-    console.print(f"[dim]Endpoint stored in {config_path()}[/dim]\n")
-    console.print("Try it:\n")
-    console.print('  [bold]cortexdb remember "Q3 revenue: $2.4M"[/bold]')
-    console.print('  [bold]cortexdb recall   "Q3 revenue?"[/bold]\n')