Command-Line Interface

cortexdb-cli is a Click + Rich CLI that wraps the v1 HTTP API in a small, fast binary. It works against CortexDB Cloud or any self-hosted CortexDB deployment.

pip install cortexdb-cli

Requires Python 3.10+. The cortexdb-cli version line is independent of the CortexDB server version; see Versioning and SDK compatibility.

The happy path on CortexDB Cloud

Create an API token on your dashboard (it shows your actor and default scope too), put the four values in the environment, and go:

export CORTEXDB_URL=https://api.cortexdb.ai
export CORTEXDB_API_KEY='<your API token>'
export CORTEXDB_ACTOR=user:acct_42
export CORTEXDB_SCOPE=org:acct_42/user:acct_42

cortexdb experience "Q3 revenue: $2.4M, $10M ARR target"   # store
cortexdb recall     "Q3 revenue?"                          # retrieve

cortexdb init signs up anonymously instead (POST /v1/auth/signup) and persists the identity to ~/.cortexdb/state.json (mode 0600 on POSIX). That needs a server whose minter allows anonymous signup, such as a self-hosted dev server started with CORTEX_V1_MINTER_ENABLE=1; CortexDB Cloud has it off, since its accounts come from cortexdb.ai.

Commands

cortexdb auth tokens --subject agent:b --ttl 3600 --confine 'scope.read:org:acme/team:b/*'

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",
  "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,
      "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.

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.

verify is safe against a real deployment

verify writes one synthetic marker with ?wait=indexed, so read-your-writes is guaranteed by the time the write returns. 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)

Also available: --config-dir (env CORTEXDB_HOME) isolates one project's identity and checkpoints from another's — --profile alone does not.

Auth notes

Against the cloud (and any server with CORTEX_API_KEY set), authenticated requests carry both Authorization: Bearer <token> and X-Cortex-Actor — the bearer is a PASETO v4 token, or the CORTEX_API_KEY value itself on self-hosted servers. The CLI stamps both for you.

• 401s show the specific error code (TOKEN_EXPIRED, ACTOR_MISMATCH, INVALID_TOKEN_SIGNATURE) and the remediation: on CortexDB Cloud, a new token from your dashboard.
• 403s cite the missing capability and the policy tier that denied. If a recall returns diagnostics.read denied, pass --diagnostics none — CortexDB Cloud tokens don't carry diagnostics.read (the CLI defaults to none).
• On CortexDB Cloud, 402 PLAN_LIMIT_REACHED and 429 SUBTREE_RATE_LIMITED mean a plan limit (Plans and limits).
• Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Reset, X-Cortex-Token-Expires-In, and X-Cortex-Token-Expires-At; cortexdb admin usage surfaces them.

Profiles

Run against multiple deployments by passing --profile:

cortexdb --profile prod --endpoint https://api.cortexdb.ai --api-key "$PROD_TOKEN" --actor user:acct_42 auth whoami
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, or isolate with --config-dir.

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.