cortexdb-cli 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

cortexdb_cli/__init__.py

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

cortexdb_cli/client.py

@@ -63,6 +63,14 @@ class CortexClient:
     ) -> httpx.Response:
         return self._http.post(path, json=json, params=params)
 
+    def put(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        return self._http.put(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)
 

cortexdb_cli/commands/admin.py

@@ -1,15 +1,21 @@
-"""cortexdb admin - health, usage, layer stats."""
+"""cortexdb admin - health, usage, layer stats, retention, unified WAL."""
 
 from __future__ import annotations
 
+from typing import Any
+
 import click
 
 from cortexdb_cli.client import get_client
 from cortexdb_cli.errors import handle_errors
 from cortexdb_cli.output import (
+    console,
+    escape,
     is_json_mode,
     print_health,
+    print_json,
     print_ontology,
+    print_success,
     print_usage,
     spinner,
 )
@@ -81,3 +87,526 @@ def admin_layers(ctx: click.Context) -> None:
             resp = client.get("/v1/admin/layers/stats")
         resp.raise_for_status()
         print_ontology(resp.json(), cfg)
+
+
+# -- retention (unified WAL) -------------------------------------------------
+#
+# The operator surface over the D1 retention plane. Every write here is
+# irreversible in effect - an applied sweep ERASES expired captured events
+# through the ordinary erasure plane - so reporting is the default on both
+# mutating commands and `--apply` is the only thing that sends
+# `dry_run: false`.
+
+
+def _parse_source_days(pairs: tuple[str, ...]) -> dict[str, int]:
+    """Parse repeated ``--source-days KEY=N`` options into the wire map.
+
+    Only the option's own grammar is checked here (KEY=VALUE, N a positive
+    integer). The ``source:`` prefix rule and the 1..=36500 ceiling belong to
+    the server's governance validator, which answers 422
+    INVALID_RETENTION_POLICY - duplicating them here would let the CLI and
+    the server disagree about what a valid rule is.
+    """
+    out: dict[str, int] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise click.UsageError(f"--source-days must be KEY=DAYS, got {pair!r}")
+        key, raw = pair.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise click.UsageError(f"--source-days needs a key, got {pair!r}")
+        try:
+            days = int(raw)
+        except ValueError:
+            raise click.UsageError(
+                f"--source-days value must be a whole number of days, got {raw!r}"
+            ) from None
+        if days < 1:
+            raise click.UsageError(
+                f"--source-days must be at least 1 day, got {days} for {key!r}"
+            )
+        if key in out:
+            raise click.UsageError(f"--source-days {key!r} given twice")
+        out[key] = days
+    return out
+
+
+def _print_retention_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/retention."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    config = Table(title="[header]Retention[/header]", border_style="cyan")
+    config.add_column("Setting", style="bold")
+    config.add_column("Value")
+    interval = data.get("sweep_interval_secs", 0)
+    if data.get("enabled"):
+        scheduled = "yes"
+    elif data.get("scheduler_disabled"):
+        scheduled = "[warning]no (CORTEX_SCHEDULER_DISABLE)[/warning]"
+    else:
+        scheduled = "no (operator-triggered only)"
+    config.add_row("scheduled", scheduled)
+    config.add_row("sweep interval", f"{interval}s" if interval else "-")
+    default_days = data.get("deployment_default_days")
+    config.add_row("deployment default", f"{default_days}d" if default_days else "keep")
+    config.add_row("max events/tick", str(data.get("max_events_per_tick", "")))
+    config.add_row("tick budget", str(data.get("tick_budget_secs", "")) + "s")
+    config.add_row(
+        "compact after sweep", "yes" if data.get("compact_after_sweep") else "no"
+    )
+    config.add_row("cursor", str(data.get("cursor", "")))
+    config.add_row("watermark", str(data.get("watermark", "")))
+    config.add_row(
+        "cursor trustworthy",
+        "yes" if data.get("fingerprint_ok") else "no (next applied tick rescans)",
+    )
+    config.add_row("running", "yes" if data.get("running") else "no")
+    if data.get("native_profile_blocked"):
+        config.add_row("native profile", "[warning]retention refused[/warning]")
+    console.print(config)
+
+    policies = data.get("policies") or []
+    if policies:
+        table = Table(title="[header]Policies[/header]", border_style="cyan")
+        table.add_column("Scope", style="bold")
+        table.add_column("Default", justify="right")
+        table.add_column("Per-source", style="dim")
+        for entry in policies:
+            policy = entry.get("policy") or {}
+            days = policy.get("default_retention_days")
+            per_source = policy.get("per_source_days") or {}
+            table.add_row(
+                escape(str(entry.get("scope", ""))),
+                f"{days}d" if days else "keep",
+                escape(", ".join(f"{k}={v}d" for k, v in sorted(per_source.items()))),
+            )
+        console.print(table)
+    else:
+        console.print("[dim]No per-scope retention rules stored.[/dim]")
+
+    last = data.get("last")
+    if isinstance(last, dict):
+        note = " [warning](dry run)[/warning]" if last.get("dry_run") else ""
+        console.print(
+            "[dim]Last tick:[/dim] "
+            f"scanned {last.get('scanned', 0)}, "
+            f"expired {last.get('expired', 0)}, "
+            f"erased {last.get('erased', 0)}, "
+            f"stopped {escape(str(last.get('stopped', '')))}" + note
+        )
+
+
+def _print_sweep_report(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/retention/sweep (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "erased" not in data:
+        # 202: the tick outlived the blocking-lane deadline and is still going.
+        poll = escape(str(data.get("poll", "/v1/admin/retention")))
+        console.print(
+            Panel(
+                f"Sweep still running; poll [bold]{poll}[/bold]",
+                title="[header]Retention sweep[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] captured row(s)",
+        f"expired [bold]{data.get('expired', 0)}[/bold], "
+        f"erased [bold]{data.get('erased', 0)}[/bold], "
+        f"kept forever [bold]{data.get('kept_forever', 0)}[/bold]",
+        f"cursor {data.get('cursor_before', 0)} -> {data.get('cursor_after', 0)} "
+        f"(watermark {data.get('watermark', 0)})",
+        f"stopped: {escape(str(data.get('stopped', '')))} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    held = data.get("held") or {}
+    if isinstance(held, dict) and any(held.values()):
+        lines.append(f"[dim]held: {escape(str(held))}[/dim]")
+    for error in data.get("errors") or []:
+        lines.append(f"[error]{escape(str(error))}[/error]")
+    title = "[header]Retention sweep" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+def _print_wal_status(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render GET /v1/admin/wal."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.table import Table
+
+    table = Table(title="[header]Unified WAL[/header]", border_style="cyan")
+    table.add_column("Field", style="bold")
+    table.add_column("Value", justify="right")
+    for label, key in (
+        ("live rows", "live_count"),
+        ("next offset", "next_offset"),
+        ("head offset", "head_offset"),
+        ("captured head", "captured_head_offset"),
+        ("partitions", "partitions"),
+        ("retired markers", "retired_marker_count"),
+    ):
+        value = data.get(key)
+        table.add_row(label, "-" if value is None else str(value))
+    if data.get("native_profile_blocked"):
+        table.add_row("native profile", "[warning]mutations refused[/warning]")
+    console.print(table)
+
+    consumers = data.get("consumer_offsets") or {}
+    if consumers:
+        floors = Table(title="[header]Consumer floors[/header]", border_style="cyan")
+        floors.add_column("Consumer", style="bold")
+        floors.add_column("Offset", justify="right")
+        for name, offset in sorted(consumers.items()):
+            floors.add_row(escape(str(name)), str(offset))
+        console.print(floors)
+
+    verify = data.get("verify")
+    if isinstance(verify, dict):
+        ok = verify.get("ok")
+        if ok is None:
+            # Not a verdict: the self-check is bounded and a production-sized
+            # log is past that bound, so nothing was checked. Rendering this
+            # as a failure is how a healthy store gets restored from backup.
+            skipped = escape(
+                str(verify.get("skipped", "log exceeds the bounded self-check"))
+            )
+            console.print(f"[warning]Integrity check not run:[/warning] {skipped}")
+        elif ok:
+            console.print("[success]Integrity check passed.[/success]")
+        else:
+            reason = escape(str(verify.get("reason", "unknown")))
+            console.print(f"[error]Integrity check failed:[/error] {reason}")
+
+
+def _print_compaction(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render POST /v1/admin/wal/compact (or its 202 still-running body)."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.panel import Panel
+
+    if "removed_tombstones" not in data:
+        poll = escape(str(data.get("poll", "/v1/admin/wal")))
+        console.print(
+            Panel(
+                f"Compaction still running; poll [bold]{poll}[/bold]",
+                title="[header]WAL compaction[/header]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    dry = data.get("dry_run", True)
+    lines = [
+        f"scanned [bold]{data.get('scanned', 0)}[/bold] row(s)",
+        f"removed {data.get('removed_tombstones', 0)} tombstone(s), "
+        f"{data.get('removed_orphaned_twins', 0)} orphaned twin(s)",
+        f"skipped {data.get('skipped_in_use', 0)} in use, "
+        f"{data.get('skipped_above_bound', 0)} above the bound",
+        f"live rows {data.get('live_count_before', 0)} -> "
+        f"{data.get('live_count_after', 0)}, "
+        f"{data.get('bytes_removed', 0)} byte(s) reclaimed",
+        f"ranges compacted: {data.get('ranges_compacted', 0)} "
+        f"in {data.get('elapsed_ms', 0)}ms",
+    ]
+    if data.get("truncated_by_budget"):
+        lines.append("[warning]Budget reached - rerun to continue.[/warning]")
+    title = "[header]WAL compaction" + (" (dry run)" if dry else " (APPLIED)")
+    console.print(
+        Panel(
+            "\n".join(lines),
+            title=title + "[/header]",
+            border_style="yellow" if dry else "red",
+        )
+    )
+
+
+@admin_group.group("retention")
+def retention_group() -> None:
+    """Unified-WAL retention - per-scope rules and the expiry sweep.
+
+    Requires trusted-operator access. Reporting needs `diagnostics.read`;
+    storing a rule or applying a sweep needs `admin.compact`.
+    """
+
+
+@retention_group.command("show")
+@click.pass_context
+@handle_errors
+def retention_show(ctx: click.Context) -> None:
+    """Config, stored rules, cursor and last tick (GET /v1/admin/retention).
+
+    503 NOT_AVAILABLE when this process runs no retention sweeper (legacy
+    WAL, no coordinator, or a configuration the sweeper refused).
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading retention status..."):
+                resp = client.get("/v1/admin/retention")
+        else:
+            resp = client.get("/v1/admin/retention")
+        resp.raise_for_status()
+        _print_retention_status(resp.json(), cfg)
+
+
+@retention_group.command("set")
+@click.option("--scope", "-S", required=True, help="Scope path the rule is keyed on.")
+@click.option(
+    "--days",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Expire captured events after this many days. Omit for an explicit KEEP.",
+)
+@click.option(
+    "--source-days",
+    "source_days",
+    multiple=True,
+    metavar="KEY=DAYS",
+    help="Per-source override, e.g. source:slack=30. Repeatable.",
+)
+@click.pass_context
+@handle_errors
+def retention_set(
+    ctx: click.Context,
+    scope: str,
+    days: int | None,
+    source_days: tuple[str, ...],
+) -> None:
+    """Store the retention rule for one scope (PUT /v1/admin/retention/policies).
+
+    Irreversible in effect: an applied sweep under this rule ERASES expired
+    events from the scope and every scope beneath it. Omitting `--days`
+    stores an explicit KEEP, which overrides the deployment default for the
+    subtree but never a shorter rule inherited from an ancestor scope.
+    Storing a rule always resets the durable sweep cursor.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"scope": scope, "default_retention_days": days}
+    per_source = _parse_source_days(source_days)
+    if per_source:
+        body["per_source_days"] = per_source
+    with get_client(cfg) as client:
+        resp = client.put("/v1/admin/retention/policies", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    policy = data.get("policy") or {}
+    stored = policy.get("default_retention_days")
+    reset = " (sweep cursor reset)" if data.get("cursor_reset") else ""
+    print_success(
+        f"Retention rule stored for {scope}: "
+        + (f"{stored} day(s)" if stored else "keep")
+        + reset
+    )
+
+
+@retention_group.command("delete")
+@click.option("--scope", "-S", required=True, help="Scope path whose rule to remove.")
+@click.pass_context
+@handle_errors
+def retention_delete(ctx: click.Context, scope: str) -> None:
+    """Remove one scope's rule (DELETE /v1/admin/retention/policies).
+
+    404 when a well-formed store held no rule for exactly this scope -
+    inheritance is resolution, not storage, so a descendant that expires by
+    an ancestor's rule has no rule of its own to delete. Resets the durable
+    sweep cursor, like `set`.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.delete("/v1/admin/retention/policies", params={"scope": scope})
+        resp.raise_for_status()
+    if is_json_mode(cfg):
+        print_json({"scope": scope, "deleted": True, "cursor_reset": True})
+        return
+    print_success(f"Retention rule removed for {scope} (sweep cursor reset)")
+
+
+@retention_group.command("sweep")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="ERASE expired events. Without it the tick only reports.",
+)
+@click.option("--scope", "-S", default=None, help="Confine the scan to this subtree.")
+@click.option(
+    "--older-than-secs",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Request-only TTL override for --scope. Never persisted.",
+)
+@click.option(
+    "--max-events",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Override the per-tick expiry budget.",
+)
+@click.option(
+    "--rescan",
+    is_flag=True,
+    default=False,
+    help="Ignore the durable cursor and scan from the start of the log.",
+)
+@click.pass_context
+@handle_errors
+def retention_sweep(
+    ctx: click.Context,
+    apply_: bool,
+    scope: str | None,
+    older_than_secs: int | None,
+    max_events: int | None,
+    rescan: bool,
+) -> None:
+    """Run one retention tick (POST /v1/admin/retention/sweep).
+
+    DRY RUN IS THE DEFAULT - the tick reports what would be erased and
+    writes nothing. `--apply` is what sends `dry_run: false`, which erases
+    expired captured events irreversibly and needs `admin.compact`.
+
+    Single-flight: a second concurrent tick is refused with 409
+    RETENTION_SWEEP_RUNNING rather than queued.
+    """
+    cfg = ctx.obj
+    if older_than_secs is not None and not scope:
+        raise click.UsageError("--older-than-secs requires --scope.")
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if scope:
+        body["scope"] = scope
+    if older_than_secs is not None:
+        body["older_than_secs"] = older_than_secs
+    if max_events is not None:
+        body["max_events"] = max_events
+    if rescan:
+        body["rescan"] = True
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Sweeping..."):
+                resp = client.post("/v1/admin/retention/sweep", json=body)
+        else:
+            resp = client.post("/v1/admin/retention/sweep", json=body)
+        resp.raise_for_status()
+        _print_sweep_report(resp.json(), cfg)
+
+
+@admin_group.group("wal")
+def wal_group() -> None:
+    """Unified write-ahead log - census and dead-row compaction.
+
+    Requires trusted-operator access. A legacy data dir is refused with 409
+    RETENTION_UNSUPPORTED_BACKEND naming the offline migrator.
+    """
+
+
+@wal_group.command("status")
+@click.option(
+    "--verify",
+    is_flag=True,
+    default=False,
+    help=(
+        "Also run the bounded row-level self-check (clamped server-side). "
+        "The check is bounded at 1M rows / 512 MiB, which a production-sized "
+        "log exceeds: it then reports 'not run', which is not a failure."
+    ),
+)
+@click.pass_context
+@handle_errors
+def wal_status(ctx: click.Context, verify: bool) -> None:
+    """Live rows, offsets, consumer floors, markers (GET /v1/admin/wal)."""
+    cfg = ctx.obj
+    params = {"verify": "true"} if verify else None
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading WAL census..."):
+                resp = client.get("/v1/admin/wal", params=params)
+        else:
+            resp = client.get("/v1/admin/wal", params=params)
+        resp.raise_for_status()
+        _print_wal_status(resp.json(), cfg)
+
+
+@wal_group.command("compact")
+@click.option(
+    "--apply",
+    "apply_",
+    is_flag=True,
+    default=False,
+    help="Physically remove the dead rows. Without it the run only reports.",
+)
+@click.option(
+    "--max-rows",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Upper bound on dead rows removed in one sweep.",
+)
+@click.option(
+    "--below-offset",
+    type=click.IntRange(min=0),
+    default=None,
+    help="Exclusive offset bound. Defaults to the indexer watermark.",
+)
+@click.option(
+    "--compaction",
+    type=click.Choice(["none", "touched_ranges", "full"]),
+    default=None,
+    help="Physical reclamation mode. `full` is a whole-CF compaction.",
+)
+@click.pass_context
+@handle_errors
+def wal_compact(
+    ctx: click.Context,
+    apply_: bool,
+    max_rows: int | None,
+    below_offset: int | None,
+    compaction: str | None,
+) -> None:
+    """Reclaim already-dead WAL rows (POST /v1/admin/wal/compact).
+
+    Removes only rows that are ALREADY logically dead - redaction
+    tombstones and orphaned Derived twins. It never removes a live row and
+    never touches derived-artifact history.
+
+    DRY RUN IS THE DEFAULT; `--apply` is what sends `dry_run: false` and
+    needs `admin.compact`. Single-flight: 409 WAL_COMPACTION_RUNNING.
+    """
+    cfg = ctx.obj
+    body: dict[str, Any] = {"dry_run": not apply_}
+    if max_rows is not None:
+        body["max_rows"] = max_rows
+    if below_offset is not None:
+        body["below_offset"] = below_offset
+    if compaction is not None:
+        body["compaction"] = compaction
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Compacting..."):
+                resp = client.post("/v1/admin/wal/compact", json=body)
+        else:
+            resp = client.post("/v1/admin/wal/compact", json=body)
+        resp.raise_for_status()
+        _print_compaction(resp.json(), cfg)

cortexdb_cli/commands/code.py

@@ -36,25 +36,81 @@ def _echo(cfg, payload) -> None:
 @code_group.command("add")
 @click.argument("name")
 @click.argument("path", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--scope",
+    default=None,
+    help=(
+        "Parent scope the repository binds under (default: the tenant "
+        "root org:<billing id>). Every later read or mutation is "
+        "authorized against that binding."
+    ),
+)
 @click.pass_context
 @handle_errors
-def code_add(ctx: click.Context, name: str, path: str) -> None:
+def code_add(ctx: click.Context, name: str, path: str, scope: str | None) -> None:
     """Register + index a local repository (POST /v1/code/repos).
 
     NAME is the repo handle used by every other verb; PATH is the local
     checkout. Indexing runs synchronously and reports the fact counts.
+
+    --scope binds the repository under a scope you already own; the
+    server appends a stable ``repo:<dirname>-<digest>`` segment and the
+    response reports the resulting binding. A scope that does not parse,
+    or a ``global:`` one, is refused 422 INVALID_SCOPE; one you may not
+    register under is 403 POLICY_DENIED.
     """
     cfg = ctx.obj
     absolute = str(pathlib.Path(path).resolve())
+    body: dict = {"name": name, "path": absolute}
+    if scope is not None:
+        body["scope"] = scope
     with get_client(cfg) as client:
         with spinner(f"Indexing {name}..."):
-            resp = client.post(
-                "/v1/code/repos", json={"name": name, "path": absolute}
-            )
+            resp = client.post("/v1/code/repos", json=body)
         resp.raise_for_status()
         _echo(cfg, resp.json())
 
 
+@code_group.command("remove")
+@click.argument("name")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+@handle_errors
+def code_remove(ctx: click.Context, name: str, yes: bool) -> None:
+    """De-register a repository AND free its bytes (DELETE
+    /v1/code/repos/NAME).
+
+    Prints the purge report: the directory that was removed, how many
+    bytes it held, and whether the registry journal was compacted (a
+    false there means the bytes are gone but the journal still names the
+    checkout path; removing the same name again retries it).
+
+    503 REPO_PURGE_BUSY means the repository is ALREADY de-registered but
+    readers still hold its stores open - run the same command again to
+    finish freeing the directory.
+    """
+    cfg = ctx.obj
+    if not yes and not is_json_mode(cfg):
+        click.confirm(
+            f"Remove repository {name} and delete its indexed data?", abort=True
+        )
+    with get_client(cfg) as client:
+        with spinner(f"Purging {name}..."):
+            resp = client.delete(f"/v1/code/repos/{name}")
+        resp.raise_for_status()
+        body = resp.json()
+    if is_json_mode(cfg):
+        _echo(cfg, body)
+        return
+    purge = body.get("purge") or {}
+    click.echo(f"Removed {body.get('removed', name)}")
+    click.echo(f"  scope:      {purge.get('scope', '')}")
+    click.echo(f"  directory:  {purge.get('directory', '')}")
+    click.echo(f"  freed:      {purge.get('bytes_freed', 0)} bytes")
+    compacted = "compacted" if purge.get("registry_compacted") else "NOT compacted"
+    click.echo(f"  registry:   {compacted}")
+
+
 @code_group.command("status")
 @click.argument("name", required=False)
 @click.pass_context

{cortexdb_cli-0.5.2.dist-info → cortexdb_cli-0.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdb-cli
-Version: 0.5.2
+Version: 0.5.4
 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.2.dist-info → cortexdb_cli-0.5.4.dist-info}/RECORD

@@ -1,5 +1,5 @@
-cortexdb_cli/__init__.py,sha256=E9HyqRe9juxBYu8xwyA9tk6TUvi3rTeVOfrdIvcJFPA,90
-cortexdb_cli/client.py,sha256=CQwGo4Gn7cHDnfLUlJBZMsZ9-AyGVz8W6bJKxNMwlRA,2862
+cortexdb_cli/__init__.py,sha256=R-3t2jLxSGdc1xNb9pu6tbckqSCXYYrp2zCV8lOqSsE,93
+cortexdb_cli/client.py,sha256=Abgv8CLbhNYKG0QqHjsdGFXWZuVhke4Zuc4TAOuGjG4,3086
 cortexdb_cli/config.py,sha256=ee1qmOfqMwilL81ujaqjf6TjjlrFG7WZAHRIgeyif9U,5690
 cortexdb_cli/errors.py,sha256=xwxAWYY7KtNa-e7dyLQECnsKcciVcKC41CXFFF_-0VU,3924
 cortexdb_cli/harness_packs_data.py,sha256=38oyPX47a_S3BRgiNxml37auhIUyWafeJ_MtApX9tWE,10693
@@ -8,13 +8,13 @@ cortexdb_cli/onboarding.py,sha256=kjCxhMOY2nReNyEfGGGsmHO6_j4CXS5o2LIwzpFzIok,17
 cortexdb_cli/output.py,sha256=9NvXhX3ncCIgP9BMzt7c9VReQc0O1FUbQTwj2vUQ2JI,13611
 cortexdb_cli/state.py,sha256=pfslyJ9xuZno4n13-maJ0qKmD7nxWkFznjrVvItYK4I,1527
 cortexdb_cli/commands/__init__.py,sha256=TeF4ieMQkbgBr9Fco9VAiIZvKQ4vdg4yhkz4fvwfToc,37
-cortexdb_cli/commands/admin.py,sha256=0vy8B1Lk1M0-6P964GgFkdxpujQ-on_pjfJyLvafuzw,2510
+cortexdb_cli/commands/admin.py,sha256=KzCiRSLeDkVHGa_V1AYwk4--KVkC2GI9giZc0LDN8pY,21633
 cortexdb_cli/commands/answer.py,sha256=41Yl9pjfODyRnWzYL68nRA7GPDb73Cccj0Kq-8sLv9k,3343
 cortexdb_cli/commands/audit.py,sha256=br9ksMeR4dHBkfvNvGG4mjYdhh7E1IRxJ1FOX1klckQ,2620
 cortexdb_cli/commands/auth.py,sha256=6YoKl5mZcyep2FRMrnXRv_EKvblC6H2vKfVOBzDXgpo,4505
 cortexdb_cli/commands/beliefs.py,sha256=akjOg2drLqQKlrGVL-Z6oLdP6TY-4YHe3yg9lJpQPH4,6180
 cortexdb_cli/commands/claims.py,sha256=NApq0i8NXX0j7uwnHdHtendnblMBnHh0OXlwQwB-tCQ,3720
-cortexdb_cli/commands/code.py,sha256=VWUV3uxpBuEu7N_EJfZvtSsQfTggf4xv3Buc7qdsOPI,8454
+cortexdb_cli/commands/code.py,sha256=QMlE9RwNFEQsRqQrUvqlKA2c0v7sKLU2vcyQiW1uZ10,10719
 cortexdb_cli/commands/compose.py,sha256=i9fEugN818mt1t8nWsAxvv9h0nNLvBAf-WZZIl64xiw,3853
 cortexdb_cli/commands/config_cmd.py,sha256=MCb5XoulnGLkeOzYY54R_hFnTxGWAboLARSe8zAEhXA,1522
 cortexdb_cli/commands/conflicts.py,sha256=s4sp3BtPzPEy3T73inx68vhmucvjh-zQRnWYsJ_ADQQ,10506
@@ -34,7 +34,7 @@ cortexdb_cli/commands/scopes.py,sha256=Cx_zV-zyIrnDxwp_I4AX_Teh7UFu4EdvDOYe9hTEF
 cortexdb_cli/commands/search.py,sha256=4wsgNU47deb0x5o7xC9eWlhwdIIbz56q7ne8GIiCmYo,1953
 cortexdb_cli/commands/understanding.py,sha256=BktqOn-GloOzSSGJGK9xh5kGCpxcrwkNogtXhjj4pBI,5371
 cortexdb_cli/commands/wire.py,sha256=M3UUHScmvr_MDrX_RaMBg-YLTcHKUq9woNkT4KHJKfs,8131
-cortexdb_cli-0.5.2.dist-info/METADATA,sha256=CIgu0dksEWHPqVq3WHPmOq2kQRxkMf3U00ZlltMO620,4429
-cortexdb_cli-0.5.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-cortexdb_cli-0.5.2.dist-info/entry_points.txt,sha256=h3sEbdqqvtv8LBbRLUgybYPo9N2lpU85fQUSh5ToEvs,51
-cortexdb_cli-0.5.2.dist-info/RECORD,,
+cortexdb_cli-0.5.4.dist-info/METADATA,sha256=wNeADaguuwEJjnQgsLpwnOnMKaWGSZMfnKfgXARS2JU,5234
+cortexdb_cli-0.5.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cortexdb_cli-0.5.4.dist-info/entry_points.txt,sha256=h3sEbdqqvtv8LBbRLUgybYPo9N2lpU85fQUSh5ToEvs,51
+cortexdb_cli-0.5.4.dist-info/RECORD,,