CLI Reference

The Cortex TMS CLI is the primary tool for managing your TMS projects. Use it to initialize projects, validate documentation health, check project status, and more.

Installation

# Install globally
npm install -g cortex-tms@latest

# Or use with npx (no installation)
npx cortex-tms@latest <command>

Global Usage

cortex-tms [command] [options]
cortex-tms --help          # Show help for all commands
cortex-tms --version       # Show current version

---

Available Commands

init

Initialize Cortex TMS in your project

Sets up the complete TMS documentation structure with interactive prompts.

View init documentation

validate

Validate project health and compliance

Runs comprehensive health checks to ensure documentation follows TMS standards.

View validate documentation

status

Show project health dashboard

Displays a high-level overview of scope, sprint progress, health summary, and backlog.

View status documentation

migrate

Upgrade TMS files to current version

Safely updates template files while preserving customizations.

View migrate documentation

prompt

Access AI prompt templates

Provides quick access to project-aware AI prompts with clipboard integration.

View prompt documentation

tutorial

Interactive walkthrough

Teaches the “Cortex Way” through an interactive onboarding tutorial.

View tutorial documentation

auto-tier

Automatic tier assignment

Uses git history to assign HOT/WARM/COLD tiers based on file recency.

View auto-tier documentation

review

Guardian: Pattern validation

AI-powered code review against project patterns and domain logic.

View review documentation

dashboard

Interactive terminal dashboard

Real-time governance health UI with tab navigation — file tiers, staleness, sprint progress, and validation in one view.

View dashboard documentation

hooks

Manage git hooks

Install pre-commit hooks for automatic documentation validation before every commit.

View hooks documentation

---

Global Options

All commands support these global options:

Option	Description
-h, --help	Show help for the command
-V, --version	Show CLI version

---

Command Summary

Command	Purpose	Common Usage
init	Initialize TMS in project	cortex-tms init
validate	Check project health	cortex-tms validate --strict
status	Text health summary	cortex-tms status
dashboard	Interactive terminal UI	cortex-tms dashboard --live
auto-tier	Auto-assign tiers via git history	cortex-tms auto-tier --dry-run
migrate	Upgrade templates	cortex-tms migrate --apply
prompt	Get AI prompts	cortex-tms prompt init-session
review	Validate code against patterns	cortex-tms review src/file.ts
tutorial	Learn Cortex TMS	cortex-tms tutorial
hooks	Git hook management (v4.1+)	cortex-tms hooks install

---

Exit Codes

All commands follow standard Unix exit code conventions:

Code	Meaning
0	Success - command completed without errors
1	Failure - command encountered errors

CI/CD Integration

Exit codes are especially useful in CI/CD pipelines:

- name: Validate Documentation
  run: cortex-tms validate --strict
  # Fails the build if exit code is 1

---

Common Workflows

Initial Setup

# 1. Initialize project
cortex-tms init

# 2. Verify setup
cortex-tms validate

# 3. Check status
cortex-tms status

Daily Development

# 1. Get AI session prompt
cortex-tms prompt init-session

# 2. Work on tasks in NEXT-TASKS.md

# 3. Validate before committing
cortex-tms validate --strict

Template Upgrades

# 1. Check for updates
cortex-tms migrate

# 2. Apply upgrades
cortex-tms migrate --apply

# 3. Verify changes
cortex-tms validate

---

Environment Variables

Cortex TMS CLI respects these environment variables:

Variable	Description	Default
NO_COLOR	Disable colored output	Not set
CI	Indicates CI/CD environment	Not set

Note

When CI=true, the CLI automatically disables interactive prompts and uses non-interactive mode.

---

Configuration File

The CLI uses .cortexrc in your project root for configuration:

{
  "version": "1.0.0",
  "scope": "standard",
  "projectName": "my-project",
  "metadata": {
    "createdAt": "2026-01-19T10:00:00.000Z",
    "customFiles": []
  }
}

Note

The version field is the config schema version (currently 1.0.0), not the Cortex TMS CLI version. It is used internally for future config migrations.

This file is automatically created by cortex-tms init and updated by other commands.

---

Next Steps

Explore individual command documentation:

• cortex-tms init - Detailed initialization options
• cortex-tms validate - Validation checks explained
• cortex-tms status - Dashboard components
• cortex-tms auto-tier - Git-based tier assignment
• cortex-tms migrate - Safe migration process
• cortex-tms prompt - Prompt library usage
• cortex-tms review - Guardian pattern validation
• cortex-tms tutorial - Interactive learning
• cortex-tms hooks - Git hook management

Quick Help

Run any command with --help for detailed usage:

cortex-tms init --help
cortex-tms validate --help