Cortex CLI

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

Documentation · Getting started · CLI reference · cortex.foundation

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

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

Windows

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

cargo build -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 → typing → working) headlessly through generate_tui_demo and rasterises the frames into docs/media/intro.gif.

Release and CI secrets

Merges to main run .github/workflows/version-bump.yml, which patch-bumps the version and tags it. Tags run release.yml, which can publish to 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.

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.