Command-Line Interface

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

pip install cortexdb-cli

Requires Python 3.10+.

The three-line happy path

cortexdb init                                            # anonymous signup, writes ~/.cortexdb/state.json
cortexdb experience "Q3 revenue: $2.4M, $10M ARR target"  # store
cortexdb recall     "Q3 revenue?"                         # retrieve

init posts to /v1/auth/signup, gets a token + actor + scope, and persists everything to ~/.cortexdb/state.json (mode 0600 on POSIX). The token has a 7-day TTL on the free tier — re-run init to refresh, or pass --api-key + --actor when you have a permanent identity from your IdP.

Commands

cortexdb remember "..." is a hidden alias for experience — kept so old scripts and muscle memory keep working.

Onboarding and diagnostics

Eight commands exist specifically so a coding agent can install, verify and diagnose CortexDB without guessing. They share one output envelope and one exit-code contract.

cortexdb preflight            # can this machine talk to CortexDB at all?
cortexdb plan                 # what would apply do? (no writes)
cortexdb apply                # do it, checkpointing after each stage
cortexdb resume               # continue after an interruption
cortexdb doctor               # why is my existing install unhappy?
cortexdb verify               # prove write -> recall -> cleanup end to end
cortexdb cleanup              # remove what verify/apply created

One envelope

Every one of them emits the same document, so you parse one shape rather than eight. --json works before or after the subcommand, and is implied when stdout is not a TTY.

{
  "schema": "cortexdb.cli.diagnostic/v1",
  "command": "doctor",
  "ok": false,
  "exit_code": 11,
  "outcome": "failure",
  "first_failing_stage": "authenticated",   // start here
  "counts": { "pass": 4, "fail": 1, "skip": 0, "blocked": 1 },
  "stages": [
    {
      "id": "authenticated",
      "title": "Token is accepted",
      "state": "fail",
      "detail": "HTTP 401: token expired",
      "retriable": false,                    // retrying will not help
      "remediation": "The token is missing, expired or revoked. Run `cortexdb init`.",
      "doc_url": "https://cortexdb.ai/docs/api-reference/auth"
    }
  ]
}

Every stage that is not pass carries retriable, remediation and doc_url. A failure you cannot act on is not a diagnostic.

Exit codes

Branch on these instead of parsing the message:

blocked is deliberately distinct from fail: "you have no credentials" and "your credentials were rejected" need different responses.

Stages are idempotent

Each stage probes before it acts, so a stage that is already satisfied reports skip with the reason. Re-running a partial onboarding is safe, apply never mints a second identity, and resume is simply apply reading the checkpoint at ~/.cortexdb/onboarding.json.

apply stops at the first failing stage rather than continuing — the stages after it would only report consequences and bury the real cause.

verify is safe to run against a real deployment

verify writes one synthetic marker with ?wait=indexed, so read-your-writes is guaranteed by the time the write returns and a recall miss is a genuine miss rather than a race. Everything it writes goes into a cortexdb-cli-verify leaf subtree of your scope, and cleanup removes exactly that subtree — it cannot reach your real data.

Pass --keep to leave the marker in place for inspection.

Pipe-friendly

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

cortexdb recall "Q3 revenue" | jq .context_block
cortexdb facts list          | jq '.items[] | {predicate, object}'
echo "remember this"         | cortexdb experience -
cat envelopes.jsonl          | cortexdb experience bulk -

Force JSON any time with --json.

Configuration

Three layers, in precedence order (high to low):

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 server's (0.6.0), so a user who signed up through one tool can copy state across to use the other from the same anonymous identity.

Auth notes

• Against the cloud (and any server with CORTEX_API_KEY set), the v1 API requires both Authorization: Bearer <token> and X-Cortex-Actor on every request — the bearer is a PASETO v4 token, or the CORTEX_API_KEY value itself on self-hosted servers. The CLI stamps both for you — you never need to pass them by hand. (A self-hosted server with no CORTEX_API_KEY runs in local no-auth mode and serves everything as user:local.)
• 401s show the specific error code (TOKEN_EXPIRED, actor_mismatch, INVALID_TOKEN_SIGNATURE) 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 diagnostics.read. (The CLI defaults to none already.)
• Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Reset, X-Cortex-Token-Expires-In, and X-Cortex-Token-Expires-At headers; cortexdb admin usage surfaces them.

Profiles

Run against multiple deployments by passing --profile:

cortexdb --profile prod init --endpoint https://api-v1.cortexdb.ai
cortexdb --profile staging init --endpoint https://staging.cortexdb.example
cortexdb --profile staging experience "test memory"

Each profile gets its own block in ~/.cortexdb/config.toml. The state.json is shared — if you need separate identities per profile, run cortexdb auth signup --save after switching.

See also

• Python SDK — programmatic access from Python.
• TypeScript SDK — programmatic access from JS/TS.
• MCP Server — same v1 surface exposed to Claude / Cursor / VS Code Copilot.
• Auth — how tokens, actors, and capabilities fit together.