Cortex CLI

Cortex Code — a coding agent that runs in your terminal.

Documentation · Getting started · CLI reference · cortex.foundation

Generated macOS desktop demo, not a screen recording. The TUI frames come from the offline readme_hero lock boards; the forest wallpaper, Terminal chrome and pointer are composited. No live coding request is performed. Regenerate with ./scripts/render-demo-gif.sh (Cargo, Python with Pillow, and FFmpeg required); terminal pixels are preserved 1:1 before GIF quantization.

What is Cortex CLI

Cortex CLI — also called Cortex Code — is a coding agent you run from a terminal in your project. Describe the change you want and it works through it: searching the codebase, reading the files that matter, editing them, running your build and tests, and reporting what it did. Every step shows up in the timeline as it happens, and you decide how much it can do without asking.

One binary gives you:

• An interactive TUI with a live timeline, tool approvals, plan and build modes, session history, rewind and fork.
• Headless one-shot runs for scripts and CI, with autonomy levels, structured JSON output, and turn and time limits.
• The tools a coding agent needs — search, read, edit, patch, shell execution, language-server queries and web fetch — under an approval policy and a sandbox you control.
• Extension points: MCP servers, skills, custom agents and subagents, shell hooks and WebAssembly plugins.

Cortex CLI talks to the Cortex API at api.cortex.foundation and signs in there with device login (POST /v1/auth/device). Credentials are stored in your OS keyring.

Install

Linux and macOS

The installer downloads the matching archive from software.cortex.foundation, verifies its SHA-256, and installs to ~/.local/bin. Review it first if you prefer:

curl -fsSL https://software.cortex.foundation/install.sh | less
curl -fsSL https://software.cortex.foundation/install.sh | sh

Update an existing install with cortex upgrade. Pin a version with CORTEX_VERSION=0.1.4 when running the installer.

Windows

Windows installs into %LOCALAPPDATA%\Cortex\bin after the same checksum check:

irm https://software.cortex.foundation/install.ps1 | iex

From source

Requires the toolchain pinned in rust-toolchain.toml.

cargo build -p cortex-cli --release
# binary: target/release/Cortex

On Linux, the optional audio and desktop crates need ALSA headers: sudo apt-get install -y libasound2-dev pkg-config.

Full instructions, including Homebrew and WinGet, are in Getting started.

Quick start

cd ~/code/my-project
cortex

That opens the session view from the recording above. Type what you want changed and press Enter:

> add a /healthz endpoint and cover it with a test

Press Esc to interrupt a turn, Shift+Tab to change how much autonomy the agent has, and ? for help.

Prefer one-shot? Both of these work without a terminal:

cortex run "explain the release process"
cortex exec --auto read-only --git-diff "review my uncommitted changes"

Login

cortex login

This opens the Cortex sign-in flow in your browser and stores the session in your OS keyring. For machines without a browser:

cortex login --device-auth      # device-code flow
cortex login --sso              # enterprise SSO
cortex login --with-api-key     # read an API key from stdin

Check it worked with cortex whoami. See Signing in for the full picture.

Documentation

Getting started	Install, sign in, first session
The TUI	Timeline, composer, modes, approvals
Sessions	Resume, export, import, share
Headless / exec mode	Scripts and CI
Plan and Spec modes	Approve a plan before anything changes
Configuration	Files, keys, profiles, permissions
Agents · Skills · MCP · Hooks · Plugins	Extending Cortex
CLI reference · Tools · Slash commands · Keyboard	Reference
Troubleshooting	When something does not work

The index is at docs/README.md.

Building and testing

For native prerequisites, pinned tools, a development container, real local QA, test reports, and coverage, follow Development and local QA.

cargo build --locked -p cortex-cli
./target/debug/Cortex --help

The gates CI enforces:

cargo fmt --all -- --check
./scripts/clippy.sh
cargo test --workspace
cargo audit
./scripts/check-cli-version.sh

Headless TUI and snapshot tests, required whenever a TUI surface changes:

cargo test -p cortex-tui -p cortex-tui-capture -p cortex-tui-components \
  -p cortex-tui-framework -p cortex-tui-core -p cortex-tui-buffer \
  -p cortex-tui-widgets -p cortex-tui-layout -p cortex-tui-text \
  -p cortex-tui-input -p cortex-tui-terminal -p cortex-tui-syntax

The banner above is generated from this repository, not captured by hand:

./scripts/render-demo-gif.sh

That records the signed lock TUI (splash → type a prompt → working → slash palette → /model → Shell → composer) headlessly through generate_tui_demo and composites it onto the forest desktop in docs/media/intro.gif.

Release and CI secrets

Version bumps merge to main in a normal PR (chore: bump version to …). That merge runs .github/workflows/version-bump.yml, which tags v*.*.*. Tags run release.yml, which builds GitHub Release assets and automatically publishes them to Cloudflare R2 / software.cortex.foundation via publish-r2.yml.

This repository does not invent cloud accounts. The secret names CI expects are listed in docs/CI_SECRETS.md. Values never go in git. Linux CI can additionally run on AWS CodeBuild via GitHub OIDC; the one-time IAM steps are in deploy/aws/codebuild/README.md.

Contributing

Start with docs/CONTRIBUTING.md, then AGENTS.md and .rules/. Every PR fills the attestation list in .github/PULL_REQUEST_TEMPLATE.md.

Licence

Apache-2.0.