cortex-cli

A TypeScript CLI for managing software project artifacts — sprints, kanban boards, knowledge graphs, documents, reviews, and traceability — backed by SQLite with safe concurrent multi-process access.

Installation

From npm (recommended)

npm install -g @lwelliott/cortex-cli

From source

git clone https://github.com/lwelliot/cortex-cli.git
cd cortex-cli
npm install
npm run build

Verify installation

cortex-cli --version
cortex-cli --help

Quick Start

# Initialize a project
cortex project init my-project

# Create and start a sprint
cortex -p my-project sprint init sprint-001
cortex -p my-project sprint start

# Add and manage tasks
cortex -p my-project task add --content-file /tmp/task-content.md --stage IMPL --owner coder
cortex -p my-project task move 0001 "In Progress"
cortex -p my-project task move 0001 "Done"

# Validate the board
cortex -p my-project validate board

# Close sprint
cortex -p my-project sprint close

Commands

Project Management

| Command | Description | |---------|-------------| | project init <name> | Initialize a new project with SQLite database | | project info | Display project overview and sprint summary | | project list | List all projects | | project remove <name> | Remove a project |

Sprint Lifecycle

| Command | Description | |---------|-------------| | sprint init <id> | Create a new sprint (PLANNING state) | | sprint start | Begin sprint execution (IN EXECUTION) | | sprint close | Close sprint after review (CLOSED) | | sprint overview [id] | Display sprint overview and task breakdown | | sprint update [id] | Update sprint name or goal |

Task Management

| Command | Description | |---------|-------------| | task add [id] | Add task to sprint with optional positional ID (content via --content-file) | | task move <id> <state> | Move task between kanban states | | task update <id> | Update task metadata (owner, notes) | | task remove <id> | Permanently delete a task | | task show <id> | Display task details |

Document Registry

| Command | Description | |---------|-------------| | doc add <id> --type --title | Register documents (inline or file-based content) | | doc list [--type] | List documents with pagination and sorting | | doc show <id> | Display document details | | doc search <query> | FTS5 full-text search with ranking | | doc update <id> / doc remove <id> | Modify or remove document registrations |

Knowledge Graph

| Command | Description | |---------|-------------| | graph validate | Check graph integrity | | graph status | Show graph schema status | | graph entity create/get/query/update/delete | Entity CRUD | | graph relation relate/unrelate/related | Relation management | | graph export | Export graph data | | graph migrate [--phase] | Run schema migration |

Schema is auto-initialized from project-schema.yaml during project create with 18 relation types and entity types derived from doc types.

Audit & Traceability

| Command | Description | |---------|-------------| | audit | Run all 11 audit checks (4 integrity + 7 traceability) | | audit --checks <name,...> | Run specific checks | | audit --fix | Auto-fix supported issues | | audit --fix-dry-run | Preview fixes without applying |

Traceability checks:

• us-to-fr-nfr — US→FR/NFR traceability
• fr-nfr-to-fs-nfs — FR/NFR→FS/NFS traceability
• fs-nfs-to-sad-ad-qa — FS/NFS→SAD/AD/QA traceability
• fs-nfs-to-ts — FS/NFS→TS traceability
• ts-to-tc — TS→TC traceability
• sad-ad-qa-tc-to-src — SAD/AD/QA/TC→SRC traceability
• src-filesystem-only — SRC files exist on filesystem

Review & Reporting

| Command | Description | |---------|-------------| | review add <id> | Create reviews with positional ID | | review list [--sprint] / review show <id> | Browse review records | | test-report add <id> | Record test execution results | | test-report list / test-report show <id> | Browse test reports | | lesson update | Record and update lessons learned |

Board Validation

| Command | Description | |---------|-------------| | validate board | Check board shape, integrity, and state fields | | validate spawn --sprint --task --stage --role | Validate spawn legality |

Output Formats

All commands support multiple output formats:

cortex project list --format json        # Structured JSON
cortex project list --format table       # Tabular (default for list/actions)
cortex project info --format markdown    # Markdown (default for info/show)
cortex project list --quiet              # Minimal output
cortex project list --json               # Shorthand for --format json

Precedence: --quiet > --format > --json

Kanban States

Sprint lifecycle:

PLANNING → IN EXECUTION → CLOSING → CLOSED

Task lifecycle:

Backlog → To Do → In Progress → In Review → Done
         ↘ Blocked (from any state)
         ↘ Dropped (from any state)

Global Options

| Option | Description | |--------|-------------| | -p, --project <name> | Target a specific project | | --sprint <id> | Scope to a sprint (defaults to latest non-closed) | | --format <type> | Output format: table, json, markdown, quiet | | --json | Shorthand for --format json | | --quiet | Minimal output | | -V, --version | Print version | | -h, --help | Display help |

Development

npm install            # Install dependencies
npm run build          # TypeScript compilation
npm run build:release  # Build single-file release binary
npm test               # Run test suite
npm run lint            # Type-check only

License

MIT