Creating & Editing Tasks

Creating Tasks

Basic Creation

Run the following command and enter a title to quickly create a task:

backlog task create "Task Title"

If the current terminal supports interactive TTY and no title is provided, the creation wizard starts automatically to guide you through task details.

The output of backlog task create --help and backlog task edit --help ends with a Note pointing to backlog instructions overview. The project expects every session to start from that overview—which includes the project state-machine guidance and the --plain convention for AI-readable output—so new readers who check --help directly still see this guidance.

Full-Parameter Creation

You can set all fields at creation time via command-line options:

backlog task create "Implement user login" \
  -d "Support email and password login" \
  -a "@developer" \
  -s "To Do" \
  -l "feature" \
  --priority high \
  --ac "Users can log in with email" \
  --ac "Passwords must be at least 8 characters" \
  --plan "1. Design database table 2. Implement API 3. Write tests" \
  --notes "Refer to the existing auth module" \
  --dep "back-1" \
  --ref "https://docs.example.com/auth" \
  --doc "doc-5"

Common Options

Newlines in Descriptions

--description and --desc support cross-platform consistent newline input:

# Insert a newline in the description
backlog task create "Title" --desc "First line\nSecond line"

# Editing also supports it
backlog task edit back-10 --desc "Fixes:\n1. Fix A\n2. Fix B"

• On Windows, typing \n produces a newline (the CLI internally simulates a bash double-quote escape layer and processes it uniformly)
• To input a literal \n rather than a newline, enter \\\\n on Windows and \\n on non-Windows
• This escape only handles \n (newline) and \\ (literal backslash); other sequences such as \t are preserved as-is
• --plan, --notes, and --final-summary support the same cross-platform newline escape

Avoid bash ANSI-C quoting: do not wrap multi-line values in $'...'. Bash $'...' parses \n into a real newline before the CLI sees the argument, causing the echoed command to break across lines and the CLI to receive only the first line. Use ordinary double quotes with \n escapes instead (--plan "Step 1\nStep 2"). This rule applies to --desc, --notes, --comment, --final-summary, --append-notes, --append-final-summary, and all other multi-line fields.

Viewing Tasks

Interactive TUI View

backlog task <id>

Or explicitly use the view subcommand:

backlog task view <id>

In the TUI:

• Use arrow keys or j/k to browse task details
• Press E to open the task file in the system editor (the TUI suspends and resumes after you close the editor)
• Press Escape or q to exit

Plain-Text Output

In non-interactive environments (scripts or AI sessions), use --plain for structured plain text:

backlog task <id> --plain
backlog task view <id> --plain

Stable JSON Output

Read commands support --json for structured, versioned JSON output, convenient for script parsing:

backlog task list --json
backlog task view back-10 --json
backlog task back-10 --json
backlog search "api" --json
backlog doc list --json

Output uses a unified envelope { schemaVersion: 1, kind: "..." }, with fields consistent with --plain, and includes date fields such as dueDate, plannedStart, plannedEnd, actualStart, actualEnd, plus acceptance-criteria progress acceptanceCriteriaCompleted / acceptanceCriteriaCount (0/0 for tasks with no acceptance criteria). Task list, task detail, and search results share the same JSON field set. --json writes only to stdout; errors go to stderr; it is mutually exclusive with --plain, and specifying both errors with a non-zero exit code.

The JSON payload also includes:

• isReady: dependency readiness determination for the task; consistent with the --ready filter projection; task view --json additionally provides a readiness block (isReady / isBlocked / blockingDependencies / missingDependencies)
• references / modifiedFiles: the task's references and modified-files lists (empty arrays when none), carried consistently across list, search, and detail payloads
• source: defaults to null; rows from the completed corpus when expanded via --completed are marked "completed"

Continuous Watch (--json --watch)

task list --json --watch enters watch mode: it listens for task-directory changes and emits a complete JSON replacement frame on each change that is byte-for-byte consistent with a one-time --json run; it does not repeat output when nothing changes:

# Watch a single assignee's todo queue with jq
backlog task list -a "@alice" -s "To Do" --json --watch | jq --unbuffered '.tasks | length'

• Options, filters, and sorting are re-evaluated on each read, so they do not drift from a one-time command
• Exit via SIGINT / SIGTERM or by closing the pipe; suitable for script subscriptions and dashboard pipelines
• Stops when the initiator exits: when the upstream program driving the watch (e.g., a script or IDE plugin) exits without stopping the watch, the watcher detects the initiator process disappearance and ends itself, avoiding orphan processes on quiet repositories
• Low CPU at idle: when nothing happens, the per-second reconcile tick performs only a cheap file stat signature comparison (name + size + mtime + ctime, one level deep); if the signature is unchanged, it does not re-read. Idle CPU for large repositories drops from ~35% to below 1%, with unchanged output bytes and update latency

Editing Tasks

Basic Edit

backlog task edit <id> --title "New Title" --status "In Progress"

If no edit fields are provided and the terminal supports interactive TTY, the edit wizard starts.

Multi-ID Batch Edit

task edit accepts multiple task IDs for batch application of shared flags:

# Move multiple tasks to the same status at once
backlog task edit back-1 back-2 back-3 -s "In Progress"

# Batch append a label
backlog task edit back-1 back-2 --add-label sprint-3

Rules:

• Batch-applicable flags: -s/--status, -a/--assignee, -l/--label, --add-label, --remove-label, --priority, -m/--milestone, --clear-milestone, --add-doc, --add-ref, and other shared fields
• Per-task fields (--title, --desc, --plan, --notes, --comment, --ordinal, AC/DoD items, date clears, etc.) are rejected in multi-ID calls
• A single task failure does not abort the batch; the command reports each failure at the end
• A multi-ID call with no batch-applicable flags errors rather than opening the edit wizard

Correspondingly, the server provides a POST /api/tasks/move batch-move endpoint; multi-select drag-and-drop in the Web board submits through it in one request (see the multi-select section in Board View).

Common Edit Options

Acceptance Criteria Examples

# Add a new acceptance criterion
backlog task edit back-10 --ac "New acceptance item"

# Delete the 2nd acceptance criterion
backlog task edit back-10 --remove-ac 2

# Check the 1st acceptance criterion
backlog task edit back-10 --check-ac 1

# Uncheck it
backlog task edit back-10 --uncheck-ac 1

# Atomically clear all acceptance criteria, then re-add (clear-then-add workflow)
backlog task edit back-10 --clear-ac --ac "Brand new acceptance criteria"

--clear-ac clears all acceptance criteria at once and rejects combinations with other AC change options (--ac, --remove-ac, etc.). AC and DoD editing and serialization are deterministic; repeated edits do not produce redundant or malformed checklists.

Append-Plan Example

# Append content to the existing plan
backlog task edit back-10 --append-plan "Add integration test cases"

# Replace plan first, then append multiple items
backlog task edit back-10 --plan "New plan" --append-plan "Step 1" --append-plan "Step 2"

Each append is separated from existing content by a blank line; multiple --append-plan flags are applied in command-line order. Purely whitespace values are ignored. When the implementation-plan section does not exist, the first non-empty append automatically creates it.

Notes and Summary Examples

# Append notes
backlog task edit back-10 --append-notes "New note content"

# Set final summary
backlog task edit back-10 --final-summary "Task completed, implemented..."

# Append to final summary
backlog task edit back-10 --append-final-summary "Additional note"

# Clear final summary
backlog task edit back-10 --clear-final-summary

Comment Examples

# Append a comment
backlog task edit back-10 --comment "Consider splitting the UI part into a separate PR"

# Append a comment with explicit author
backlog task edit back-10 --comment "Consider splitting the UI part into a separate PR" --comment-author @sara

# Append multiple comments at once
backlog task edit back-10 --comment "First comment" --comment "Second comment"

Comment bodies support Markdown, but a standalone --- line is reserved as a comment separator and cannot appear in the body. Comments appear in the task detail Comments section, listed in append order with index, author (if provided), and timestamp.

Differences between comments, implementation notes, and final summary:

List Fields: Set / Add / Remove / Clear

List fields such as --ref, --doc, and --dep support four semantics, mutually exclusive within a single command:

# Overwrite dependencies
backlog task edit back-10 --dep "back-3,back-4"

# Append a dependency while keeping existing ones
backlog task edit back-10 --add-dep back-5

# Remove a dependency by value
backlog task edit back-10 --remove-dep back-4

# Clear all dependencies
backlog task edit back-10 --clear-deps

Rules:

• Set and add cannot be mixed (--ref and --add-ref are mutually exclusive), and clear cannot be combined with set/add/remove of the same kind; violations fail the command and leave the task file unchanged
• Remove flags can be repeated or comma-separated; empty values are rejected
• Empty set values are rejected: backlog task edit back-10 --dep "" errors and suggests using --clear-deps (older versions silently no-op'd with exit 0, which was a false success)
• MCP task_edit semantics are consistent: empty-string elements in arrays are rejected; only an explicit empty array [] means clear

Three Forms of Reference Entries

Each entry for --ref / --add-ref is one location and supports three forms:

• One entry carries one location; to reference two regions of the same file, use two entries
• --remove-ref matches the stored full string, including the line-number suffix
• In the Web UI, clicking a link with a line-number suffix opens the preview box at the specified line range

Comment Deletion

# Delete the 2nd comment
backlog task edit back-10 --remove-comment 2

# Delete multiple at once (list-edit flags support comma separation)
backlog task edit back-10 --remove-comment 2,3

# Clear all comments
backlog task edit back-10 --clear-comments

--remove-comment accepts 1-based indices; out-of-bounds errors with the available indices listed. --clear-comments cannot be used with --comment. After deletion, remaining comments are renumbered by position (the index itself is not persistent). CLI, MCP task_edit, the Web UI comment per-comment delete button, and the "Clear comments" button all behave consistently.

Concurrent Edit Protection

Task read-modify-write is protected by file locks to prevent two processes from silently overwriting each other's edits. On contention it fails immediately:

Edit failed: back-10 is being modified by another process; retry if appropriate.

It is fail-fast: no waiting, no merging, no automatic retry; the failing side must retry itself. The lock is based on the task file itself and works across independent backlog processes, not just within a single process. Locks also cover the draft demotion path.

Task List and Filtering

# List all tasks
backlog task list

# Filter by status
backlog task list -s "In Progress"

# Multi-status filter (repeat or comma-separated)
backlog task list -s "To Do" -s "In Progress"

# Exclude a status
backlog task list --exclude-status "Done"

# Show only unassigned tasks (mutually exclusive with --assignee)
backlog task list --unassigned

# Filter by assignee
backlog task list -a "@developer"

# Filter by milestone
backlog task list -m "M1 - CLI"

# Filter by priority
backlog task list --priority high

# View subtasks of a specific parent task
backlog task list -p back-4

# Sort by field (priority or id)
backlog task list --sort priority

# Only list tasks whose dependencies are ready to start
backlog task list --ready

# Expand corpus: also list historical tasks from completed directory
backlog task list --completed

# Plain-text output
backlog task list --plain

--completed expands the read scope from active tasks to the backlog/completed/ corpus; JSON rows are marked with source: "completed". backlog search --completed and MCP list_tasks / search_tasks with completed: true have the same semantics. Note: MCP task_search now defaults to searching only active tasks; pass completed: true explicitly to include historical tasks.

Plain-text list rows append (ac: checked/total) when a task has acceptance criteria; MCP plain-text lists do the same. Tasks without acceptance criteria do not show this suffix.

List Paging

task list, search, draft list, milestone list, doc list, doc search, decision list, and memo list all support grep-style paging window options:

The window is applied after filtering, sorting, and --limit, in output order, so consecutive pages neither overlap nor miss items. Truncated text output ends with Showing <first>-<last> of <total> items. Next: backlog task list --skip <n>; copy that command to page forward. --count outputs only a number and cannot be combined with --json (returns non-zero); JSON envelopes include total / nextSkip only when the window truncates the list. Centralized paging semantics are described in the "List Paging" section of Search & Sequences.

Dependency-Ready Filter (--ready)

backlog task list --ready keeps only tasks that can start immediately:

• Determination is fail-closed: if any dependency is incomplete or unresolvable, the task is considered blocked
• Completed tasks count as "completion evidence" regardless of their status string (based on presence in the completed corpus)
• Dependency identity is matched by normalized ID (prefix and zero-padding differences do not affect determination)
• Circular dependencies and ambiguous dependency data are marked as blocked rather than guessed
• The same determination appears in CLI (--ready, plain/json/interactive output), the TUI task detail panel Readiness row, the Web task detail Dependencies card status badge, and MCP task_list's ready: true parameter
• This filter only marks and filters; it does not modify tasks or override ordinal-sort authority

Completing and Archiving Tasks

The first step to complete a task is to change its status to a terminal status (usually Done):

backlog task edit <id> --status "Done"

After reaching a terminal status, if you want to remove the task from the active board, run the complete subcommand to move the task file into backlog/completed/:

backlog task complete <id>

task complete is a cleanup operation: the task must be in a terminal status, otherwise the command errors and prompts you to first advance status with backlog task edit <id> -s "<terminal-status>". On success, the task disappears from the active board, the file moves to the completed directory, and the output shows Completed task <id>. with the new file path. The corresponding MCP tool is task_complete (parameter id), with the same semantics, and it does not allow completing tasks from other branches.

Archiving moves the file to backlog/archive/tasks/, which is a soft delete; the original ID can be reused by later new tasks:

backlog task archive <id>

To periodically remove completed tasks from the active list, run the cleanup command:

backlog cleanup

Date Fields

When creating or editing tasks, manage date fields with these options:

# Planning fields (date-only)
backlog task create "API docs" --due-date 2026-06-01 --planned-start 2026-05-25 --planned-end 2026-05-30

# Actual fields (datetime)
backlog task create "Urgent fix" --status "In Progress" --actual-start "2026-05-29 10:00"
backlog task edit back-10 --actual-end "2026-05-30 18:00" --clear-actual-start

• Planning fields use YYYY-MM-DD (date-only)
• Actual fields use YYYY-MM-DD HH:MM (UTC datetime)
• In interactive TTY environments, the create/edit wizard prompts for dates

Date Editing in Web UI

In the task detail modal sidebar:

• Due Date / Planned Start / Planned End — date input
• Actual Start / Actual End — datetime-local input (supports UTC ↔ local timezone conversion)

Auto-fill rules: when Due Date is set and Planned Start is empty, the system auto-fills Planned Start with the current date and Planned End with the Due Date value. You can modify these auto-filled values before saving.

Actual-time auto-fill: when task status is changed to In Progress or Done in the Web UI, the system auto-fills the corresponding actual field (if empty).

Date clearing: clicking the Clear button on any date input and saving the task removes the corresponding date field from the file. Clearing is transmitted via an empty string so the server receives the deletion correctly.

Creating Tasks in Web UI

Click the "New Task" button in the Web board or task list to open the creation modal:

• References / Documentation: in creation mode, you can add reference links or associated documents via path autocomplete; typing .back discovers the .backlog directory
• After saving, references and documentation are written to the task file

Demoting to Draft

If a task needs more refinement before execution, demote it to a draft:

backlog task demote <id>

After demotion, the task moves to backlog/drafts/ and receives an independent draft ID (e.g., draft-3). References to the original ID from other tasks are automatically cleaned up (see Archiving & Cleanup).

The Web UI demotion operation has accidental-trigger protection: all editing, status changes, and shortcuts are locked during demotion; on network errors it clearly warns "demotion may have succeeded" and refreshes the view for verification, avoiding duplicate submissions.

Label Input (Web UI)

When editing labels in the Web task detail modal, the label input supports smart autocomplete:

• Dropdown hints: clicking the label input or typing displays a dropdown of all existing project labels (configured labels plus labels used in any task)
• Fuzzy search: typing matches characters in order, e.g. we matches web-ui
• Keyboard selection: use ↑ / ↓ to highlight options and Enter to select; press Escape to close the dropdown
• Create new label: when the input matches no existing label, press Enter or type a comma , to create a new label
• Duplicate detection: trying to add an item that differs only in case from an existing label (e.g. Feature when feature exists) turns the input border red and the dropdown shows feature already added

Opening Tasks in an Editor

Editing in TUI

In the TUI (backlog task <id> or backlog board):

• Select the target task
• Press E (or Shift+e) to open the task file directly in the system editor
• After closing the editor, the TUI automatically resumes and reloads the latest content

Manual Editing

Task files are ordinary Markdown and can be modified with any editor:

vim backlog/tasks/back-10.md

After manual editing, Backlog.md's file watcher automatically refreshes the index without restarting the service.