dcx — DevCortex CLI

Version: 1.4.0
Package: @devcortex/cli
Platform: devcortexai.com

The dcx CLI connects AI coding agents (Claude Code, Cursor, OpenCode) to your DevCortex project. It handles authentication, project linking, CLAUDE.md generation, and live supervision — replacing manual curl workflows with two commands.

┌─────────────────────────────────────────────────────┐
│  Without dcx                  With dcx              │
│  ───────────────────          ──────────────────    │
│  1. Login via curl            dcx login             │
│  2. Fetch project ID                                │
│  3. Generate API key          dcx start             │
│  4. Write .mcp.json                                 │
│  5. Download CLAUDE.md                              │
│  6. Start claude                                    │
└─────────────────────────────────────────────────────┘

Installation

npm install -g @devcortex/cli

Requires Node.js 18 or higher.

Permission error? If you see EACCES: permission denied, either:

Option 1 — use sudo (simplest):

sudo npm install -g @devcortex/cli

Option 2 — use pnpm (recommended):

npm install -g pnpm
pnpm install -g @devcortex/cli

Option 3 — configure npm user directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @devcortex/cli

Note: on some Linux systems the npm global symlink may not execute correctly. If dcx produces no output after install, use pnpm or sudo instead.

See npm docs on fixing permissions for more options.

Verify:

dcx --version
dcx --help

Quick Start

# 1. Authenticate
dcx login

# 2. Link your project directory to DevCortex
cd ~/my-project
dcx init

# 3. Launch your AI agent with CLAUDE.md refreshed
dcx start

dcx start fetches the latest requirements and issues from DevCortex, writes them to CLAUDE.md, and launches Claude Code (or OpenCode) — so your agent always starts with the current project context.

Commands

| Command | Description | |---|---| | dcx login | Authenticate and store token locally | | dcx init | Link current directory to a DevCortex project | | dcx start | Refresh CLAUDE.md and launch AI agent | | dcx update | Refresh CLAUDE.md without launching agent | | dcx status | Show project health summary | | dcx logs | Stream live audit events to terminal | | dcx keys | Manage project API keys | | dcx list | Query requirements, backlog, and issues | | dcx export | Export requirements to CSV | | dcx import | Import requirements from CSV | | dcx test-mcp | Self-diagnose MCP connection health | | dcx issue | Manage issues |

dcx login

dcx login
dcx login --email [email protected] --password mypassword

Authenticates with DevCortex and stores your JWT token in ~/.devcortex/config.json.

dcx init

dcx init
dcx init --agent opencode      # generate AGENTS.md instead of CLAUDE.md
dcx init --agent cursor        # generate .cursorrules
dcx init --project <projectId> # skip project selector
dcx init --force               # overwrite existing files

Links the current directory to a DevCortex project. Creates:

| File | Purpose | Commit? | |------------------------|--------------------------------------|----------------| | .mcp.json | MCP API key for Claude Code | ❌ No (secret) | | .cursor/mcp.json | MCP API key for Cursor | ❌ No (secret, auto-added to .gitignore) | | CLAUDE.md | Agent constitution with requirements | ✅ Yes | | .cursorrules | Cursor agent constitution | ✅ Yes | | .devcortex-link.json | Project link (no secrets) | ✅ Yes |

.mcp.json and .cursor/mcp.json are automatically added to .gitignore.

dcx start

dcx start
dcx start --agent claude
dcx start --agent opencode
dcx start --agent cursor
dcx start --no-init    # skip CLAUDE.md refresh, launch immediately

Refreshes CLAUDE.md from the live database and launches your AI agent. Auto-detects Claude Code or OpenCode on your PATH.

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Install OpenCode:

npm install -g opencode-ai

dcx update

dcx update
dcx update --watch    # keep CLAUDE.md in sync continuously (polls every 60s)

Refreshes CLAUDE.md without launching an agent. Use --watch in a background terminal when requirements change frequently during a session.

dcx status

dcx status
dcx status --json    # machine-readable output

Displays project health: requirements count, open issues, MCP connection status, token validity, and spec version.

dcx logs

dcx logs
dcx logs --tail 50
dcx logs --follow

Streams live audit events from DevCortex — shows what your AI agent is reading and writing in real time.

dcx keys

dcx keys list                  # list all API keys for the project
dcx keys regenerate            # rotate the key in .mcp.json
dcx keys revoke <keyId>        # revoke a specific key

Manages project-scoped API keys used by the MCP server.

dcx list

dcx list backlog
dcx list backlog --status APPROVED
dcx list issues
dcx list issues --severity HIGH

Queries and displays requirements and issues from DevCortex.

dcx export

dcx export --csv                        # print CSV to stdout
dcx export --csv --out requirements.csv # write to file

Exports project requirements as CSV.

dcx import

dcx import --csv requirements.csv            # import from file
dcx import --csv requirements.csv --dry-run  # preview only
dcx import --list                            # list all supported import formats

Imports requirements from CSV. Rows are matched by reqId — existing requirements are skipped, new ones are created.

Importing

The dcx import command supports multiple source formats. Use dcx import --list to see all supported formats.

dcx import kiro

Import requirements from an AWS Kiro requirements.md spec file. Kiro's spec-driven development workflow produces a structured requirements document that maps directly to DevCortex specs and requirements.

# Preview what would be imported (no changes made)
dcx import kiro ./requirements.md --dry-run

# Import with defaults (MUST priority, DRAFT status, version 1.0.0)
dcx import kiro ./requirements.md

# Import with custom version and priority
dcx import kiro ./requirements.md \
  --spec-version 2.0.0 \
  --spec-title "Sprint 15 Requirements" \
  --priority SHOULD

Options:

| Option | Description | Default | |---|---|---| | --spec-version <ver> | Version string for the new Spec | 1.0.0 | | --spec-title <title> | Title for the new Spec version | Imported from Kiro | | --priority <p> | Default priority: MUST | SHOULD | COULD | WONT | MUST | | --status <s> | Default status: DRAFT | APPROVED | DRAFT | | --dry-run | Preview without making API calls | — | | --verbose | Show full AC text in preview and during import | — |

What gets imported:

• The ## Introduction and ## Glossary sections become the Spec version overview
• Each ### Requirement N: [Title] becomes a DevCortex requirement
• **User Story:** text is imported as the requirement's user story
• Numbered items under #### Acceptance Criteria become individual acceptance criteria

dcx import linear

Import issues from a Linear CSV export. Linear sprint issues map directly to DevCortex requirements — re-importing after editing issues in Linear updates existing requirements rather than creating duplicates.

# Export from Linear: Issues → Export → Download CSV

# Preview what would be imported (no changes made)
dcx import linear ./Export_*.csv --dry-run

# Import all issues from the CSV
dcx import linear ./Export_*.csv

# Import issues from a specific sprint/cycle only
dcx import linear ./Export_*.csv --cycle "Sprint 1"

# Import with Linear issue ID prefixed to title
dcx import linear ./Export_*.csv \
  --cycle "Sprint 1" \
  --prefix-id \
  --spec-title "Sprint 1 Requirements"

Options:

| Option | Description | Default | |---|---|---| | --cycle <name> | Filter by cycle/sprint name (case-insensitive) | all issues | | --spec-version <ver> | Version string for the new Spec | 1.0.0 | | --spec-title <title> | Title for the new Spec version | Imported from Linear (or Imported from Linear — {cycle} when --cycle is set) | | --priority <p> | Override priority for all requirements: MUST | SHOULD | COULD | WONT | from Linear (Urgent/High → MUST, Medium → SHOULD, Low → COULD) | | --status <s> | Default status: DRAFT | APPROVED | DRAFT | | --prefix-id | Prefix Linear issue ID to requirement title (e.g. DCX-5 — Title) | — | | --dry-run | Preview without making API calls | — | | --verbose | Show full AC text in preview and during import | — |

What gets imported:

• Each issue row becomes one DevCortex requirement
• Issue title becomes the requirement title; use --prefix-id to prepend the Linear ID (e.g. DCX-5 — Title)
• Description text before an Acceptance Criteria: heading becomes the requirement user story
• Lines starting with \- under Acceptance Criteria: become individual acceptance criteria
• Linear priority is mapped: Urgent/High → MUST, Medium → SHOULD, Low → COULD
• Cycle name and labels are imported as requirement tags
• Each requirement is stored with a linear:{ID}:{UUID} external reference — re-importing after editing issues in Linear updates existing requirements rather than creating duplicates

Cursor MCP Setup

dcx init --agent cursor generates .cursor/mcp.json and .cursorrules for your project. Cursor uses .cursor/mcp.json (not .mcp.json) and requires a one-time manual enable step before MCP tools are available.

Enable DevCortex in Cursor Settings

After running dcx init --agent cursor:

1. Open Cursor Settings → MCP
2. Find devcortex in the server list and toggle it Enabled
3. Fully quit and restart Cursor (⌘Q on Mac, Ctrl+Q on Windows/Linux — closing the window is not enough)

This enable step is one-time per machine. Once enabled it persists across projects and future Cursor restarts.

Verify the connection

In an Agent mode chat, send:

dc_health

A successful response confirms Cursor has loaded the DevCortex MCP tools and your API key is valid.

Troubleshooting

Wrong filename — Cursor reads .cursor/mcp.json, not .mcp.json in the project root. If DevCortex tools are missing, confirm the file is in the .cursor/ subdirectory.

Missing closing brace — A malformed JSON file silently disables MCP. Validate with:

cat .cursor/mcp.json | python3 -m json.tool

Must restart Cursor fully — Closing and reopening a window is not enough. Use Quit (⌘Q / Ctrl+Q) and relaunch Cursor completely.

dcx test-mcp

dcx test-mcp

Self-diagnoses the MCP connection. Runs four checks:

1. API reachable
2. API key valid
3. Project accessible
4. MCP tools available

✔  1. API reachable
✔  2. API key valid
✔  3. Project accessible
✔  4. MCP tools available

✔ MCP connection healthy — 12 tools registered for my-org/My Project

Run this whenever Claude Code reports an MCP connection error.

Typical Workflows

Start a new project

mkdir my-app && cd my-app
dcx init
dcx start

Resume after a break

cd my-app
dcx start    # refreshes CLAUDE.md then launches agent

Monitor an agent session

# Terminal 1 — agent
dcx start

# Terminal 2 — live supervision
dcx logs

Keep CLAUDE.md in sync automatically

# Terminal 1 — watch for requirement changes
dcx update --watch

# Terminal 2 — agent (skip refresh since watch handles it)
dcx start --no-init

New team member setup

git clone https://github.com/org/my-project
cd my-project
dcx login
dcx init      # generates personal .mcp.json (not committed)
dcx start

Use Cursor

dcx init --agent cursor

Open the project in Cursor, go to Settings → MCP, enable devcortex, then fully restart Cursor. Verify with dc_health in Agent mode.

Diagnose MCP problems

dcx test-mcp
# If key is stale:
dcx init --force
dcx test-mcp

Configuration

Config is stored at ~/.devcortex/config.json:

{
  "token": "eyJhbGci...",
  "tokenExpiry": "2026-06-17T00:00:00.000Z",
  "apiUrl": "https://api.devcortexai.com",
  "defaultOrgSlug": "my-org",
  "defaultProjectId": "cmmxbv3v..."
}

Environment Variables

| Variable | Description | Default | |----------------|-----------------------|-------------------------------| | DCX_API_URL | Override API URL | https://api.devcortexai.com | | DCX_NO_COLOR | Disable colour output | unset |

Override API URL

dcx login --api-url https://staging-api.devcortexai.com
dcx status --api-url https://staging-api.devcortexai.com

Troubleshooting

✗ Not logged in — run dcx login first
Your token has expired (7-day TTL). Run dcx login.

✗ No project linked — run dcx init first
Run dcx init in your project directory.

✗ API unreachable
Check your internet connection or verify the API URL with dcx status.

✗ No AI agent found
Install Claude Code (npm install -g @anthropic-ai/claude-code) or OpenCode (npm install -g opencode-ai).

MCP connection fails in Claude Code
Run dcx test-mcp — it pinpoints exactly which of the four connection steps is failing and shows the fix.

Cursor MCP tools not showing
Ensure DevCortex is enabled in Cursor Settings → MCP and that you fully restarted Cursor (Quit, not just close the window). The config file must be .cursor/mcp.json — not .mcp.json in the project root. See Cursor MCP Setup for the full troubleshooting checklist.

Blank screen on macOS Terminal.app after dcx login Upgrade to v1.5.1+: npm install -g @devcortex/cli@latest Or use flags directly: dcx login --email [email protected] --password yourpassword

Reset config

rm ~/.devcortex/config.json
dcx login
dcx init

Files Reference

| File | Location | Purpose | Commit? | |------------------------|----------------------|--------------------------|---------| | config.json | ~/.devcortex/ | Token + defaults | ❌ No | | .mcp.json | Project root | MCP API key (Claude Code)| ❌ No | | .cursor/mcp.json | Project .cursor/ | MCP API key (Cursor) | ❌ No | | .devcortex-link.json | Project root | Project link | ✅ Yes | | CLAUDE.md | Project root | Claude Code constitution | ✅ Yes | | .cursorrules | Project root | Cursor agent constitution| ✅ Yes | | AGENTS.md | Project root | OpenCode constitution | ✅ Yes |

Links

• Platform: devcortexai.com
• npm: npmjs.com/package/@devcortex/cli
• Support: [email protected]

DevCortex is built by MainRobin Pty Ltd(https://www.devcortexai.com). © 2026 MainRobin Pty Ltd.