commands.md

Commands

Part of the Cortex Local Agent documentation.

PowerShell

Run commands from C:\Projects\Cortex unless a command says otherwise. All repository PowerShell scripts live under scripts\; this section documents the purpose of each one.

| Script | Run directly? | Purpose | | --- | --- | | .\scripts\setup-secrets.ps1 -OpenAiKey "<key>" | Yes, during first-time setup or credential rotation. | Generates or reuses local service secrets, stores OPENAI_API_KEY, Postgres, Neo4j, and Mem0 values at User environment scope, and writes the gitignored Docker Compose environment file at local-agent\docker\mem0\.env. Use -Force to regenerate existing generated passwords. | | .\scripts\setup-local-agent.ps1 | Yes, or via run.ps1 when setup/build work is needed. | Verifies local prerequisites, warns about occupied service ports, validates the workspace config path, runs root npm install, and builds the root TypeScript workspaces. Use -WorkspaceConfig <path> to validate a non-default workspace registry. | | .\scripts\run.ps1 | Yes. This is the normal interactive launcher. | Coordinates install/build checks, ensures pnpm, installs Matbot dependencies when missing, starts local services through start-local-agent.ps1, waits for health checks, starts or restarts Matbot WebUI, and opens the browser. | | .\scripts\start-local-agent.ps1 | Usually through run.ps1; direct use is useful for advanced startup. | Starts the Docker Mem0/Postgres/Neo4j stack when Docker is available, waits for Postgres before Matbot starts, probes NVIDIA/CUDA support and starts workspace-rag-cuda when possible, starts file-index on port 8877, starts file-broker on port 8878, and optionally starts Matbot from -MatbotCommand or MATBOT_COMMAND. | | .\scripts\health-check.ps1 | Yes, after startup or during troubleshooting. | Checks file-index, file-broker, Mem0 Swagger docs, Postgres TCP readiness, and workspace-rag-cuda when CORTEX_RAG_CUDA_EMBEDDING_URL is set. It prints warnings for unavailable services instead of stopping at the first failure. | | .\scripts\stop-local-agent.ps1 | Yes. | Stops local listener processes on ports 8877, 8878, and 19778, then runs docker compose down for the Mem0 stack when Docker is installed. It is intended for the interactive launcher path, not for uninstalling the Windows service. | | .\scripts\install-cortex-service.ps1 -Start | Yes, from an elevated PowerShell session. | Installs the WinSW-backed CortexLocalAgent Windows service, downloads or copies the WinSW wrapper, writes the service XML in local-agent\service, configures service logs under local-agent\logs\service, and optionally starts the service. | | .\scripts\run-service.ps1 | No, except for debugging the service foreground runner. | Starts the same local dependencies as the interactive path, but keeps Matbot running in the foreground so WinSW can supervise it. The service wrapper generated by install-cortex-service.ps1 calls this script. | | .\scripts\uninstall-cortex-service.ps1 | Yes, from an elevated PowerShell session. | Stops and removes the WinSW-backed Windows service. Use -RemoveWrapperFiles to delete the generated wrapper executable and XML after uninstalling. |

Interactive startup path:

run.ps1 -> start-local-agent.ps1 -> file-index, file-broker, Docker Mem0/Postgres/Neo4j, optional Matbot WebUI child process

Windows service startup path:

install-cortex-service.ps1 -> WinSW service -> run-service.ps1 -> file-index, file-broker, Docker Mem0, Matbot foreground process

Useful run.ps1 switches:

Switch	Effect
-ForceInstall	Force dependency checks and installation.
-SkipInstall	Do not install dependencies. Requires dependencies to already exist.
-SkipBuild	Do not run builds.
-SkipDocker	Do not start the Mem0/Postgres/Neo4j Docker stack.
-SkipCudaIngestion	Do not start or use the optional CUDA embedding service for workspace RAG.
-SkipHealth	Do not run health checks.
-NoBrowser	Start services but do not open a browser. Use this for unattended/local-service operation.
-NoStart	Check install/build state without starting services.
-NoRestartMatbot	Reuse an already-running WebUI process instead of restarting it.
-WebPort 19779	Start the WebUI on a different port.
-HealthTimeoutSec 180	Wait longer for services to become healthy.

run.ps1 restarts the WebUI process by default so changes to plugins, configuration, providers, and UI assets are picked up. Use -NoRestartMatbot only when you deliberately want to keep the existing WebUI process.

Useful start-local-agent.ps1 switches:

Switch	Effect
-SkipDocker	Do not start the Mem0/Postgres/Neo4j Docker stack.
-SkipBuild	Do not run npm run build before startup. run.ps1 passes this after doing its own build check.
-SkipCudaIngestion	Disable launch-time CUDA probing and CUDA embedding startup.
-NoRestartMatbot	Keep an existing Matbot WebUI listener on MATBOT_WEB_PORT instead of stopping it.
-MatbotCommand "<command>"	Command used to start Matbot. Defaults to MATBOT_COMMAND when set.

Useful Windows service switches:

Command	Effect
.\scripts\install-cortex-service.ps1 -Start	Install and immediately start the default CortexLocalAgent service.
.\scripts\install-cortex-service.ps1 -Force	Replace an existing service with the same name.
.\scripts\install-cortex-service.ps1 -SkipDocker	Install a service runner that leaves Mem0/Postgres/Neo4j Docker startup to something else.
.\scripts\install-cortex-service.ps1 -WebPort 19779	Configure the service-hosted WebUI to use a different port.
.\scripts\install-cortex-service.ps1 -WinSWExe <path>	Use an existing WinSW executable instead of downloading one.
.\scripts\run-service.ps1 -SkipDocker	Debug the service runner without starting Docker.
.\scripts\run-service.ps1 -SkipCudaIngestion	Debug or run the service runner with CUDA ingestion disabled.
.\scripts\uninstall-cortex-service.ps1 -RemoveWrapperFiles	Remove the service and delete generated WinSW wrapper files.

npm

Command	Purpose
npm run build	Build all npm workspaces declared in the root package.json.
npm test	Run the Node test suite in tests\*.test.mjs.
npm run test:webui	Run Playwright WebUI tests.
npm run test:all	Run Node tests and Playwright tests.
npm run eval:cortex -- <suite-id> [--candidate <version>] [--provider <provider>] [--url <base-url>] [--junit <path>]	Run a persisted regression suite through the Cortex tool endpoint, print the gate result, optionally write JUnit XML, and return a failing process status when the gate fails.
npm run verify:openai	Verify the current OpenAI API key with the configured test script.

The Workspace RAG V2 PostgreSQL tests are opt-in because they need a live database. They create and drop their own workspace_rag_v2_*_<pid> schemas and never touch the configured schema. They cover atomic publication, RLS, and interrupted-scan recovery (resumption, checkpoint publication, and pruning):

$env:CORTEX_RAG_V2_POSTGRES_INTEGRATION = "1"; node --test tests\workspace-rag-v2-postgres.integration.test.mjs

First Playwright setup on a machine:

npx playwright install chromium