CLI-INSTRUCTIONS.md

CLI Reference

Full command reference for Backlog.md. For getting started, see README.md.

All examples use the backlog command, available after installing the backlog.md package globally (npm i -g backlog.md) or as a project dependency. For one-off runs without installing, use the full package name — npx backlog.md <command>, e.g. npx backlog.md board; without an install, npx backlog resolves to an unrelated third-party npm package, not this tool.

Project Setup

Action	Example
Initialize project	backlog init [project-name] (creates backlog structure with a minimal interactive flow)
Re-initialize	backlog init (preserves existing config, allows updates)
Advanced settings wizard	backlog config (no args) — launches the full interactive configuration flow

backlog init keeps first-run setup focused on the essentials:

• Project name – identifier for your backlog (defaults to the current directory on re-run).
• Backlog folder – choose backlog/, .backlog/, or a custom project-relative path.
• Config location – for built-in folders, choose folder-local config.yml or root backlog.config.yml; custom paths use root backlog.config.yml.
• Integration choice – decide whether your AI tools use CLI instructions (recommended), the optional MCP connector, or no AI setup.
• Instruction files (CLI path) – the CLI setup writes a short nudge to AGENTS.md by default in non-interactive setup. --agent-instructions cursor also selects AGENTS.md, and the interactive CLI and Web setup identify Cursor under that shared target. Existing user-managed .cursor/rules files may coexist; Backlog.md does not migrate or remove them, and repeated initialization preserves non-Backlog content in AGENTS.md.
• Advanced settings prompt – default answer "No" finishes init immediately; choosing "Yes" jumps straight into the advanced wizard documented in ADVANCED-CONFIG.md.

The advanced wizard includes interactive Definition of Done defaults editing (add/remove/reorder/clear), so project checklist defaults can be managed without manual YAML edits.

You can rerun the wizard anytime with backlog config. All existing CLI flags (for example --defaults, --agent-instructions) continue to provide fully non-interactive setups, and init also supports --backlog-dir <path> plus --config-location <folder|root> for scripted configuration.

Humans and agents can run backlog instructions for workflow guides and backlog instructions overview for the overview.

Documentation

• Document IDs are global across all subdirectories under backlog/docs. You can organize files in nested folders (e.g., backlog/docs/guides/), and backlog doc list and backlog doc view <id> work across the entire tree.
• Use backlog doc create "New Guide" -p guides to create a document in a docs subdirectory. The created output includes the persisted docs-relative file path, such as backlog/docs/guides/doc-1 - New-Guide.md.
• Use backlog doc update doc-1 --content "Updated markdown" to update document content. Add --title, -t/--type, --tags, or -p/--path to update metadata or move the document while preserving omitted fields.
• Use backlog doc search "query" for scoped document search with plain text output that includes document IDs and follow-up backlog doc view <docId> commands. Use --limit <number> to cap results.
• Document paths are always relative to the docs directory. Absolute paths and traversal segments such as .. are rejected.

Task Management

Action	Example
Create task	backlog task create "Add OAuth System"
Create with description	backlog task create "Feature" -d "Add authentication system"
Create with assignee	backlog task create "Feature" -a @sara
Create with status	backlog task create "Feature" -s "In Progress"
Create with labels	backlog task create "Feature" -l auth,backend
Create with priority	backlog task create "Feature" --priority high
Create with due date	backlog task create "Feature" --due-date 2026-08-10
Create with plan	backlog task create "Feature" --plan "1. Research\n2. Implement"
Create with AC	backlog task create "Feature" --ac "Must work,Must be tested"
Add DoD items on create	backlog task create "Feature" --dod "Run tests"
Create without DoD defaults	backlog task create "Feature" --no-dod-defaults
Create with notes	backlog task create "Feature" --notes "Started initial research"
Create with final summary	backlog task create "Feature" --final-summary "Completion summary"
Create with deps	backlog task create "Feature" --dep task-1,task-2
Create with refs	backlog task create "Feature" --ref https://docs.example.com --ref src/api.ts
Create with docs	backlog task create "Feature" --doc https://design-docs.example.com --doc docs/spec.md
Create sub task	backlog task create -p 14 "Add Login with Google"
Create (all options)	backlog task create "Feature" -d "Description" -a @sara -s "To Do" -l auth --priority high --ac "Must work" --notes "Initial setup done" --dep task-1 --ref src/api.ts --doc docs/spec.md -p 14
List tasks	backlog task list [-s <status>] [-a <assignee>] [-p <parent>] [--labels <labels>] [--search <query>] [--limit <n>]
List filtered	backlog task list --labels frontend,bug --search "login" --limit 10 --plain
List in windows	backlog task list --max-count 20 --skip 20 --plain
Count tasks	backlog task list --status "To Do" --count
List as JSON	backlog task list --status "To Do" --json
Watch as JSON	backlog task list --json --watch
List by parent	backlog task list --parent 42 or backlog task list -p task-42
View detail	backlog task 7 (interactive UI, press 'E' to edit in editor)
View (AI mode)	backlog task 7 --plain
View as JSON	backlog task 7 --json
Edit	backlog task edit 7 -a @sara -l auth,backend
Add plan	backlog task edit 7 --plan "Implementation approach"
Add AC	backlog task edit 7 --ac "New criterion" --ac "Another one"
Add DoD	backlog task edit 7 --dod "Ship notes"
Remove AC	backlog task edit 7 --remove-ac 2 (removes AC #2)
Remove multiple ACs	backlog task edit 7 --remove-ac 2 --remove-ac 4 (removes AC #2 and #4)
Check AC	backlog task edit 7 --check-ac 1 (marks AC #1 as done)
Check DoD	backlog task edit 7 --check-dod 1 (marks DoD #1 as done)
Check multiple ACs	backlog task edit 7 --check-ac 1 --check-ac 3 (marks AC #1 and #3 as done)
Uncheck AC	backlog task edit 7 --uncheck-ac 3 (marks AC #3 as not done)
Uncheck DoD	backlog task edit 7 --uncheck-dod 3 (marks DoD #3 as not done)
Mixed AC operations	backlog task edit 7 --check-ac 1 --uncheck-ac 2 --remove-ac 4
Mixed DoD operations	backlog task edit 7 --check-dod 1 --uncheck-dod 2 --remove-dod 4
Add notes	backlog task edit 7 --notes "Completed X, working on Y" (replaces existing)
Append notes	backlog task edit 7 --append-notes "New findings"
Add comment	backlog task edit 7 --comment "Question for review" --comment-author @sara
Add final summary	backlog task edit 7 --final-summary "Completion summary"
Append final summary	backlog task edit 7 --append-final-summary "More details"
Clear final summary	backlog task edit 7 --clear-final-summary
Add deps	backlog task edit 7 --dep task-1 --dep task-2
Set due date	backlog task edit 7 --due-date 2026-08-10
Clear due date	backlog task edit 7 --clear-due-date
Complete	backlog task complete 7 (move finished work to completed storage)
Archive	backlog task archive 7 (canceled, duplicate, or invalid work)

Mark finished work Done (or the configured final status). During periodic cleanup, use Complete to move it off the board while preserving its record and dependency links. Archive removes incoming dependencies and task references.

Task list order

Without --sort, task list orders tasks by ordinal, then priority, then ID: tasks that have an ordinal come first, lowest ordinal first, and priorities rank in the configured order. --sort priority, --sort id, and --sort ordinal order by that field and then by ID. Plain output groups the ordered tasks by status in the configured status order, except that --sort priority prints one flat list; --json returns the ordered tasks as one flat array. The interactive list shows the same tasks in the same order and status groups as --plain for the same options, and MCP task_list, which has no sort option, uses the order without --sort.

Paging long lists

task list, search, draft list, milestone list, doc list, doc search, and decision list print every match by default. --max-count <n> prints at most n items and --skip <n> leaves out the first n, as in git log. Both apply after filtering, sorting, and --limit. task list takes the window from the sorted list, so --plain and --json select the same tasks; plain output then groups only those tasks by status, as it does for --limit, unless --sort priority prints one flat list. The other lists take the window in the order their output prints: plain search prints tasks, then documents, then decisions, and milestone list prints active milestones before completed ones. Each list has a stable order: tasks, drafts, and decisions break ties by ID, documents sort by title and then path, search results by score and then corpus order, and milestones follow their files and then the tasks that name them. So consecutive windows of an unchanged backlog neither overlap nor leave items out. With --json, search windows its results in relevance order, so read all windows of a search in one output mode. The options print text instead of opening an interactive view.

Output cut by a window ends with the shown range, the total, and the command that prints the following items:

Showing 21-40 of 57 items. Next: backlog task list --status 'To Do' --max-count 20 --skip 40

The last window has no Next: part, and a --skip past the end prints only Showing 0 of 57 items. Output that is not cut has no footer. --count prints only the number of items the same command would list, as grep --count does; it cannot be combined with --json. There are no short forms because -m already means --milestone. --limit keeps its behavior: it silently shortens the list before any window applies.

Task comments are append-only discussion entries with optional author labels. Use comments for review questions and collaboration notes; use implementation notes for execution progress and final summary for PR-ready completion notes. Comment bodies may contain Markdown, but standalone --- lines are reserved as comment delimiters.

Task and milestone due dates are calendar days stored as YYYY-MM-DD. Use a plain date such as 2026-08-10; a due date carries no time and no timezone.

Stable JSON output

Use --json when a script or integration needs structured output:

backlog task list --status "To Do" --json | jq '.tasks[] | .id'
backlog task view BACK-7 --json | jq '.task.acceptanceCriteria'
backlog task BACK-7 --json
backlog search "authentication" --json | jq '.results[] | [.type, .data.id]'

Use backlog task list --json --watch to receive the full matching list immediately, then a full replacement whenever its JSON result changes. Every response uses exactly the same fields, envelope, indentation, and trailing newline as task list --json. Read successive complete JSON values, not individual lines or the whole stream as one document. For example:

backlog task list --json --watch | jq --unbuffered -c '.tasks'

Each response replaces the subscriber's previous list, including an empty tasks array. Filters, sorting, limits, and local editable task scope are unchanged; completed storage, archives, drafts, and other branches are not added to the list. Dependency and configuration changes can update derived fields or which tasks match. Unchanged results are suppressed, and rapid edits or slow consumers may coalesce intermediate states. The command reconciles periodically as well as on file notifications; this is a current-state subscription, not an edit history. Restart it to receive a fresh full list.

--watch requires --json and cannot be combined with --plain. Stop it with Ctrl+C or terminate the process; closing the output pipe also stops it. It also ends when the process that started it ends. A failure after earlier responses writes a diagnostic to stderr and exits nonzero without emitting a replacement for that failed read.

Each successful response is one pretty-printed JSON document followed by a newline. The top-level contract is versioned and identifies the command result:

Command	Envelope
task list --json	{ "schemaVersion": 1, "kind": "task-list", "tasks": [...] }
task view <id> --json and task <id> --json	{ "schemaVersion": 1, "kind": "task-view", "task": {...} }
search [query] --json	{ "schemaVersion": 1, "kind": "search", "results": [...] }

Task list and task search results use these compact fields: id, title, status, type, priority, project, assignees, reporter, labels, milestone, parentTaskId, acceptanceCriteriaCompleted, acceptanceCriteriaCount, references, modifiedFiles, ordinal, createdAt, updatedAt, dueDate, and isReady. acceptanceCriteriaCompleted is the number of checked acceptance criteria and acceptanceCriteriaCount is the total; both are 0 when the task has no acceptance criteria. project reports the task's project: frontmatter and is null when the task has none. Setting or filtering by it requires a projects: list in the project config. isReady is derived from the whole visible corpus at read time and never stored: it is true when the task is unfinished and every dependency it names resolved to a completed task, and false for a finished task or one whose dependencies are unfinished, unknown, or ambiguous. It is the same verdict task list --ready filters on.

Task view includes the same progress counts alongside the full checklist and adds path, description, dependencies, dependencyGraph, readiness, references, documentation, modifiedFiles, subtasks, acceptanceCriteria, definitionOfDone, implementationPlan, implementationNotes, comments, and finalSummary. path is relative to the project root. Checklist entries contain index, text, and checked. Comment entries contain index, body, createdAt, and author.

Task view also carries dependencyGraph, a property of the task detail that is derived from the whole visible corpus at read time and never stored in the Markdown file. task.dependencies stays the task's own list of direct dependency IDs, unchanged. task.dependencyGraph contains root (the selected task's ID), nodes, and edges. Each edge is { "from": ..., "to": ... } and always points from the task that declares the dependency to the task it depends on, so to blocks from. Each node contains id, title, status, state, completed, dependencyDepth, and dependentDepth. The two depths are the shortest hop counts from the root: 0 is the root itself, 1 is a direct relationship, anything higher is transitive, and null means the node is not reachable in that direction. Nodes are listed root first and then by task ID, edges by from and then to. See "Dependency Management" for what the graph covers and how it reports identities it cannot resolve.

readiness explains the isReady field above it and comes from the same derivation. It contains isReady, isBlocked, blockingDependencies (dependencies that resolved to unfinished tasks), and missingDependencies (dependency IDs no single visible task claims). Both lists fail closed: an unknown or ambiguous dependency blocks instead of being treated as satisfied.

Search keeps relevance order and discriminates every result with type and data. Task data uses the compact task fields. Document data contains id, title, type, path, tags, createdAt, and updatedAt. Decision data contains id, title, status, and date. Search scores are not part of the version 1 public contract.

When --max-count or --skip cuts a task list, search, or decision list result, the envelope also contains total, the number of items before the window, and nextSkip, the --skip value for the following items or null when none follow. Output that is not cut has neither field.

Absent scalar fields are null, and absent collections are []. Date-only values remain YYYY-MM-DD; UTC date-times use RFC 3339. Internal fields, absolute paths, raw Markdown source objects, branch metadata, and search implementation details are not exposed.

--json and --plain are mutually exclusive. Explicit JSON mode is always noninteractive, including in a terminal. Without --json, existing interactive, explicit plain, and automatic non-TTY plain behavior is unchanged. One-shot errors leave stdout empty, write a concise message to stderr, and exit nonzero. Version 1 may gain backward-compatible fields, but removing, renaming, retyping, or changing documented field semantics requires a new schemaVersion.

Multi-line input (description/plan/notes/comments/final summary)

The CLI preserves input literally — \n sequences are not auto-converted. Use one of the following forms (recommended order for AI agents):

1. Repeat --append-* for each line (works in every shell, including Claude Code / Codex / agent sandboxes):

backlog task edit 7 --notes "First line"
backlog task edit 7 --append-notes "Second line"
backlog task edit 7 --append-notes "Third line"

2. Real newlines inside double quotes (single command):

backlog task create "Feature" --desc "Line1
Line2

Final paragraph"

The same shape works for --plan, --notes, --comment, --final-summary, and the --append-* variants.

3. Shell-specific shorthand (interactive shells only — rejected by tree-sitter-based agent sandboxes, see #595):

• Bash/Zsh (ANSI-C quoting)

  backlog task edit 7 --notes $'Line1\nLine2'

• POSIX sh (printf substitution)

  backlog task create "Feature" --desc "$(printf 'Line1\nLine2\n\nFinal paragraph')"

• PowerShell (backtick-n)

  backlog task create "Feature" --desc "Line1`nLine2`n`nFinal paragraph"

Literal backticks in task text

When task text includes Markdown code spans, quote it so the shell passes the backticks literally. Unescaped backticks in double-quoted or unquoted arguments are command substitution in many shells, and Backlog.md cannot recover the original text after the shell has already executed it.

Use single-quoted CLI arguments for values that contain literal backticks:

backlog task create 'Document `backlog init` setup' \
  --ac 'Instructions mention `backlog init --defaults` literally'

If single quotes are not practical in your shell, escape each literal backtick before running the command. Do not rely on Backlog.md to sanitize accidental command output after substitution.

Milestone Management

Milestones are managed through milestone files. Use CLI commands instead of editing milestone markdown directly so IDs, filenames, task references, and archive state stay consistent.

Action	Example
List milestones	backlog milestone list --plain
List completed milestones too	backlog milestone list --show-completed --plain
Add milestone	backlog milestone add "Release 1.0"
Add with description	backlog milestone add "Beta" --description "Beta scope"
Add with due date	backlog milestone add "Beta" --due-date 2026-08-10
Rename and update tasks	backlog milestone rename "Release 1.0" "Release 2.0"
Set due date without renaming	backlog milestone rename "Release 1.0" "Release 1.0" --due-date 2026-08-10
Clear due date	backlog milestone rename "Release 1.0" "Release 1.0" --clear-due-date
Rename without task updates	backlog milestone rename m-1 "Release 2.0" --no-update-tasks
Remove and clear task milestones	backlog milestone remove "Release 1.0"
Remove and keep task values	backlog milestone remove "Release 1.0" --task-handling keep
Remove and reassign tasks	backlog milestone remove "Release 1.0" --task-handling reassign --reassign-to "Release 2.0"
Archive milestone	backlog milestone archive m-1

milestone remove task handling modes are clear (default), keep, and reassign. --reassign-to is required when using --task-handling reassign, and the target must be an active milestone file.

Search

Find tasks, documents, and decisions across your entire backlog with fuzzy search:

Action	Example
Search tasks	backlog search "auth"
Filter by status	backlog search "api" --status "In Progress"
Filter by priority	backlog search "bug" --priority high
Combine filters	backlog search "web" --status "To Do" --priority medium
Plain text output	backlog search "feature" --plain (for scripts/AI)
JSON output	backlog search "feature" --json (for structured integrations)
Find by modified file	backlog search --modified-file src/path.ts --plain
Page results	backlog search "api" --max-count 20 --skip 20 --plain

Search features:

• Fuzzy matching -- finds "authentication" when searching for "auth"
• Modified-file lookup -- tasks can record project-root-relative modified files; find them later with --modified-file
• Interactive filters -- refine your search in real-time with the TUI
• Live filtering -- see results update as you type (no Enter needed)

Draft Workflow

Action	Example
Create draft	backlog task create "Feature" --draft
Draft flow	backlog draft create "Spike GraphQL" → backlog draft promote 3.1
Demote to draft	backlog task demote <id>

Dependency Management

Manage task dependencies to express execution order:

Action	Example
Add dependencies	backlog task edit 7 --dep task-1 --dep task-2
Add multiple deps	backlog task edit 7 --dep task-1,task-5,task-9
Create with deps	backlog task create "Feature" --dep task-1,task-2
View dependencies	backlog task 7 (shows dependencies in task view)
Validate dependencies	Use task commands to automatically validate dependencies

Dependency Features:

• Automatic validation: verifies that referenced dependency tasks exist
• Flexible formats: Use task-1, 1, or comma-separated lists like 1,2,3
• Completion tracking: See which dependencies are blocking task progress

Dependency graph in task detail

Task detail shows the whole dependency context around the selected task, under Dependency Graph, directly above the description. It is derived and read-only, and it replaces the raw Dependencies: ID list in plain output: the graph names the same direct dependencies and resolves their titles, status, and everything behind them.

Every plain task output uses this one layout, so task create --plain, task edit --plain, task view --plain, and the MCP task results all render identically. --json is unaffected: task.dependencies remains the editable direct list alongside task.dependencyGraph.

Dependency Graph:
--------------------------------------------------
Depends on (1 direct, 2 total):
└─ BACK-2 - Parser rewrite [In Progress]
   └─ BACK-1 - Token schema [completed]

Dependents (2 direct, 2 total):
├─ BACK-8 - Migration guide [To Do]
└─ BACK-9 - Release checklist [To Do]

• Edge direction. A dependency edge points from the task that declares it to the task it depends on, so the task it points at blocks the task it comes from.
• Direct versus transitive. Depends on lists everything the selected task transitively depends on; Dependents lists everything that transitively depends on it. Nesting shows the distance: the outermost entries are direct relationships and everything indented below them is transitive. The heading counts both, as N direct, M total.
• Dependents. "Dependents" means the tasks this one blocks. It is the reverse of the task's own dependency list, and nothing on it is editable from here; change it on the task that declares it.
• Visibility. The graph resolves against exactly what task detail can already see: the current checkout plus completed tasks for the CLI, TUI, and MCP, and the configured cross-branch corpus in the browser. Archiving a task takes it out of every one of those, so an archived ID stops resolving instead of coming back.
• Cycles and repeats. Every task appears once. A relationship that points back into the branch above it is marked (cycle), and a task already shown elsewhere in the same section is marked (shown above) rather than being expanded again.
• Unresolved identities. unknown task ID means no visible task claims that ID. ambiguous task ID means more than one record claims it, so nothing is chosen. Neither is ever treated as satisfied, and the graph never traverses past one, so anything behind it is left out rather than reported as resolved. Diagnose and repair duplicate IDs with backlog doctor before trusting a graph that reports one.

Board Operations

Action	Example
Kanban board	backlog board (interactive UI, press 'E' to edit in editor)
Export board	backlog board export [file] (exports Kanban board to markdown)
Export with version	backlog board export --export-version "v1.0.0" (includes version in export)

Statistics & Overview

Action	Example
Project overview	backlog overview (interactive TUI showing project statistics)

Web Interface

Action	Example
Web interface	backlog browser (launches the local-machine-only web UI on 127.0.0.1:6420)
Web custom port	backlog browser --port 8080 --no-open

The Web UI listens only on 127.0.0.1; it is not reachable from other devices on the LAN or VPN.

To keep the Web UI running in the background with auto-start on boot, see Running Backlog.md as a Service.

Documentation

Action	Example
Create doc	backlog doc create "API Guidelines"
Create with path	backlog doc create "Setup Guide" -p guides/setup
Create with type	backlog doc create "Architecture" -t guide
Update content	backlog doc update doc-1 --content "Updated markdown"
Update metadata/path	backlog doc update doc-1 --title "Setup Handbook" -t guide --tags setup,runbook -p guides
List docs	backlog doc list
Search docs	backlog doc search "architecture" --limit 5
View doc	backlog doc view doc-1

Decisions

Action	Example
Create decision	backlog decision create "Use PostgreSQL for primary database"
Create with status	backlog decision create "Migrate to TypeScript" -s proposed

Agent Instructions

Action	Example
Open the local CLI documentation entry point	backlog
List workflow guides	backlog instructions
Required first read for task workflow	backlog instructions overview
Read a detailed workflow guide	backlog instructions task-execution
Update CLI agent instruction files	backlog agents --update-instructions (updates CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md)

Maintenance

Action	Example
Cleanup done tasks	backlog cleanup (move old completed tasks to completed folder to cleanup the kanban board)

Full help: backlog --help

---

Sharing & Export

Board Export

Export your Kanban board to a clean, shareable markdown file:

# Export to default Backlog.md file
backlog board export

# Export to custom file
backlog board export project-status.md

# Force overwrite existing file
backlog board export --force

# Export to README.md with board markers
backlog board export --readme

# Include a custom version string in the export
backlog board export --export-version "v1.2.3"
backlog board export --readme --export-version "Release 2024.12.1-beta"

Perfect for sharing project status, creating reports, or storing snapshots in version control.

---

Shell Tab Completion

Backlog.md can install tab completion for bash, zsh, fish, and PowerShell.

Quick Installation:

# Auto-detect and install for your current shell
backlog completion install

# Or specify shell explicitly
backlog completion install --shell bash
backlog completion install --shell zsh
backlog completion install --shell fish
backlog completion install --shell pwsh

What you get:

• Command completion: backlog <TAB> → shows all commands
• Dynamic task IDs: backlog task edit <TAB> → shows actual task IDs from your backlog
• Smart flags: --status <TAB> → shows configured status values
• Context-aware suggestions for priorities, labels, and assignees

Full documentation: See completions/README.md for detailed installation instructions, troubleshooting, and examples.