Skip to content

Updated

Cortex CLI reference

View as Markdown

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 (new tab) 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

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

Before signing in, review the access you are granting. Cortex CLI commands can read and modify data that your selected Account permits. The read-only verification does not restrict later commands to reads. Review commands and run only the actions you intend.

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.

Inspect Account profiles

These company-wide CLI commands read local Account profiles without changing credentials or the active profile.

Check authentication status for the active profile:

Bash
socra account status

To check a named profile, replace PROFILE_NAME with its name:

Bash
socra account status --profile PROFILE_NAME

The --profile option applies to account status and defaults to the active profile when omitted.

List local Account profiles:

Bash
socra account profile list

The list marks the active profile with *. This command has no --profile option.

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.

This reference describes the commands your agent can run. You do not need to run them yourself or fill the graph before using Cortex. Choose your review preference, then continue your work; the agent can maintain useful knowledge automatically or recommend changes for approval.

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. 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 distill work that needs coordination into human-readable tasks.

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

Knowledge

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 for the conceptual model.

Inspect recorded Flash history

Use Flash history to inspect a previous context retrieval. These commands read existing records; they do not create a new Flash.

List recorded Flashes, newest first:

Bash
socra cortex flashes list --limit 20

To filter by the requested Module, replace MODULE_NAME with its exact name:

Bash
socra cortex flashes list --target MODULE_NAME --limit 20

The table shows each Flash's ID, target Module, Module count, token count, and age. If more results remain, use the printed --after cursor with the same filters to read the next page. An empty result means no records matched the query.

Replace FLASH_ID with an ID returned by the list command. Read its totals and closure manifest:

Bash
socra cortex flashes get FLASH_ID

The manifest identifies the target and dependency Modules, their recorded versions, and their token contributions. A legacy record can show a version as unknown.

To rebuild the target's current context bundle, run:

Bash
socra cortex flashes get FLASH_ID --assembly

This rebuilds the target's current dependency closure using current Module content. The result can differ from the versions and dependencies in the recorded manifest. Save the original Flash output if you need the exact context it returned. Reading an assembly does not create a new metered Flash.

The target and its current dependencies must still be available and active. Archived Modules cannot be assembled. An assembly does not reconstruct missing historical snapshots; use Module version history separately where available. Current access rules apply. If access is denied or a record is unavailable, follow Troubleshoot Cortex before retrying. History inspection does not grant access to edit the listed Modules.

Inspect roles

List role definitions and their permissions as JSON:

Bash
socra cortex role list

To read one definition, replace ROLE_KEY with a role key, such as issue_contributor:

Bash
socra cortex role get ROLE_KEY

Reading a role definition does not grant that role to your identity.

Work

Read Issue comments

Replace ISSUE_ID with the ID of an Issue you can read:

Bash
socra cortex comment list --issue ISSUE_ID

Comments appear oldest first. The default page contains at most 20 comments. When more comments remain, the CLI prints a cursor. Replace CURSOR with that value to read the next page:

Bash
socra cortex comment list --issue ISSUE_ID --limit 20 --after CURSOR

Use --limit to choose the maximum number of comments in a page.

Read an Issue timeline

Replace ISSUE_ID with the ID of an Issue you can read:

Bash
socra cortex issue timeline ISSUE_ID

The timeline combines recorded Issue events and authored comments, oldest first. These commands read existing Issue history without changing the Issue or its comments.

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.

If a command fails, record its error and check the command's help. Update with socra update when the installed command or response contract differs from the current documentation. Authentication errors, denied access, timeouts, and service failures need their own checks. Follow Troubleshoot Cortex to identify the cause before retrying.

See also