Skip to main content
The Cortex CLI is Cortex Code in the terminal. One binary gives you an interactive full-screen session view with a live timeline and approval prompts, one-shot runs from your own shell, and a headless mode for scripts. It uses the same Cortex account and the same Code sessions as the web and desktop apps, so a change you start in the terminal is the same piece of work you can pick up in a browser. One thing to know before anything else: the CLI does not run a model on your machine. Every turn goes to the Cortex coding service. When that service cannot be reached, the CLI says so and stops with a non-zero exit status; it never quietly substitutes something local. This page is the map of the CLI documentation. If you have never used it, follow the three Get started pages in order.

​
Three ways to run it

​
Install in one line

Then sign in and open a session in a project:

​
Get started

Install the CLI

The installers for macOS, Linux and Windows, what the checksum check proves, pinning a version, cortex upgrade, uninstalling.

Sign in

cortex login in a browser, a device code for machines without one, single sign-on, API keys for unattended runs.

CLI quickstart

Install, sign in, a first turn in a project, AGENTS.md, and how much autonomy to grant on day one.

​
Use the CLI

The TUI

Everything on screen: the timeline, the composer and its chips, the footer hints, queueing a follow-up, the panels.

Modes and permissions

Agent, Plan, Ask and Bash, the approval prompt, the sandbox, and the permission table.

Plan and Spec modes

Get a plan before anything changes, accept or keep iterating, and the stricter Spec lock.

Sessions

Sessions are files: list, resume, rewind, fork, export, import, share, lock and clean up.

Goals

A long-horizon objective that survives compaction and resume, with a turn budget and evidence.

Slash commands

Everything after / in the composer, grouped by purpose, plus your own custom commands.

Keyboard shortcuts

Every binding, grouped by where it applies, and the in-app shortcuts overlay.

Tools the agent uses

Search, read, edit, shell and the rest, how each one appears in the timeline, and which ones ask first.

Cloud, This PC, and SSH

Where a session actually runs, how to opt in to the other hosts, and why they fail closed.

Editor integration

Driving the CLI from an editor over the agent protocol, and what is not wired yet.

​
Automate

Headless and one-shot runs

cortex run and cortex exec: autonomy levels, output formats, turn and time limits, exit codes.

CI cookbook

Recipes for pipelines: the key in the environment, parsing the result document, reviewing uncommitted changes.

​
Configure

Configuration

config.toml keys, profiles, and the five layers that decide which value wins.

Environment variables

Every CORTEX_* variable the CLI reads and what each one overrides.

Data locations

Where sessions, configuration, cache and credentials live on each operating system.

Permission policy

Allow and deny rules for tools and commands, and the managed policy an organization can set.

​
Extend

MCP servers

Add a server, the supported transports, authentication, tool naming, and the connection panel.

Skills

Skill files, where the CLI looks for them, how the agent picks one, and writing your own.

Agents and subagents

Custom agents, their tool access, and when the CLI delegates part of a turn.

Hooks

The hooks block in a plugin manifest, which events actually fire, and why a hook can refuse but never approve.

Plugins

Installing and enabling plugins, the sandbox they run in, and the development workflow.

Themes

The built-in themes, switching them, and the related display settings.

​
Reference

Command reference

Every cortex subcommand and flag, one table per command group.

CLI troubleshooting

The diagnostic commands first, then the messages you might see and what to do about each.

​
How it fits with the other products

Cortex Code is the same product in a browser and on the desktop. The terminal is another front end onto it, not a separate service.

​
Conventions on these pages

  • Commands are written as cortex .... The installed binary file is named Cortex, and the command you type is cortex.
  • The generated help is always authoritative: cortex --help and cortex <command> --help come from the same definitions as the shipped commands. If this documentation and the help output ever disagree, believe the help.
  • The CLI talks to the Cortex API over HTTPS at api.cortex.foundation. Releases are published to software.cortex.foundation.
  • Source and issues: github.com/CortexLM/cli, licensed Apache-2.0.
Version numbers move between releases, so no page here pins one. Run cortex --version to see what you have, and cortex upgrade --check to see what is published on your channel.