Installation
CLI 0.38.0 requires Node.js 24.15.0 or newer and uses the selected project's Convex 1.46.0 executable. The Basic app additionally requires npm 12.2.0 or newer; upgrade npm explicitly before installing it. SDK/provider 0.38.0, apps 1.2.0 and catalog 1.1.0 have separate release versions; package declarations remain authoritative for their own runtime requirements.
The Python SDK remains archived in _DEPRECATED/cortex-sdk-python in Project-Cortex. Use the TypeScript SDK for current development; the archive receives no new releases.
npm install -g @cortexmemory/cli@0.38.0
cortex --version
cortex --help
For a project-local CLI, use npm install --save-dev @cortexmemory/cli@0.38.0 and npx cortex. An unpublished release needs its explicit matching local archives; unavailable registry versions do not select an older SDK.
New or existing SDK project
cortex init my-agent --template basic --local --yes --graph none
cortex init backend --template none --local --yes --graph none
cortex install ./existing-project --no-deploy --yes --graph none --dry-run
cortex install ./existing-project --no-deploy --yes --graph none
Basic/backend-only init is separate from application templates. Existing-project installation supports a standalone npm project and protects conflicts. --no-install requires --no-deploy; --local and --cloud conflict. Cloud staging uses --cloud --no-deploy and separate native target setup.
Use the actual local URL reported by setup and associate the project with a deployment alias:
cortex config add-deployment local --url http://127.0.0.1:3210 --json-only
cortex config set-path local ./my-agent
cortex dev -d local --local
dev/start run one foreground Convex child. Ctrl-C stops it; run the application's script in another terminal. There is no detached supervisor or port-kill dashboard. status/doctor are read-only; explicit --check performs a bounded backend check.
Application templates and optional graph
cortex templates list --format json
cortex templates init demo --template vercel-ai-quickstart --template-version 1.2.0 --catalog-version 1.1.0 --yes --graph none
cortex templates init chat --template chat-sdk --template-version 1.2.0 --catalog-version 1.1.0 --yes --graph none
Basic uses npm 12.2.0 or newer; Vercel uses npm and Chat uses pnpm 10.33.0. The CLI does not download or switch managers, and dry-run/no-install remain manager-free. Follow the generated README for the composed backend, private server keys, exact localhost origin and normal session setup. CLI builds do not copy a quickstart mirror. Template update and SDK update are independent. If external update work fails, inspect the operation receipt, use journal-only templates update ./demo --recover, and manually reconcile external effects before acknowledging with --recover --yes; recovery never replays dependencies/backend/graph.
Both SDK init/install and template init support the same shared optional graph service; explicit cortex graph setup uses it too. Graph off needs no Docker. Local Neo4j/Memgraph setup owns only project-specific resources, and stop preserves volumes. Existing-service configuration probes without graph data writes. Credentials stay in matching provider environment or private files.
Updates and shell completion
cortex update -d local --sdk-version 0.38.0 --convex-version 1.46.0 --sync --dry-run
cortex templates update ./demo --to 1.2.0 --catalog-version 1.1.0 --dry-run
cortex completion bash
cortex completion zsh
cortex completion fish
Completion is explicit script output; installation/uninstallation does not edit shell RC files. For the recognized old Next shim lacking MutationCtx, update the template/app before synchronizing the SDK backend. User conflicts and arbitrary schemas remain refused. See the CLI reference for exact migration and snapshot limitations.