@tasks-md/cli

A unified CLI for TASKS.md task queue management — pick tasks, lint files, sync from issue trackers, and monitor queue health.

Install

npm install -g @tasks-md/cli

Or run directly with npx:

npx @tasks-md/cli pick

Commands

tasks pick

Pick the highest-priority unblocked, unclaimed task. Uses a deterministic algorithm: walks P0→P3, skips blocked/claimed tasks, scores by unblocking impact.

tasks pick                    # pick best task
tasks pick --tags backend     # prefer tasks tagged "backend"

tasks lint

Validate TASKS.md files against the spec — checks structure, priority ordering, ID format, duplicate IDs, and dangling blocker references.

tasks lint TASKS.md                    # lint one file
tasks lint TASKS.md examples/          # lint multiple paths
tasks lint --fix TASKS.md              # auto-fix (removes completed tasks)

tasks stats

Show queue overview and throughput metrics.

tasks stats

📋 Queue Overview

  P0   P1   P2   P3   Total
  1    2    5    1    9

  Blocked: 2
  Claimed: 1
  Available: 6
  Files: 1

📊 Throughput

  Completed (all time):  42
  Completed (this month): 8
  Completed (this week):  3

tasks diff

Show queue changes since a git reference.

tasks diff              # changes since HEAD
tasks diff HEAD~5       # changes in the last 5 commits

tasks init

Initialize a TASKS.md file in the current repo.

tasks init

tasks install

Install the /next-task command for detected agents (Claude Code, Cursor, Windsurf, etc.).

tasks install
tasks install --all       # install for all agents, even if directories don't exist
tasks install --hooks     # also install pre-commit hook for TASKS.md validation

tasks watch

Watch TASKS.md files for changes and auto-lint on save.

tasks watch               # watch current directory
tasks watch ./packages    # watch a specific directory

tasks generate-commands

Regenerate agent-specific command files from the canonical source (commands/next-task.md). Used after editing the canonical command to propagate changes to all agent variants.

tasks generate-commands

tasks sync-issues

Sync GitHub Issues into TASKS.md. Requires the gh CLI to be authenticated (gh auth login).

tasks sync-issues                              # sync from current repo
tasks sync-issues --repo owner/repo            # specify repo
tasks sync-issues --label bug --merge          # filter + merge into existing file
tasks sync-issues --output TASKS.md --merge    # write to file, preserving manual tasks

Priority mapping — GitHub labels map to TASKS.md priorities. The highest-priority (lowest number) label wins when multiple are present:

| GitHub Label | Priority | |-------------|----------| | critical, p0 | P0 | | high, p1 | P1 | | medium, p2 | P2 (default) | | low, p3 | P3 |

Tag extraction — Labels that aren't the filter label (default: tasks.md) and aren't priority labels become tags. For example, an issue with labels tasks.md, p1, frontend, api produces tags frontend, api.

ID format — Each synced issue gets an ID like issue-42 (the issue- prefix plus the GitHub issue number).

tasks sync-jira

Sync Jira issues into TASKS.md. Requires JIRA_URL and JIRA_TOKEN environment variables. Set JIRA_AUTH=bearer for Bearer token auth (default is Basic).

tasks sync-jira --project PROJ                 # sync a project
tasks sync-jira --jql "assignee = currentUser()" --merge
tasks sync-jira --output TASKS.md --merge
tasks sync-jira --max 50                       # limit results

Priority mapping — Jira priority names map to TASKS.md priorities:

| Jira Priority | Priority | |--------------|----------| | Highest, Blocker, Critical | P0 | | High | P1 | | Medium | P2 (default) | | Low, Lowest | P3 |

Tag extraction — Jira issue labels are lowercased and used as tags.

ID format — Each synced issue gets an ID like jira-PROJ-42.

tasks sync-linear

Sync Linear issues into TASKS.md. Requires LINEAR_API_KEY environment variable.

tasks sync-linear --team ENG                   # sync a team's issues
tasks sync-linear --team ENG --project "Q1"    # filter by project
tasks sync-linear --filter '{"assignee":{"id":{"eq":"me"}}}'  # custom filter
tasks sync-linear --output TASKS.md --merge
tasks sync-linear --max 50                     # limit results

Priority mapping — Linear numeric priorities map to TASKS.md priorities:

| Linear Priority | Priority | |----------------|----------| | 1 (Urgent) | P0 | | 2 (High) | P1 | | 3 (Medium) | P2 | | 4 (Low), 0 (No priority) | P3 |

Tag extraction — Linear label names are lowercased with spaces replaced by hyphens (e.g., "Bug Fix" becomes bug-fix).

ID format — Each synced issue gets an ID like linear-ENG-42.

Merge behavior

When using --merge, sync preserves manual tasks you've added by hand. It:

1. Removes all previously synced tasks (matched by ID prefix, e.g., issue-, jira-, linear-)
2. Inserts the current set of open issues under the correct priority headings
3. Leaves all other tasks untouched

This means closed issues are automatically removed on the next sync, and new issues appear in the right priority section.

Programmatic Usage

The CLI also exports its core functions as a library:

import { loadAllTasks, pickBestTask, getQueueStats, getQueueDiff } from "@tasks-md/cli";

const tasks = loadAllTasks(process.cwd());
const best = pickBestTask(tasks);
const stats = getQueueStats(process.cwd());

License

MIT