Cortex CLI
Install the CLI with npm install -g @canopy/cortex-cli. Run cortex --help for the installed version’s command list. The published CLI is separate from the Host canopy CLI.
Authenticate and select a project
Section titled “Authenticate and select a project”cortex logincortex whoamicortex projects listcortex projects use <project-id>cortex init writes a .cortex.json file for the current directory. Keep API keys out of that file when it is committed; authenticate with the CLI’s login flow or environment-specific secret storage.
Ingest and ask
Section titled “Ingest and ask”Create or select a knowledge base in the Cortex dashboard, then ingest files and wait for processing:
cortex ingest ./handbook --kb <knowledge-space-id> --waitcortex ask "What is the escalation process?" --kb <knowledge-space-id>cortex ingest accepts .pdf, .txt, .md and .markdown files. It
creates each upload job for the selected knowledge space; PDFs use the PDF
upload route and text/Markdown files use the general document upload route.
HTML and DOCX are accepted by the Cortex API’s general upload endpoint but are
not currently accepted by this CLI command. Direct API callers can use the
authenticated upload flow in the Cortex developer guide.
Use --assistant <assistant-id> with cortex ask when the request should use an assistant. Add --json for machine-readable output. Ingestion can take time; inspect the returned job or rerun with --wait to wait for completion.
Other supported workflows
Section titled “Other supported workflows”The CLI also provides kb create, assistants create, canned responses, evaluation-set upload/run/show, evaluation suites, usage reports, residency attestations, organization webhooks, tenants, experimental agent-run/runtime-state inspection, and setup/mcp status. Evaluation suites, agent runs and runtime state are feature-gated; check /platform-features/resolved before relying on them. The freshdesk integrations commands are present in the CLI, but Freshdesk is marked planned, internal and staff-restricted in the current feature manifest. Training and sync-source commands are also registered but are planned/internal; they are not general customer capabilities. Command registration does not grant access or indicate general availability. cortex --help prints the top-level summary; group-specific help is not implemented in the current CLI, so consult this guide and the linked command references for arguments.
Staff-only or staff-restricted commands include cortex admin, cortex projects inference-policy, and the current Freshdesk integration routes; some use a Canopy staff login rather than a Cortex API key. The CLI checks server authorization, so a command being present does not grant access.
MCP setup
Section titled “MCP setup”cortex setupcortex mcpsetup signs in and configures MCP endpoints only when a real endpoint is
provided. There is no default remote Cortex MCP deployment today, so a plain
cortex setup skips Cortex MCP registration. For a self-hosted or staging
server, pass --mcp-url <base-url> or set CORTEX_MCP_URL; setup appends
/mcp when needed and writes .mcp.json in the current directory. Pass
--output-dir <path> to write it elsewhere. cortex mcp reports the
configured endpoint and registration status. The server still enforces
the caller’s Cortex authorization and feature availability.
See Cortex MCP tools for connection details and the registered tool reference.