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.

Latest release: v1.1.4 — Release notes

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-cli project init my-project

# Create and start a sprint
cortex-cli --project my-project sprint init sprint-001 --name "My Sprint"
cortex-cli --project my-project sprint set-status sprint-001 --status "IN EXECUTION"

# Add and manage tasks
cortex-cli --project my-project task add --sprint sprint-001 --content-file /tmp/task.md --owner captain
cortex-cli --project my-project task move 0001 --to "In Progress" --stage Implementation --owner coder
cortex-cli --project my-project task move 0001 --to "In Review" --owner master

# Validate the board
cortex-cli --project my-project validate board --sprint sprint-001

# Close sprint
cortex-cli --project my-project sprint set-status sprint-001 --status CLOSED

Project Resolution

Every command requires an explicit project. Resolution follows this priority order:

1. --project <name> flag — highest priority; if specified but the name is not found in the registry, the command fails immediately (short-circuit — no fall-through to CWD match)
2. Current working directory match — if the CWD is within a registered project directory, that project is used
3. If neither method resolves a project, the command fails with an error instructing the user to use --project <name> or run from a registered project directory

There is no longer a default project concept.

Commands

Project Management

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

Sprint Lifecycle

| Command | Description | |---------|-------------| | sprint init <id> | Create a new sprint (PLANNING state) | | sprint set-status <id> | Transition sprint status (PLANNING, IN EXECUTION, CLOSING, CLOSED) | | sprint overview [id] | Display sprint overview and task breakdown | | sprint update [id] | Update sprint name or goal | | sprint list | List all sprints |

Task Management

| Command | Description | |---------|-------------| | task add | Add task to sprint (content via --content-file; ID auto-generated and printed) | | task move <id> | Move task status/stage (requires --to, --stage, --owner) | | task move <id> --dry-run | Preview move without committing | | task update <id> | Update task metadata | | task remove <id> | Permanently delete a task | | task show <id> | Display task details | | task list | List tasks in a sprint |

Document Registry

| Command | Description | |---------|-------------| | doc add --type --title | Register documents (inline or file-based content; ID auto-generated and printed) | | 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 | Create reviews (ID auto-generated and printed) | | review list [--sprint] / review show <id> | Browse review records | | review remove <id> | Permanently delete a review | | test-report add | Record test execution results (ID auto-generated and printed) | | test-report list / test-report show <id> | Browse test reports | | test-report remove <id> | Permanently delete a test report | | 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-cli --project my-project project info my-project --format json
cortex-cli --project my-project task list --format table
cortex-cli --project my-project task show 0001 --format markdown
cortex-cli --project my-project task list --quiet
cortex-cli --project my-project task list --json

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

Kanban States

Sprint lifecycle:

PLANNING → IN EXECUTION → CLOSING → CLOSED

Task stages (6 consolidated stages):

Planning → Requirement+Specification → Design → Implementation → Testing → Release

Task status lifecycle (restricted transitions):

Backlog → To Do → In Progress → In Review → Done
   ↕        ↕         ↕             ↕          ↕
  To Do   Backlog    To Do         To Do    In Progress
Dropped  Dropped   In Review    In Progress  In Review
                    Dropped       Dropped     Dropped

• All stage, status, and role names are case-insensitive
• Stage transitions are free (forward, backward, and same-stage all allowed)
• Dropped tasks can be recovered (Dropped → Backlog or To Do)

Global Options

| Option | Description | |--------|-------------| | -p, --project <name> | Target a specific project (required unless CWD is in a registered project directory) | | --sprint <id> | Scope to a sprint | | --format <type> | Output format: table, json, markdown, quiet | | --json | Shorthand for --format json | | --quiet | Minimal output | | --dry-run | Preview task move without committing | | -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 (1065 tests)
npm run lint            # Type-check only

License

MIT