Skip to content

README.md

Latest commit

 

History

History
85 lines (69 loc) · 4.78 KB

README.md

File metadata and controls

85 lines (69 loc) · 4.78 KB
Raw

Cortex CLI documentation

Cortex CLI (also called Cortex Code) is a coding agent that runs in your terminal. It ships one binary, Cortex, that gives you an interactive TUI, a headless one-shot mode for scripts and CI, and the surrounding machinery — tools, MCP servers, skills, agents, plugins, hooks, sessions and permissions.

New here? Start with Getting started, then keep CLI reference open in another tab.

Cortex CLI in macOS Terminal on a green forest desktop, touring slash commands and a live tool row

Contents

Guides

Page What it covers
Getting started Install, sign in, and run your first session
The TUI The interactive UI: timeline, composer, modes, approvals
Sessions Resume, list, export, import, share, protect
Headless / exec mode Non-interactive runs for scripts and CI
Plan and Spec modes Get a plan approved before anything is written
Long-horizon persisted goals /goal session-backed objectives
Editor integration What running Cortex inside an editor terminal does and does not provide
Development and local QA Reproducible setup, real local tests, coverage and test reports
Source quality Dependency, complexity, duplication, feature-flag and contract gates

Configuration

Page What it covers
Configuration files Discovery order, config.toml keys, profiles
Environment variables Every variable the CLI reads, by name
Data locations Where config, sessions, logs and caches live

Customization

Page What it covers
Agents Built-in agents, custom agent files, subagents
MCP servers Connect Model Context Protocol servers
Skills Reusable instruction bundles the agent can load
Hooks Run your own commands on agent lifecycle events
Plugins WebAssembly plugins, their manifest and lifecycle
Themes Built-in themes and how to switch them

Reference

Page What it covers
CLI reference Every command and flag
Tools The tools the agent can call
Slash commands Everything you can type after / in the TUI
Keyboard shortcuts Key bindings by context
Signing in Browser, device-code, SSO and token sign-in; the keyring
Local app-server API Authentication, supported OpenAPI contract and local readiness
Privacy Local diagnostic allowlist, consent, retention and data boundaries
Local client SDK Typed TypeScript client for an installed cortex exec subprocess

Operations

Page What it covers
Troubleshooting Common failures and how to diagnose them
Contributing Filing issues, PR conventions, required checks
CI secrets Secret names the release workflows expect
CodeBuild CI OIDC + AWS CodeBuild Linux x64/arm64 status checks
Local operations Alerts, error investigation, deployment comparison and profiling
Maintenance Ownership, labels, backlog triage and release review
Readiness remediation Local validation snapshot and explicit remaining limits
CLI 100 % audit (2026-09-08) TUI + MCP audit against the product and Designer locks: gaps with evidence, verifier MCP spec, ordered fix PRs

Conventions used here

  • Commands are written as cortex …. The installed binary is Cortex; on case-insensitive filesystems and via the install script both spellings work. A local debug build is ./target/debug/Cortex.
  • Anything documented here is backed by the code in this repository. If a flag is missing from a page, check cortex <command> --help, which is generated from the same definitions.
  • Cortex CLI talks to the Cortex API at api.cortex.foundation and signs in there (POST /v1/auth/device). Releases are published to software.cortex.foundation.