Skip to main content
The Cortex CLI is Cortex Code in a terminal. It signs in with the same Cortex account and drives the same sessions, so a run you start from a shell is the same piece of work you can open in your browser: it appears on the sessions board marked · Started from CLI, with its transcript, its worklog and its approvals exactly where they would be if you had typed the task into the composer. The terminal is another front end onto Code, not a second product with its own history. This page is the bridge between the two. It covers when the terminal is the better surface, how CLI vocabulary maps onto the words used throughout the Code tab, what does not carry across, and which pages of the Cortex CLI tab answer everything else. Installers, commands, flags and exit codes live there on purpose. A command list copied onto a Code page drifts out of date, so this page links instead of repeating.

​
When to reach for the terminal

The terminal is the right surface when the work starts where you already are. You are in a project directory, you want to describe a change without leaving the shell, and you want the result as a branch and a pull request like any other Code session. It is also the only way to drive Code from a script or a pipeline, which the CLI has a dedicated headless mode for. Stay in the browser when the work is about reading rather than typing. The Changes pane, the live diff of the attached runtime, the Plan tab and the pull-request link are browser surfaces, and a pending file write is answered there with Approve whichever surface started the session. Approvals belong to the session, not to the window you happen to have open: attach to the session in the browser and you can answer them there.

​
Code words, CLI words

The concepts are the same on both sides. Only the names differ, and this is the map. When you are describing something to a colleague looking at the browser, use the Code words. When you are reading CLI help output, expect the CLI words.

​
Where a run executes

The CLI makes the same runtime choice Code makes everywhere else, and it makes it the same way: Cloud is the default, and This PC and SSH are opt-in. Both of those need an already connected Code session. The CLI will not create one for you on the fly, and it will not quietly substitute Cloud without saying so, because a turn binds one runtime and there is no silent fallback. The switches that select a host from your shell are the CLI’s own, and they are documented with it in environment variables and Cloud, This PC, and SSH. If a run refuses This PC or SSH, clearing that override returns you to Cloud, which is the usual fix.
Treat local and SSH execution as unfinished. The choice and the screens exist, but Cortex does not promise a complete run of the tools on This PC or on an SSH host today. When you need a run you can rely on end to end, use Cloud. See Cloud runtimes.

​
What the terminal does not change

  • The two gates stay separate. A command that needs a decision is answered with Allow once, Always allow and Deny; a file write is never on that rail and waits in Changes for a human Approve. What the prompt looks like in a shell is on Modes and permissions; what the gates mean is on Permissions and approvals.
  • There is still no undo, no checkpoint and no revert. Refusing a write while it is pending is the moment that matters, in a terminal exactly as in a browser.
  • A mode is a lock on the next turn. Switching between Ask, Plan and Agent changes the tools the turn is built with, so the change applies to the turn after it, never to the one already running. See Ask, Plan, Agent.
  • Extension points belong to the CLI. The CLI has its own tool servers, skills, agents, hooks and plugins, all documented in its tab. Those are the CLI’s, not a Code session’s: a Code session in the browser is given no tool servers, no connectors and no plugins of its own, and can say so under its Tools tab.
Do not assume the two surfaces are feature-for-feature identical. Cortex does not specify parity between Cloud and the terminal, and the tool names differ between them. Before you plan around something, check the CLI page that owns it.

​
One control that is browser-only

The command palette has an Initialise the repository row, reached by opening the palette and typing init or /init. It writes an AGENTS.md file inside a Cloud guest, and its dialog explains the choice plainly: Writes AGENTS.md in this Cloud guest. Keep leaves an existing file. Replace overwrites it. If no session is attached it says Open a Cloud session first., and where the deployment does not offer it, Initialise is not available on this deployment. That row is a control in the browser, not a CLI command. Do not go looking for it in help output.

​
What the CLI tab documents

Cortex CLI

The map of the whole tab: the three ways to run it, and what the CLI does and does not do.

Install the CLI

Getting the binary on macOS, Linux and Windows, pinning a version, and upgrading.

Sign in

Signing in with your Cortex account, including machines without a browser.

CLI quickstart

A first turn in a real project, and how much autonomy to grant on day one.

Cloud, This PC, and SSH

Where a run actually executes, opting in to the other hosts, and why they fail closed.

Modes and permissions

The auto level, the approval prompt, and the permission rules the CLI reads.

Headless and one-shot runs

Driving a run from a script or a pipeline, with machine-readable output.

CLI troubleshooting

The diagnostics first, then the messages a terminal run can print.