CLI Commands

Complete reference for all Cortex CLI commands.

cortex login

Authenticate with an agent key and store credentials locally.

Usage

cortex login [--key crtx_...] [--url https://your-cortex-host]

Flags

Flag	Description
`--key`	Agent key (or use `CORTEX_API_KEY` env)
`--url`	Cortex endpoint (or use `CORTEX_URL` env, default: `http://localhost:4040`)

--url defaults to http://localhost:4040. If your Cortex runs anywhere else (a deployed host), omitting --url makes login fail with Verifying with Cortex… ✗ fetch failed — it's trying to reach a local server that isn't there. The onboarding screen fills in the correct --url for you automatically.

Interactive Mode

If --key is not provided, you'll be prompted:

Paste your Cortex API key (crtx_...):

Examples

# Login with flags
cortex login --key crtx_abc123 --url https://cortex.example.com

# Login with env vars
export CORTEX_API_KEY="crtx_abc123"
export CORTEX_URL="https://cortex.example.com"
cortex login

# Interactive login
cortex login

Output

Verifying with Cortex… done.
✓ Logged in as John Doe <john@company.com> — role IC.
  Credentials saved to /Users/john/.cortex/config.json

cortex whoami

Show the currently authenticated identity.

Usage

cortex whoami

Output

John Doe <john@company.com> — role IC, level Senior
Endpoint: https://cortex.example.com

cortex push

Push a file as a memory into Cortex.

Usage

cortex push <file> [--title "..."] [--scope engineering]

Flags

Flag	Description
`--title`	Human-readable title (defaults to filename)
`--scope`	Scope key to write into (e.g., `engineering`)

Examples

# Push a markdown file
cortex push ./api-design.md --title "API Design Guidelines" --scope engineering

# Push with default title (filename)
cortex push ./notes.txt --scope public-docs

# Push without scope (uses source-based default)
cortex push ./decision.md

Output

✓ Pushed memory a1b2c3d4-e5f6-7890-abcd-ef1234567890

Error Cases

Error	Cause
`Not logged in`	Run `cortex login` first
`Verifying with Cortex… fetch failed`	Wrong `--url` — the CLI can't reach the host. Pass `--url https://your-cortex-host`
`File not found`	Check the file path
`push failed: scope denied`	Your role can't write to this scope

Environment Variables

Variable	Description	Overrides
`CORTEX_API_KEY`	Agent key	`--key` flag
`CORTEX_URL`	Cortex endpoint	`--url` flag

Credential Storage

Credentials are stored at ~/.cortex/config.json:

{
  "apiKey": "crtx_...",
  "url": "https://cortex.example.com",
  "actingUser": {
    "name": "John Doe",
    "email": "john@company.com",
    "role": "IC",
    "level": "Senior"
  }
}

The config file is created with mode 600 (owner read/write only). Do not share your agent key.