---
title: "Cortex CLI reference"
canonical: https://workspace.socra.com/docs/cortex/reference/cli
---

# Cortex CLI reference

The Cortex CLI is the `cortex` namespace of the company-wide CLI. Run `socra cortex --help` for the commands installed on your computer.

## Install the CLI

Use [guided CLI setup](https://cortex.socra.com/setup?method=cli&step=install-cli) for one action at a time. CLI access works in a terminal or an agent that can run terminal commands.

### macOS and Linux

Open Terminal and run:

```bash
curl -fsSL https://cli.socra.cloud/install.sh | sh
```

### Windows

Open PowerShell and run:

```powershell
irm https://cli.socra.cloud/install.ps1 | iex
```

Open a new terminal after installation. If Socra is already installed, run `socra update`.

## Add Cortex

Run:

```bash
socra install cortex
```

If the terminal cannot find `socra`, close and reopen it so it picks up the installer’s path changes.

## Sign in

Run:

```bash
socra account login
```

In the browser that opens, sign in and choose the Account you use in Cortex. Return when the terminal confirms sign-in. Use `socra account switch` if you selected the wrong Account.

## Agent instructions

These suggested instructions teach your agent to Flash the right knowledge before acting, without reminders. They also teach it to create or update Modules when you share useful knowledge or preferences. You can edit or skip them.

If an agent will use the CLI, add these instructions to its persistent instructions alongside any existing text. The agent needs terminal access. A single chat message does not configure future sessions.

[Open just the Cortex instructions as Markdown](https://workspace.socra.com/docs/cortex/instructions.md). This link serves the current instructions without the installation guide.

```text
Cortex helps people and teams stop repeating themselves to their AI. It keeps their preferences, requirements, decisions, and reasons in a single source of truth that agents can retrieve across conversations and tools.

Modules hold that knowledge, Dependencies connect prerequisite Modules, Flash loads a Module and its Dependencies, and Issues track work that needs coordination.

Before executing a task, find and Flash its narrowest relevant Module, using Search or Map if needed.

When conversation or work reveals preferences, requirements, decisions, or other specific knowledge, update the relevant Modules or create missing ones. Preserve the knowledge and its reasons, keep Dependencies consistent, and Flash to verify. Briefly tell the user what changed and why.
```

This is the complete [canonical Cortex guidance](https://github.com/socra/agent-plugins/blob/main/shared/cortex/session-start.md). For terminal access, use `socra cortex map`, `socra cortex module search`, and `socra cortex flash` for discovery and flashing. The guidance explains Cortex's capabilities and owner-governed knowledge, leaving the agent room to judge how they can help your work.

## Verify CLI access

Start a new agent conversation and send:

```text
Run socra cortex map to list the Modules I can access (an empty list is valid). Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything.
```

Check the actual command result. An empty list is valid for a new Account; an error or an answer without running the command is not successful verification. Check the guidance report separately. If you saved instructions but the new conversation did not receive them, check their saved location and scope. If you skipped instructions, CLI access can still work; report the guidance as skipped.

In a terminal-only session, run the command yourself. This checks CLI access; it does not check an agent's persistent instructions.

```bash
socra cortex map
```

## Setup and discovery

- [`socra cortex setup`](/docs/cortex/integrations/coding-agents#install-automatically) detects supported coding agents and installs or updates the Cortex plugin.
- [`socra cortex map`](/docs/cortex/concepts/modules-and-map#the-knowledge-map) shows the Module graph you can access.
- [`socra cortex usage`](/docs/cortex/concepts/flashing-context#usage) summarizes Flash usage over an optional time window.

## Knowledge

- [`socra cortex flash`](/docs/cortex/concepts/flashing-context) retrieves one Module and its dependency closure.
- [`socra cortex module`](/docs/cortex/concepts/modules-and-map) creates and manages Modules, content, dependencies, and lifecycle state.
- [`socra cortex flashes`](/docs/cortex/concepts/flashing-context#usage) inspects recorded Flash history.

### Inspect Module version history

Use `socra cortex module version list <module-name>` to list immutable versions, newest first. Use `socra cortex module version get <module-name> <version>` to read one complete snapshot, or `socra cortex module version diff <module-name> <from> <to>` to compare two versions.

Version history records authored Module state. Follow [Modules and the knowledge map](/docs/cortex/concepts/modules-and-map#version-history) for the conceptual model.

## Work

- [`socra cortex inbox`](/docs/cortex/concepts/inbox) lists or watches work released to the authenticated principal.
- [`socra cortex issue`](/docs/cortex/concepts/issues-and-coordination) creates, reads, searches, and updates Issues.
- [`socra cortex comment`](/docs/cortex/concepts/issues-and-coordination#comments) manages authored Issue comments.
- [`socra cortex attachment`](/docs/cortex/guides/issue-attachments) manages private files owned by an Issue.
- [`socra cortex label`](/docs/cortex/guides/issue-labels) manages reusable Issue labels.
- [`socra cortex issue-schedule`](/docs/cortex/guides/issue-schedules) manages schedules that create ordinary Issues.

## Command help

Append `--help` to a command group or action to inspect its current arguments and options. For example, `socra cortex issue create --help` describes the installed Issue creation contract.

Run `socra update` before diagnosing a command that is missing or returns data that does not match the current Cortex service. Client and server version skew can resemble a service failure. Follow [Troubleshoot Cortex](/docs/cortex/troubleshooting) if updating does not resolve the problem.