Cortex CLI Reference
Last Updated: 2026-01-08 | CLI Version: 0.27.4 | Package: @cortexmemory/cli
What is Cortex CLI?
The Cortex CLI is a command-line tool for managing Cortex Memory deployments, performing administrative tasks, and streamlining development workflows. It provides comprehensive functionality for:
- Project initialization and lifecycle management
- Database operations and statistics
- Memory management (vector store operations)
- User data management with GDPR compliance
- Deployment management across multiple environments
- Interactive development with live-reloading
Installation
Install via Homebrew (Recommended):
$ brew install cortex-memory/tap/cliOr install globally via npm:
$ npm install -g @cortexmemory/cliOr use with npx (no installation needed):
$ npx @cortexmemory/cli <command>Or install as dev dependency in your project:
$ npm install --save-dev @cortexmemory/cliRequirements: Node.js >= 20
Quick Start
The most common workflow for getting started:
Initialize a new Cortex project
$ cortex init my-cortex-appStart development services
$ cortex startCheck status
$ cortex statusView database statistics
$ cortex db statsList memory spaces
$ cortex spaces listCommand Categories
Project Lifecycle
Commands for managing your Cortex project lifecycle:
cortex init- Initialize a new Cortex Memory projectcortex start- Start development servicescortex stop- Stop background servicescortex dev- Interactive development mode (Expo-style)cortex status- Show status dashboard
Configuration
Commands for managing CLI configuration:
cortex config- Configuration managementcortex use- Switch deployment context
Data Operations
Commands for managing data:
cortex memory- Memory operations (vector store)cortex users- User management with GDPR supportcortex spaces- Memory space operationscortex facts- Facts operationscortex conversations- Conversation operations
Database
Commands for database-wide operations:
cortex db stats- Show database statisticscortex db clear- Clear entire databasecortex db backup- Backup databasecortex db restore- Restore from backupcortex db export- Export all data
Deployment
Commands for deploying and updating:
cortex deploy- Deploy schema and functionscortex update- Update packages across deploymentscortex convex- Convex management
Global Options
These options work with ALL commands:
| Option | Description |
|---|---|
-d, --deployment <name> | Use a named deployment from config |
--debug | Enable debug output |
-h, --help | Display help for command |
-V, --version | Output version number |
Most data operation commands also support:
| Option | Description |
|---|---|
-f, --format <format> | Output format: table, json, csv |
-l, --limit <number> | Maximum number of results |
-y, --yes | Skip confirmation prompts |
Detailed Command Reference
Project Lifecycle Commands
cortex init
Initialize a new Cortex Memory project with interactive setup wizard.
Usage:
cortex init [directory] [options]
Arguments:
directory- Target directory (defaults to current directory)
Options:
--local- Quick setup with local Convex only [default: false]--cloud- Quick setup with cloud Convex only [default: false]--skip-graph- Skip graph database setup [default: false]-t, --template <name>- Template to use [default: "basic"]-y, --yes- Skip confirmation prompts [default: false]--start- Start Convex dev server after setup [default: false]
Examples:
# Interactive setup (recommended)
cortex init
# Create project with local Convex (fastest)
cortex init my-app --local
# Create project with cloud Convex
cortex init my-app --cloud
# Create and start immediately
cortex init my-app --local --start
# Skip graph database setup
cortex init my-app --skip-graph
What It Does:
- Creates project directory and copies template files
- Configures Convex backend (local or cloud)
- Optionally sets up graph database (Neo4j or Memgraph)
- Optionally configures OpenAI API key
- Installs dependencies
- Deploys Cortex backend functions
- Saves deployment configuration to
~/.cortexrc - Optionally installs Vercel AI quickstart demo
Related:
cortex start
Start development services for all enabled deployments.
Usage:
cortex start [options]
Options:
-d, --deployment <name>- Start a specific deployment only-l, --local- Use Convex local beta mode (starts a new local backend) [default: false]-f, --foreground- Run in foreground (only works with single deployment) [default: false]--convex-only- Only start Convex servers [default: false]--graph-only- Only start graph databases [default: false]
Examples:
# Start all enabled deployments
cortex start
# Start specific deployment
cortex start --deployment production
# Start with local Convex
cortex start --local
# Start in foreground (see logs)
cortex start --deployment local --foreground
# Start only graph databases
cortex start --graph-only
What It Does:
- Reads deployment configuration from
~/.cortexrc - For each enabled deployment:
- Starts graph database if configured
- Deploys functions to production (for cloud deployments)
- Starts Convex dev server in background
- Starts enabled template apps
- Saves process IDs for later management
Related:
cortex stop
Stop background services (Convex, graph database, and apps).
Usage:
cortex stop [options]
Options:
-d, --deployment <name>- Stop specific deployment only-a, --app <name>- Stop specific app only--convex-only- Only stop Convex server [default: false]--graph-only- Only stop graph database [default: false]--apps-only- Only stop template apps [default: false]
Examples:
# Stop all services
cortex stop
# Stop specific deployment
cortex stop --deployment local
# Stop specific app
cortex stop --app quickstart
# Stop only Convex (leave graph running)
cortex stop --convex-only
What It Does:
- Finds running processes using PID files
- Sends SIGTERM to Convex dev servers
- Stops Docker containers for graph databases
- Stops template apps
- Cleans up PID files
Related:
cortex dev
Start interactive development mode with Expo-style interface.
Usage:
cortex dev [options]
Options:
-d, --deployment <name>- Run specific deployment only-l, --local- Force local Convex instance for all deployments [default: false]
Keyboard Shortcuts:
c- Clear screen and show statuss- Show status dashboardr- Restart all servicesg- Toggle graph databasek- Kill Convex instances (port conflicts)q- Quit (or Ctrl+C)?orh- Show help
Examples:
# Start interactive dev mode
cortex dev
# Dev mode for specific deployment
cortex dev --deployment local
# Force local mode
cortex dev --local
What It Does:
- Syncs schema files from SDK
- Starts all enabled deployments and apps
- Displays live status dashboard
- Streams aggregated logs from all services
- Provides keyboard shortcuts for common actions
- Handles graceful shutdown on exit
Features:
- Multi-deployment support
- Live status updates
- Aggregated streaming logs
- Keyboard shortcuts
- Automatic schema sync
- Graph database management
Related:
cortex status
Show Cortex setup status dashboard for all deployments.
Usage:
cortex status [options]
Options:
-d, --deployment <name>- Show status for specific deployment only--check- Run health checks [default: false]-f, --format <format>- Output format:dashboard,json[default: "dashboard"]
Examples:
# Show status for all deployments
cortex status
# Status for specific deployment
cortex status --deployment production
# JSON output
cortex status --format json
What It Shows:
- All configured deployments
- Convex backend status (running/stopped)
- Graph database status (running/stopped/not configured)
- Template apps status
- SDK version information
- Process IDs and ports
- Dashboard URLs
Related:
Configuration Commands
cortex config
Manage CLI configuration. The config command has multiple subcommands:
cortex config show
Show current configuration.
Usage:
cortex config show [options]
Options:
-f, --format <format>- Output format:table,json
Examples:
# Show configuration
cortex config show
# JSON output
cortex config show --format json
cortex config list
List all deployments in table format.
Usage:
cortex config list
Examples:
# List all deployments and apps
cortex config list
Output:
- Deployment name, status, URL, key status, project path
- Apps with their type, status, and port
- Default deployment indicator (→)
- Enabled/disabled status
cortex config set
Set a configuration value.
Usage:
cortex config set <key> <value>
Examples:
# Set default deployment
cortex config set default production
# Set output format
cortex config set format json
cortex config test
Test connection to Convex deployment.
Usage:
cortex config test [options]
Options:
-d, --deployment <name>- Deployment to test
Examples:
# Test default deployment
cortex config test
# Test specific deployment
cortex config test --deployment production
cortex config add-deployment
Add a new deployment configuration.
Usage:
cortex config add-deployment [name] [options]
Options:
-u, --url <url>- Convex deployment URL-k, --key <key>- Convex deploy key--default- Set as default deployment [default: false]--json-only- Only save to ~/.cortexrc (skip .env.local) [default: false]
Examples:
# Interactive mode
cortex config add-deployment
# Add cloud deployment
cortex config add-deployment cloud \
--url https://my-app.convex.cloud \
--key "prod|abc123..."
# Add and set as default
cortex config add-deployment staging \
--url https://staging.convex.cloud \
--default
cortex config remove-deployment
Remove a deployment configuration.
Usage:
cortex config remove-deployment [name] [options]
Options:
--json-only- Only remove from ~/.cortexrc (skip .env.local) [default: false]
Examples:
# Interactive mode
cortex config remove-deployment
# Remove specific deployment
cortex config remove-deployment staging
Note: Cannot remove the default deployment. Set a different default first.
cortex config set-key
Set or update the deploy key for a deployment.
Usage:
cortex config set-key [deployment] [options]
Options:
-k, --key <key>- Deploy key (will prompt if not provided)--json-only- Only update ~/.cortexrc (skip .env.local) [default: false]
Examples:
# Interactive mode
cortex config set-key
# Set key for specific deployment
cortex config set-key production --key "prod|abc123..."
cortex config set-url
Set or update the URL for a deployment.
Usage:
cortex config set-url [deployment] [options]
Options:
-u, --url <url>- Deployment URL (will prompt if not provided)--json-only- Only update ~/.cortexrc (skip .env.local) [default: false]
Examples:
# Interactive mode
cortex config set-url
# Set URL for specific deployment
cortex config set-url production --url "https://new-app.convex.cloud"
cortex config set-path
Set project path for a deployment (enables cortex start -d <name> from anywhere).
Usage:
cortex config set-path <deployment> [path]
Examples:
# Set path to current directory
cortex config set-path production
# Set specific path
cortex config set-path production /path/to/project
cortex config enable
Enable a deployment or app (will be started with cortex start).
Usage:
cortex config enable <name>
Examples:
# Enable deployment
cortex config enable production
# Enable app
cortex config enable quickstart
cortex config disable
Disable a deployment or app (will not be started with cortex start).
Usage:
cortex config disable <name>
Examples:
# Disable deployment
cortex config disable staging
# Disable app
cortex config disable quickstart
cortex config path
Show configuration file paths.
Usage:
cortex config path
Shows:
- User config path (
~/.cortexrc) - Project config paths
- Environment variables
cortex config reset
Reset configuration to defaults.
Usage:
cortex config reset [options]
Options:
-y, --yes- Skip confirmation [default: false]
Examples:
# Reset configuration
cortex config reset
This cannot be undone.
cortex use
Set current deployment for all commands (session context).
Usage:
cortex use [deployment] [options]
Options:
--clear- Clear the current deployment setting
Examples:
# Show current deployment
cortex use
# Switch to production
cortex use production
# Clear current deployment
cortex use --clear
What It Does:
- Sets a "current deployment" for the session
- All subsequent commands will use this deployment by default
- Stored separately from the default deployment in config
Memory Commands
cortex memory
Manage memories (vector store). The memory command has multiple subcommands:
cortex memory list
List memories in a memory space.
Usage:
cortex memory list [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-u, --user <id>- Filter by user ID-l, --limit <number>- Maximum number of results [default: 50]-f, --format <format>- Output format:table,json,csv
Examples:
# List memories in a space
cortex memory list --space agent-1
# Filter by user
cortex memory list --space agent-1 --user user-123
# Increase limit
cortex memory list --space agent-1 --limit 100
Related:
cortex memory search
Search memories by content.
Usage:
cortex memory search <query> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-u, --user <id>- Filter by user ID-l, --limit <number>- Maximum number of results [default: 20]-f, --format <format>- Output format:table,json,csv
Examples:
# Search memories
cortex memory search "password preferences" --space agent-1
# Search for specific user
cortex memory search "API keys" --space agent-1 --user user-123
# Increase results
cortex memory search "configuration" --space agent-1 --limit 50
cortex memory get
Get details of a specific memory.
Usage:
cortex memory get <memoryId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)--include-conversation- Include source conversation [default: false]-f, --format <format>- Output format:table,json
Examples:
# Get memory details
cortex memory get mem-123 --space agent-1
# Include source conversation
cortex memory get mem-123 --space agent-1 --include-conversation
cortex memory delete
Delete a specific memory.
Usage:
cortex memory delete <memoryId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)--cascade- Also delete associated facts [default: false]-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Delete memory
cortex memory delete mem-123 --space agent-1
# Delete with cascade (also deletes facts)
cortex memory delete mem-123 --space agent-1 --cascade
Deletion is permanent and cannot be undone.
cortex memory clear
Clear multiple memories.
Usage:
cortex memory clear [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-u, --user <id>- Only clear memories for this user--source <type>- Only clear memories of this source type-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Clear all memories in a space
cortex memory clear --space agent-1
# Clear memories for specific user
cortex memory clear --space agent-1 --user user-123
# Clear by source type
cortex memory clear --space agent-1 --source conversation
This operation is permanent and cannot be undone.
cortex memory export
Export memories to a file.
Usage:
cortex memory export [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-u, --user <id>- Only export memories for this user-o, --output <file>- Output file path [default: "memories-export.json"]--include-facts- Include associated facts [default: false]-f, --format <format>- Export format:json,csv[default: "json"]
Examples:
# Export memories
cortex memory export --space agent-1 --output memories.json
# Export with facts
cortex memory export --space agent-1 --include-facts
# Export as CSV
cortex memory export --space agent-1 --format csv --output memories.csv
cortex memory stats
Show memory statistics for a space.
Usage:
cortex memory stats [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-f, --format <format>- Output format:table,json
Examples:
# Show statistics
cortex memory stats --space agent-1
# JSON output
cortex memory stats --space agent-1 --format json
cortex memory archive
Archive a memory (soft delete).
Usage:
cortex memory archive <memoryId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Archive memory
cortex memory archive mem-123 --space agent-1
Note: Archived memories can be restored later using cortex memory restore.
cortex memory restore
Restore an archived memory.
Usage:
cortex memory restore <memoryId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)
Examples:
# Restore memory
cortex memory restore mem-123 --space agent-1
User Commands
cortex users
Manage user profiles and data with GDPR compliance support.
cortex users list
List all user profiles with usage stats.
Usage:
cortex users list [options]
Options:
-d, --deployment <name>- Target deployment-l, --limit <number>- Maximum number of results [default: 50]-f, --format <format>- Output format:table,json,csv--no-stats- Skip gathering usage stats (faster)
Examples:
# List users
cortex users list
# List without stats (faster)
cortex users list --no-stats
# Increase limit
cortex users list --limit 100
Related:
cortex users get
Get user profile details.
Usage:
cortex users get <userId> [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json--include-history- Include version history [default: false]
Examples:
# Get user profile
cortex users get user-123
# Include version history
cortex users get user-123 --include-history
cortex users delete
Delete user profile with optional GDPR cascade deletion.
Usage:
cortex users delete <userId> [options]
Options:
-d, --deployment <name>- Target deployment--cascade- Delete all user data across all layers (GDPR) [default: false]--dry-run- Preview what would be deleted without actually deleting [default: false]--verify- Verify deletion completeness after cascade [default: true]-y, --yes- Skip confirmation prompt (not recommended for cascade) [default: false]
Examples:
# Delete user profile only
cortex users delete user-123
# GDPR cascade deletion (all user data)
cortex users delete user-123 --cascade
# Dry run to preview deletion
cortex users delete user-123 --cascade --dry-run
Cascade deletion permanently removes ALL user data:
- User profile
- Conversations and messages
- Memories (vector store)
- Facts
- Immutable records
- Mutable records
- Graph nodes (if configured)
Related:
cortex users delete-many
Delete multiple users with optional GDPR cascade.
Usage:
cortex users delete-many <userIds...> [options]
Options:
-d, --deployment <name>- Target deployment--cascade- Delete all user data across all layers [default: false]--dry-run- Preview what would be deleted [default: false]-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Delete multiple users
cortex users delete-many user-1 user-2 user-3
# Delete with cascade
cortex users delete-many user-1 user-2 --cascade
# Dry run
cortex users delete-many user-1 user-2 --cascade --dry-run
cortex users export
Export all user data (GDPR data portability).
Usage:
cortex users export <userId> [options]
Options:
-d, --deployment <name>- Target deployment-o, --output <file>- Output file path [default: "user-export.json"]
Examples:
# Export user data
cortex users export user-123
# Custom output file
cortex users export user-123 --output user-data.json
Related:
cortex users stats
Show statistics for a user.
Usage:
cortex users stats <userId> [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json
Examples:
# Show user statistics
cortex users stats user-123
# JSON output
cortex users stats user-123 --format json
cortex users update
Update user profile data.
Usage:
cortex users update <userId> [options]
Options:
-d, --deployment <name>- Target deployment--data <json>- JSON data to merge into profile-f, --file <path>- JSON file with data to merge
Examples:
# Update user data
cortex users update user-123 --data '{"name":"John","role":"admin"}'
# Update from file
cortex users update user-123 --file user-data.json
cortex users create
Create a new user profile.
Usage:
cortex users create <userId> [options]
Options:
-d, --deployment <name>- Target deployment--data <json>- JSON data for the profile [default: ""]
Examples:
# Create user
cortex users create user-123
# Create with data
cortex users create user-123 --data '{"name":"John","email":"john@example.com"}'
cortex users exists
Check if a user exists.
Usage:
cortex users exists <userId> [options]
Options:
-d, --deployment <name>- Target deployment
Examples:
# Check if user exists
cortex users exists user-123
Memory Space Commands
cortex spaces
Manage memory spaces.
cortex spaces list
List all memory spaces.
Usage:
cortex spaces list [options]
Options:
-d, --deployment <name>- Target deployment-t, --type <type>- Filter by type:personal,team,project,custom-s, --status <status>- Filter by status:active,archived-l, --limit <number>- Maximum number of results [default: 100]-f, --format <format>- Output format:table,json,csv
Examples:
# List all memory spaces
cortex spaces list
# Filter by type
cortex spaces list --type team
# Filter by status
cortex spaces list --status active
Related:
cortex spaces create
Create a new memory space.
Usage:
cortex spaces create <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-t, --type <type>- Space type:personal,team,project,custom(required)-n, --name <name>- Human-readable name-m, --metadata <json>- JSON metadata [default: ""]
Examples:
# Create team space
cortex spaces create team-alpha --type team --name "Team Alpha"
# Create with metadata
cortex spaces create project-1 --type project --metadata '{"owner":"user-123"}'
cortex spaces get
Get memory space details.
Usage:
cortex spaces get <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json
Examples:
# Get space details
cortex spaces get team-alpha
# JSON output
cortex spaces get team-alpha --format json
cortex spaces delete
Delete a memory space.
Usage:
cortex spaces delete <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment--cascade- Delete all data in the space (memories, facts, etc.) [default: false]-r, --reason <reason>- Reason for deletion (for audit trail)-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Delete space
cortex spaces delete team-alpha
# Delete with cascade (all data)
cortex spaces delete team-alpha --cascade --reason "Project completed"
Cascade deletion permanently removes:
- All memories
- All facts
- All conversations
- All contexts
cortex spaces archive
Archive a memory space (soft delete).
Usage:
cortex spaces archive <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-r, --reason <reason>- Reason for archiving-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Archive space
cortex spaces archive project-apollo --reason "Project completed"
cortex spaces reactivate
Reactivate an archived memory space.
Usage:
cortex spaces reactivate <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment
Examples:
# Reactivate space
cortex spaces reactivate project-apollo
cortex spaces stats
Get statistics for a memory space.
Usage:
cortex spaces stats <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json
Examples:
# Get statistics
cortex spaces stats team-alpha
# JSON output
cortex spaces stats team-alpha --format json
cortex spaces participants
List participants in a memory space.
Usage:
cortex spaces participants <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json
Examples:
# List participants
cortex spaces participants team-alpha
cortex spaces add-participant
Add a participant to a memory space.
Usage:
cortex spaces add-participant <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-i, --id <participantId>- Participant ID (required)-t, --type <type>- Participant type (e.g.,user,ai-tool,ai-agent) (required)
Examples:
# Add user participant
cortex spaces add-participant team-alpha --id user-123 --type user
# Add AI agent participant
cortex spaces add-participant team-alpha --id agent-1 --type ai-agent
cortex spaces remove-participant
Remove a participant from a memory space.
Usage:
cortex spaces remove-participant <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-i, --id <participantId>- Participant ID to remove (required)-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Remove participant
cortex spaces remove-participant team-alpha --id user-123
cortex spaces update
Update a memory space.
Usage:
cortex spaces update <spaceId> [options]
Options:
-d, --deployment <name>- Target deployment-n, --name <name>- New name-s, --status <status>- New status:active,archived-m, --metadata <json>- JSON metadata to merge
Examples:
# Update name
cortex spaces update team-alpha --name "Team Alpha v2"
# Update metadata
cortex spaces update team-alpha --metadata '{"updated":true}'
cortex spaces count
Count memory spaces.
Usage:
cortex spaces count [options]
Options:
-d, --deployment <name>- Target deployment-t, --type <type>- Filter by type-s, --status <status>- Filter by status
Examples:
# Count all spaces
cortex spaces count
# Count by type
cortex spaces count --type team
cortex spaces search
Search memory spaces by name.
Usage:
cortex spaces search <query> [options]
Options:
-d, --deployment <name>- Target deployment-t, --type <type>- Filter by type-s, --status <status>- Filter by status-l, --limit <number>- Maximum results [default: 20]-f, --format <format>- Output format:table,json
Examples:
# Search spaces
cortex spaces search "alpha"
# Search with filter
cortex spaces search "team" --type team
Facts Commands
cortex facts
Manage extracted facts.
cortex facts list
List facts in a memory space.
Usage:
cortex facts list [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-t, --type <type>- Filter by fact type-u, --user <id>- Filter by user ID-l, --limit <number>- Maximum number of results [default: 50]-f, --format <format>- Output format:table,json,csv
Examples:
# List facts
cortex facts list --space agent-1
# Filter by type
cortex facts list --space agent-1 --type preference
# Filter by user
cortex facts list --space agent-1 --user user-123
Related:
cortex facts search
Search facts by content.
Usage:
cortex facts search <query> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-t, --type <type>- Filter by fact type-l, --limit <number>- Maximum number of results [default: 20]-f, --format <format>- Output format:table,json
Examples:
# Search facts
cortex facts search "dark mode" --space agent-1
# Search by type
cortex facts search "preference" --space agent-1 --type preference
cortex facts get
Get fact details.
Usage:
cortex facts get <factId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-f, --format <format>- Output format:table,json
Examples:
# Get fact details
cortex facts get fact-123 --space agent-1
# JSON output
cortex facts get fact-123 --space agent-1 --format json
cortex facts delete
Delete a fact.
Usage:
cortex facts delete <factId> [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Delete fact
cortex facts delete fact-123 --space agent-1
cortex facts export
Export facts to a file.
Usage:
cortex facts export [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-t, --type <type>- Filter by fact type-o, --output <file>- Output file path [default: "facts-export.json"]-f, --format <format>- Export format:json,csv[default: "json"]
Examples:
# Export facts
cortex facts export --space agent-1 --output facts.json
# Export as CSV
cortex facts export --space agent-1 --format csv --output facts.csv
cortex facts count
Count facts in a memory space.
Usage:
cortex facts count [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-t, --type <type>- Filter by fact type
Examples:
# Count facts
cortex facts count --space agent-1
# Count by type
cortex facts count --space agent-1 --type preference
cortex facts clear
Clear all facts in a memory space.
Usage:
cortex facts clear [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-t, --type <type>- Only clear facts of this type-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Clear all facts
cortex facts clear --space agent-1
# Clear specific type
cortex facts clear --space agent-1 --type preference
This operation is permanent and cannot be undone.
Conversation Commands
cortex conversations (alias: convs)
Manage conversations.
cortex conversations list
List conversations.
Usage:
cortex conversations list [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Filter by memory space ID-u, --user <id>- Filter by user ID-t, --type <type>- Filter by type:user-agent,agent-agent-l, --limit <number>- Maximum number of results [default: 50]-f, --format <format>- Output format:table,json,csv
Examples:
# List conversations
cortex conversations list
# Filter by space
cortex conversations list --space agent-1
# Filter by user
cortex conversations list --user user-123
# Filter by type
cortex conversations list --type user-agent
Related:
cortex conversations get
Get conversation details with messages.
Usage:
cortex conversations get <conversationId> [options]
Options:
-d, --deployment <name>- Target deployment-m, --messages <number>- Number of messages to show [default: 20]-f, --format <format>- Output format:table,json
Examples:
# Get conversation
cortex conversations get conv-123
# Show more messages
cortex conversations get conv-123 --messages 50
# JSON output
cortex conversations get conv-123 --format json
cortex conversations delete
Delete a conversation.
Usage:
cortex conversations delete <conversationId> [options]
Options:
-d, --deployment <name>- Target deployment-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Delete conversation
cortex conversations delete conv-123
cortex conversations export
Export a conversation to a file.
Usage:
cortex conversations export <conversationId> [options]
Options:
-d, --deployment <name>- Target deployment-o, --output <file>- Output file path [default: "conversation-export.json"]-f, --format <format>- Export format:json,txt[default: "json"]
Examples:
# Export as JSON
cortex conversations export conv-123
# Export as text
cortex conversations export conv-123 --format txt --output conv.txt
cortex conversations count
Count conversations.
Usage:
cortex conversations count [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Filter by memory space ID-u, --user <id>- Filter by user ID-t, --type <type>- Filter by type
Examples:
# Count all conversations
cortex conversations count
# Count by space
cortex conversations count --space agent-1
# Count by user
cortex conversations count --user user-123
cortex conversations clear
Clear conversations.
Usage:
cortex conversations clear [options]
Options:
-d, --deployment <name>- Target deployment-s, --space <id>- Memory space ID (required)-u, --user <id>- Only clear for this user-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Clear all conversations in space
cortex conversations clear --space agent-1
# Clear for specific user
cortex conversations clear --space agent-1 --user user-123
This operation is permanent and cannot be undone.
cortex conversations messages
List messages in a conversation.
Usage:
cortex conversations messages <conversationId> [options]
Options:
-d, --deployment <name>- Target deployment-l, --limit <number>- Maximum number of messages [default: 50]-f, --format <format>- Output format:table,json
Examples:
# List messages
cortex conversations messages conv-123
# Show more messages
cortex conversations messages conv-123 --limit 100
Database Commands
cortex db stats
Show database statistics.
Usage:
cortex db stats [options]
Options:
-d, --deployment <name>- Target deployment-f, --format <format>- Output format:table,json
Examples:
# Show statistics
cortex db stats
# JSON output
cortex db stats --format json
Shows:
- Core entities (memory spaces, users, agents)
- Memory data (memories, facts, contexts)
- Conversations (conversations, messages)
- Shared stores (immutable, mutable)
- System tables (governance, graph sync)
- Deployment info (URL, mode)
cortex db clear
Clear entire database.
Usage:
cortex db clear [options]
Options:
-d, --deployment <name>- Target deployment-y, --yes- Skip confirmation prompt [default: false]
Examples:
# Clear database (with confirmation)
cortex db clear
# Skip confirmation
cortex db clear --yes
This permanently deletes:
- All memory spaces and memories
- All conversations and messages
- All facts and user profiles
- All graph nodes (if configured)
This operation cannot be undone.
cortex db backup
Backup database to a file.
Usage:
cortex db backup [options]
Options:
-d, --deployment <name>- Target deployment-o, --output <file>- Output file path [default: "cortex-backup.json"]--include-all- Include all data (may be large) [default: false]
Examples:
# Backup (spaces and users only)
cortex db backup
# Full backup (all data)
cortex db backup --include-all --output full-backup.json
What It Backs Up:
- Always: Memory spaces, users
- With
--include-all: Conversations, memories, facts
cortex db restore
Restore database from a backup file.
Usage:
cortex db restore [options]
Options:
-d, --deployment <name>- Target deployment-i, --input <file>- Backup file path (required)--dry-run- Preview what would be restored [default: false]-y, --yes- Skip confirmation [default: false]
Examples:
# Preview restore
cortex db restore --input backup.json --dry-run
# Restore backup
cortex db restore --input backup.json
Existing data may be overwritten.
cortex db export
Export all data to JSON.
Usage:
cortex db export [options]
Options:
-d, --deployment <name>- Target deployment-o, --output <file>- Output file path [default: "cortex-export.json"]
Examples:
# Export all data
cortex db export
# Custom output file
cortex db export --output data-export.json
Deployment Commands
cortex deploy
Deploy schema and functions to Convex.
Usage:
cortex deploy [options]
Options:
-d, --deployment <name>- Target deployment-l, --local- Deploy to local Convex instance [default: false]-p, --prod- Deploy to production [default: false]--push- Push without prompts [default: false]--skip-sync- Skip automatic schema sync from SDK [default: false]
Examples:
# Deploy to default deployment
cortex deploy
# Deploy to specific deployment
cortex deploy --deployment production
# Deploy to local
cortex deploy --local
# Deploy without prompts
cortex deploy --push
What It Does:
- Syncs schema files from SDK (unless
--skip-sync) - Runs
convex deployin the project directory - Deploys all Convex functions and schema
Related:
cortex update
Update @cortexmemory/sdk and convex packages across all enabled deployments and apps.
Usage:
cortex update [options]
Options:
-d, --deployment <name>- Target a specific deployment only-a, --app <name>- Target a specific app only--apps-only- Only update apps (skip deployments) [default: false]--deployments-only- Only update deployments (skip apps) [default: false]--dev- Use dev mode (link to local SDK via CORTEX_SDK_DEV_PATH) [default: false]--sync-template- Sync app template files (components, routes, etc.) [default: false]--sdk-version <version>- Specific Cortex SDK version to install--convex-version <version>- Specific Convex version to install--provider-version <version>- Specific vercel-ai-provider version to install-y, --yes- Auto-accept all updates [default: false]
Examples:
# Update all (shows status dashboard)
cortex update
# Update specific deployment
cortex update --deployment production
# Update specific app
cortex update --app quickstart
# Update with template sync
cortex update --app quickstart --sync-template
# Specific versions
cortex update --sdk-version 0.27.4 --convex-version 1.31.2
# Dev mode (link to local SDK)
export CORTEX_SDK_DEV_PATH=/path/to/Project-Cortex
cortex update --dev --app quickstart
What It Does:
- Checks current and latest versions
- Shows status dashboard for all deployments and apps
- Prompts for confirmation (unless
--yes) - Updates packages for selected targets
- Optionally syncs template files for apps
Related:
Convex Commands
cortex convex
Manage Convex deployments. The convex command has multiple subcommands:
cortex convex status
Check Convex deployment status.
Usage:
cortex convex status [options]
Options:
-d, --deployment <name>- Target deployment
Examples:
# Check status
cortex convex status
# Specific deployment
cortex convex status --deployment production
cortex convex dev
Start Convex in development mode.
Usage:
cortex convex dev [options]
Options:
-d, --deployment <name>- Target deployment-l, --local- Use local Convex instance [default: false]--once- Run once and exit [default: false]--skip-sync- Skip automatic schema sync from SDK [default: false]
Examples:
# Start dev server
cortex convex dev
# Local mode
cortex convex dev --local
# Run once (for CI)
cortex convex dev --once
cortex convex logs
View Convex deployment logs.
Usage:
cortex convex logs [options]
Options:
-d, --deployment <name>- Target deployment-l, --local- View local logs [default: false]-p, --prod- View production logs [default: false]-t, --tail- Tail logs continuously [default: false]-n, --lines <number>- Number of lines to show [default: 50]
Examples:
# View logs
cortex convex logs
# Tail logs
cortex convex logs --tail
# View production logs
cortex convex logs --prod
cortex convex dashboard
Open Convex dashboard in browser.
Usage:
cortex convex dashboard [options]
Options:
-d, --deployment <name>- Target deployment-l, --local- Open local dashboard [default: false]-p, --prod- Open production dashboard [default: false]
Examples:
# Open dashboard
cortex convex dashboard
# Open local dashboard
cortex convex dashboard --local
cortex convex schema
View schema information.
Usage:
cortex convex schema
Examples:
# View schema tables
cortex convex schema
Shows:
- All Cortex SDK tables
- Table descriptions
- Layer organization
cortex convex init
Initialize Convex in current project.
Usage:
cortex convex init [options]
Options:
-d, --deployment <name>- Target deployment--skip-sync- Skip automatic schema sync from SDK [default: false]
Examples:
# Initialize Convex
cortex convex init
cortex convex env
Manage environment variables.
Usage:
cortex convex env [options]
Options:
-d, --deployment <name>- Target deployment-l, --list- List environment variables-s, --set <key=value>- Set environment variable-p, --prod- Use production environment [default: false]
Examples:
# List env vars
cortex convex env --list
# Set env var
cortex convex env --set OPENAI_API_KEY=sk-...
# Production env
cortex convex env --list --prod
Configuration
The CLI uses a hierarchical configuration system.
Configuration Priority (highest first)
- CLI flags:
--url,--key,--deployment - Environment variables:
CONVEX_URL,CONVEX_DEPLOY_KEY - Project config:
./cortex.config.json - User config:
~/.cortexrc
User Config File
Location: ~/.cortexrc
Format: JSON
{
"deployments": {
"local": {
"url": "http://127.0.0.1:3210",
"deployment": "anonymous:anonymous-cortex-sdk-local",
"projectPath": "/Users/me/projects/my-cortex-app",
"enabled": true
},
"staging": {
"url": "https://staging.convex.cloud",
"key": "staging|...",
"projectPath": "/Users/me/projects/my-cortex-app",
"enabled": false
},
"production": {
"url": "https://prod.convex.cloud",
"key": "prod|...",
"projectPath": "/Users/me/projects/my-cortex-app",
"enabled": false
}
},
"apps": {
"quickstart": {
"type": "nextjs",
"projectPath": "/Users/me/projects/my-cortex-app",
"path": "quickstart",
"port": 3000,
"startCommand": "npm run dev",
"enabled": true
}
},
"default": "local",
"format": "table",
"confirmDangerous": true
}
Fields:
| Field | Type | Description |
|---|---|---|
deployments | object | Named deployment configurations |
deployments[name].url | string | Convex deployment URL |
deployments[name].key | string | Convex deploy key (optional for local) |
deployments[name].deployment | string | Convex deployment name (optional) |
deployments[name].projectPath | string | Path to project directory |
deployments[name].enabled | boolean | Auto-start with cortex start |
apps | object | Named app configurations |
apps[name].type | string | App type (e.g., "nextjs") |
apps[name].projectPath | string | Path to project root |
apps[name].path | string | Relative path to app |
apps[name].port | number | Port number |
apps[name].startCommand | string | Command to start app |
apps[name].enabled | boolean | Auto-start with cortex start |
default | string | Default deployment name |
format | string | Default output format |
confirmDangerous | boolean | Require confirmation for dangerous operations |
Environment Variables
The CLI recognizes these environment variables:
| Variable | Description |
|---|---|
CONVEX_URL | Convex deployment URL |
CONVEX_DEPLOY_KEY | Convex deploy key |
CONVEX_DEPLOYMENT | Convex deployment name |
LOCAL_CONVEX_URL | Local Convex URL |
CLOUD_CONVEX_URL | Cloud Convex URL |
CLOUD_CONVEX_DEPLOY_KEY | Cloud deploy key |
NEO4J_URI | Neo4j connection URI |
NEO4J_USERNAME | Neo4j username |
NEO4J_PASSWORD | Neo4j password |
MEMGRAPH_URI | Memgraph connection URI |
MEMGRAPH_USERNAME | Memgraph username |
MEMGRAPH_PASSWORD | Memgraph password |
CORTEX_GRAPH_SYNC | Enable graph sync ("true"/"false") |
OPENAI_API_KEY | OpenAI API key |
CORTEX_SDK_DEV_PATH | Path to local SDK for dev mode |
DEBUG | Enable debug output |
Configuration Commands
See cortex config for managing configuration.
GDPR Compliance
The CLI provides GDPR-compliant data management features.
Cascade Deletion
When deleting users with the --cascade flag, ALL user data is permanently removed:
$ cortex users delete user-123 --cascadeWhat Gets Deleted:
- User profile (all versions)
- Conversations (all messages)
- Memories (vector store)
- Facts
- Immutable records
- Mutable records
- Graph nodes (if configured)
Verification:
Use --verify (enabled by default) to check deletion completeness:
$ cortex users delete user-123 --cascade --verifyDry Run:
Preview what would be deleted without actually deleting:
$ cortex users delete user-123 --cascade --dry-runData Portability
Export all user data in machine-readable format:
$ cortex users export user-123 --output user-data.jsonRelated:
Safety Features
The CLI includes multiple safety features for dangerous operations:
Confirmation Prompts
Dangerous operations require explicit confirmation:
$ cortex db clearThis prompts: "Clear ALL data from local?"
Bypass with --yes flag (use carefully):
$ cortex db clear --yesDry Run Mode
Preview what would happen without executing:
Preview user deletion:
$ cortex users delete user-123 --cascade --dry-runPreview database restore:
$ cortex db restore --input backup.json --dry-runExact Confirmation
For cascade deletions, you must type the exact ID:
$ cortex users delete user-123 --cascadeThis prompts: Type "user-123" to confirm cascade deletion.
Verification
Automatic verification after cascade deletions:
$ cortex users delete user-123 --cascade --verifyThis verifies all user data was deleted and reports any potential issues.
Troubleshooting
Common Issues
Command Not Found
cortex: command not found
Solution:
Install via Homebrew (Recommended):
$ brew install cortex-memory/tap/cliOr install globally via npm:
$ npm install -g @cortexmemory/cliOr use npx:
$ npx @cortexmemory/cli <command>No Deployments Configured
No deployments configured
Solution:
Initialize a new project:
$ cortex initOr add existing deployment:
$ cortex config add-deploymentConnection Failed
Connection failed: ECONNREFUSED
Solutions:
- Check if Convex is running:
cortex status - Start Convex:
cortex start - Verify URL:
cortex config show - Test connection:
cortex config test
PID File Stale
Convex was already stopped
Cause: Process stopped without cleaning up PID file.
Solution:
Clean up PID files:
$ rm .convex-dev.pid .quickstart-app.pidOr use dev mode and press 'k' to kill processes by port:
$ cortex devSchema Sync Failed
Schema sync failed: SDK not found
Solutions:
Install SDK:
$ npm install @cortexmemory/sdkOr skip schema sync:
$ cortex deploy --skip-syncGraph Database Not Starting
Graph database configured but Docker not available
Solutions:
- Start Docker Desktop
- Check Docker:
docker ps - Start manually:
docker-compose -f docker-compose.graph.yml up -d
Debug Mode
Enable debug output for troubleshooting:
Via flag:
$ cortex <command> --debugVia environment variable:
$ DEBUG=1 cortex <command>Debug Output Includes:
- Environment variable loading
- Configuration resolution
- API request/response details
- Process spawning details
- File operations
Getting Help
General help:
$ cortex --helpCommand help:
$ cortex <command> --helpSubcommand help:
$ cortex <command> <subcommand> --helpReal-World Workflows
Workflow 1: New Project Setup
Create new project with local Convex
$ cortex init my-app --localNavigate to project
$ cd my-appStart development services
$ cortex startCheck status
$ cortex statusView database statistics
$ cortex db statsWorkflow 2: Multi-Environment Setup
Add deployments
$ cortex config add-deployment local --url http://127.0.0.1:3210$ cortex config add-deployment staging --url https://staging.convex.cloud --key "staging|..."$ cortex config add-deployment production --url https://prod.convex.cloud --key "prod|..."Set project paths
$ cortex config set-path local /path/to/project$ cortex config set-path staging /path/to/project$ cortex config set-path production /path/to/projectEnable only local for auto-start
$ cortex config enable local$ cortex config disable staging$ cortex config disable productionDeploy to production
$ cortex deploy --deployment productionView all deployments
$ cortex config listWorkflow 3: GDPR Data Export & Deletion
Search for user
$ cortex users list | grep john@example.comView user data
$ cortex users stats user-123Export user data (GDPR portability)
$ cortex users export user-123 --output user-123-export.jsonPreview deletion
$ cortex users delete user-123 --cascade --dry-runDelete user data (GDPR right to erasure)
$ cortex users delete user-123 --cascade --verifyWorkflow 4: Interactive Development
Start interactive dev mode
$ cortex devKeyboard shortcuts:
c- clear screens- show statusr- restart servicesg- toggle graph databasek- kill stuck processesq- quit
Watch logs in real-time
Logs are automatically displayed in the terminal.
Make code changes
Convex auto-reloads when you save files.
Toggle graph database
Press g key.
Quit gracefully
Press q key.
Workflow 5: Database Backup & Restore
Backup database
$ cortex db backup --include-all --output backup-2026-01-01.jsonVerify backup
$ ls -lh backup-2026-01-01.jsonClear database for testing
$ cortex db clear --deployment localRestore from backup
$ cortex db restore --input backup-2026-01-01.json --deployment localWorkflow 6: Package Updates
Check current versions
$ cortex updateUpdate specific deployment
$ cortex update --deployment productionUpdate all with specific version
$ cortex update --sdk-version 0.27.4 --yesUpdate app with template sync
$ cortex update --app quickstart --sync-templateDev mode (link to local SDK)
$ export CORTEX_SDK_DEV_PATH=/path/to/Project-Cortex$ cortex update --dev --app quickstartExamples
Example 1: Search and Clear Memories
Search for sensitive data:
$ cortex memory search "password" --space agent-1Review results and delete specific memory:
$ cortex memory delete mem-456 --space agent-1Or clear all for a user:
$ cortex memory clear --space agent-1 --user user-123Example 2: Manage Memory Spaces
Create team space:
$ cortex spaces create team-alpha --type team --name "Team Alpha"Add participants:
$ cortex spaces add-participant team-alpha --id user-123 --type user$ cortex spaces add-participant team-alpha --id agent-1 --type ai-agentView statistics:
$ cortex spaces stats team-alphaList participants:
$ cortex spaces participants team-alphaArchive when done:
$ cortex spaces archive team-alpha --reason "Project completed"Example 3: Export Conversations
List conversations:
$ cortex conversations list --space agent-1 --user user-123Get specific conversation:
$ cortex conversations get conv-789Export to file:
$ cortex conversations export conv-789 --format txt --output conv.txtExample 4: Database Statistics
View overall stats:
$ cortex db statsView space-specific stats:
$ cortex spaces stats agent-1$ cortex memory stats --space agent-1View user-specific stats:
$ cortex users stats user-123Export to JSON for analysis:
$ cortex db stats --format json > db-stats.jsonVersion History
v0.27.4 (Current)
- Interactive dev mode with keyboard shortcuts
- Multi-deployment support for
cortex start - Template app management
- Automatic schema sync from SDK
- Graph database integration
- GDPR cascade deletion with verification
- Improved status dashboard
- Package update management across deployments and apps
Related
Additional Resources
Documentation
- Getting Started: Installation
- Getting Started: Five Minute Quickstart
- Getting Started: Configuration
Core Features
API Reference
Repository
Next Steps
License
Cortex CLI is licensed under the FSL-1.1-Apache-2.0 license.
See LICENSE.md for details.