> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Cortex CLI

> Cortex Code in the terminal: an interactive session view, one-shot runs, headless runs for scripts, and every page of the CLI documentation

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

| Surface                  | Command             | Use it for                                                                                |
| ------------------------ | ------------------- | ----------------------------------------------------------------------------------------- |
| Interactive session view | `cortex`            | Everyday work: a timeline, approvals, Agent, Plan and Ask modes, sessions you can resume  |
| One-shot                 | `cortex run "..."`  | A single request from your shell, streamed, with session continuation                     |
| Headless                 | `cortex exec "..."` | Scripts and pipelines: an autonomy ceiling, machine-readable output, turn and time limits |

## Install in one line

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={null}
    curl -fsSL https://software.cortex.foundation/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://software.cortex.foundation/install.ps1 | iex
    ```
  </Tab>
</Tabs>

Then sign in and open a session in a project:

```bash theme={null}
cortex login
cd ~/code/my-project
cortex
```

## Get started

<CardGroup cols={2}>
  <Card title="Install the CLI" icon="download" href="/cli/install">
    The installers for macOS, Linux and Windows, what the checksum check proves, pinning a version, `cortex upgrade`, uninstalling.
  </Card>

  <Card title="Sign in" icon="right-to-bracket" href="/cli/sign-in">
    `cortex login` in a browser, a device code for machines without one, single sign-on, API keys for unattended runs.
  </Card>

  <Card title="CLI quickstart" icon="rocket" href="/cli/quickstart">
    Install, sign in, a first turn in a project, `AGENTS.md`, and how much autonomy to grant on day one.
  </Card>
</CardGroup>

## Use the CLI

<CardGroup cols={2}>
  <Card title="The TUI" icon="window-maximize" href="/cli/tui">
    Everything on screen: the timeline, the composer and its chips, the footer hints, queueing a follow-up, the panels.
  </Card>

  <Card title="Modes and permissions" icon="sliders" href="/cli/modes-and-permissions">
    Agent, Plan, Ask and Bash, the approval prompt, the sandbox, and the permission table.
  </Card>

  <Card title="Plan and Spec modes" icon="list-check" href="/cli/plan-mode">
    Get a plan before anything changes, accept or keep iterating, and the stricter Spec lock.
  </Card>

  <Card title="Sessions" icon="clock-rotate-left" href="/cli/sessions">
    Sessions are files: list, resume, rewind, fork, export, import, share, lock and clean up.
  </Card>

  <Card title="Goals" icon="bullseye" href="/cli/goal">
    A long-horizon objective that survives compaction and resume, with a turn budget and evidence.
  </Card>

  <Card title="Slash commands" icon="bolt" href="/cli/slash-commands">
    Everything after `/` in the composer, grouped by purpose, plus your own custom commands.
  </Card>

  <Card title="Keyboard shortcuts" icon="keyboard" href="/cli/keyboard">
    Every binding, grouped by where it applies, and the in-app shortcuts overlay.
  </Card>

  <Card title="Tools the agent uses" icon="screwdriver-wrench" href="/cli/tools">
    Search, read, edit, shell and the rest, how each one appears in the timeline, and which ones ask first.
  </Card>

  <Card title="Cloud, This PC, and SSH" icon="server" href="/cli/hosts">
    Where a session actually runs, how to opt in to the other hosts, and why they fail closed.
  </Card>

  <Card title="Editor integration" icon="pen-to-square" href="/cli/editor">
    Driving the CLI from an editor over the agent protocol, and what is not wired yet.
  </Card>
</CardGroup>

## Automate

<CardGroup cols={2}>
  <Card title="Headless and one-shot runs" icon="gears" href="/cli/headless">
    `cortex run` and `cortex exec`: autonomy levels, output formats, turn and time limits, exit codes.
  </Card>

  <Card title="CI cookbook" icon="code-merge" href="/cli/ci">
    Recipes for pipelines: the key in the environment, parsing the result document, reviewing uncommitted changes.
  </Card>
</CardGroup>

## Configure

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/cli/configuration">
    `config.toml` keys, profiles, and the five layers that decide which value wins.
  </Card>

  <Card title="Environment variables" icon="list" href="/cli/environment-variables">
    Every `CORTEX_*` variable the CLI reads and what each one overrides.
  </Card>

  <Card title="Data locations" icon="folder-tree" href="/cli/data-locations">
    Where sessions, configuration, cache and credentials live on each operating system.
  </Card>

  <Card title="Permission policy" icon="file-shield" href="/cli/policy">
    Allow and deny rules for tools and commands, and the managed policy an organization can set.
  </Card>
</CardGroup>

## Extend

<CardGroup cols={2}>
  <Card title="MCP servers" icon="server" href="/cli/mcp">
    Add a server, the supported transports, authentication, tool naming, and the connection panel.
  </Card>

  <Card title="Skills" icon="graduation-cap" href="/cli/skills">
    Skill files, where the CLI looks for them, how the agent picks one, and writing your own.
  </Card>

  <Card title="Agents and subagents" icon="sitemap" href="/cli/agents">
    Custom agents, their tool access, and when the CLI delegates part of a turn.
  </Card>

  <Card title="Hooks" icon="link" href="/cli/hooks">
    The hooks block in a plugin manifest, which events actually fire, and why a hook can refuse but never approve.
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/cli/plugins">
    Installing and enabling plugins, the sandbox they run in, and the development workflow.
  </Card>

  <Card title="Themes" icon="palette" href="/cli/themes">
    The built-in themes, switching them, and the related display settings.
  </Card>
</CardGroup>

## Reference

<CardGroup cols={2}>
  <Card title="Command reference" icon="book" href="/cli/reference">
    Every `cortex` subcommand and flag, one table per command group.
  </Card>

  <Card title="CLI troubleshooting" icon="life-ring" href="/cli/troubleshooting">
    The diagnostic commands first, then the messages you might see and what to do about each.
  </Card>
</CardGroup>

## 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.

| In Code                   | In the CLI                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| A session on a repository | Change into the project directory and run `cortex`; the CLI reuses that workspace's Code session, so turns continue the same session |
| Ask, Plan and Agent       | Press **Shift+Tab** to cycle Agent, Plan and Ask                                                                                     |
| Stop                      | Press **Esc**; the timeline shows `Stopped`                                                                                          |
| The Cloud host            | The default for the session view and for `cortex exec`                                                                               |
| This PC and SSH           | Opt in per session, and only with an already connected Code session                                                                  |
| Approvals                 | A numbered prompt in the composer before anything consequential                                                                      |
| Model choice              | The model chip at the bottom right of the composer, and the model picker                                                             |

| The CLI does                                               | The CLI does not                   |
| ---------------------------------------------------------- | ---------------------------------- |
| Drive Code sessions from a terminal                        | Run a model on your own machine    |
| Work in a project directory                                | Replace Cortex Chat                |
| Offer This PC and SSH hosts                                | Put those hosts in the browser     |
| Extend with MCP servers, skills, agents, hooks and plugins | Manage Cortex Bot or Cortex Design |

## 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](https://github.com/CortexLM/cli), licensed Apache-2.0.

<Note>
  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.
</Note>

## Related

* [Install the CLI](/cli/install)
* [Sign in](/cli/sign-in)
* [CLI quickstart](/cli/quickstart)
* [Cortex Code](/code/index) and [Code in the terminal](/code/cli)
* [CLI troubleshooting](/cli/troubleshooting)