Skip to content

Usage Examples

AI Integration (MCP Server)

# Start MCP server for AI agents (backlog mcp --http transport)
backlog mcp --http  # default port 8106
backlog mcp --http --port 8106 # specify the port

# Start MCP server (stdio transport)
backlog mcp

See this repository .gemini or .claude for example configurations.

Basic Task Creation

# Simple task
backlog create "Fix the login button styling"

# Task with description
backlog create "Implement password reset" \
  -d "Users should be able to request a password reset link via email"

# Task with assignees and labels
backlog create "Update dependencies" \
  -a "alex" -a "jordan" \
  -l "maintenance,backend,security" \
  --priority "high"

Hierarchical Task Structure

# Create parent task
backlog create "Implement User Authentication"
# → Creates T01-implement_user_authentication.md

# Create subtask
backlog create "Add Google OAuth login" -p "T01"
# → Creates T01.01-add_google_oauth_login.md

# Create sub-subtask
backlog create "OAuth token validation" -p "T01.01"
# → Creates T01.01.01-oauth_token_validation.md

Advanced Task Creation

# Comprehensive task with acceptance criteria
backlog create "Build reporting feature" \
  -d "Create monthly performance reports in PDF format" \
  -a "drew" \
  -l "feature,frontend,backend" \
  --priority "high" \
  --ac "Report generation logic is accurate" \
  --ac "Users can select date range" \
  --ac "PDF export works correctly" \
  -p "23"

Task Dependencies

You can define dependencies between tasks using the --deps flag. A task cannot be started until its dependencies are complete.

# Create a task that depends on another
backlog create "Deploy to production" --deps "T10"

# Create a task with multiple dependencies
backlog create "Final release" --deps "T10,T11"

# Add a dependency to an existing task
backlog edit T12 --deps "T13"

Task Management

# List all tasks
backlog list

# Filter by status
backlog list --status "todo"
backlog list --status "in-progress"
backlog list --status "done"

# Filter by parent (show subtasks)
backlog list --parent "T01"

# Pagination for large task lists
backlog list --limit 10                         # First 10 tasks
backlog list --limit 5 --offset 10              # Tasks 11-15
backlog list --status "todo" --limit 3          # First 3 todo tasks

# Search with pagination
backlog list --query "api" --limit 5                  # First 5 API-related tasks
backlog list --query "bug" --limit 3 --offset 5       # Search results 6-8

# View specific task
backlog view T01.02

# Edit task
backlog edit T01 --status "in-progress" --assigned "alex"

Conflict Management

When working with Git branches, task ID conflicts can occur when multiple branches create tasks with the same IDs. Backlog provides automatic detection and resolution capabilities:

# Detect ID conflicts
backlog doctor                           # Text output
backlog doctor --json                    # JSON output

# Automatically fix conflicts
backlog doctor --fix                     # Fix using chronological strategy (default)
backlog doctor --fix --strategy=auto    # Fix using auto-renumber strategy
backlog doctor --fix --strategy=manual  # Create manual resolution plan
backlog doctor --fix --dry-run          # Preview changes without applying

Conflict Types Detected:

  • Duplicate IDs: Same ID appears in multiple task files
  • Orphaned Children: Tasks reference non-existent parent IDs
  • Invalid Hierarchy: Parent-child relationships don't match ID structure

Resolution Strategies:

  • Chronological: Keeps older tasks unchanged, renumbers newer conflicting tasks
  • Auto: Automatically renumbers conflicting IDs using available ID space
  • Manual: Creates a resolution plan requiring manual intervention

Git Integration:

Backlog automatically checks for conflicts during Git operations and can auto-resolve them during merges to maintain task integrity.

# Container usage for conflict management
docker run --rm -it -v $(pwd):/data -e BACKLOG_FOLDER=/data/.backlog ghcr.io/veggiemonk/backlog doctor
docker run --rm -it -v $(pwd):/data -e BACKLOG_FOLDER=/data/.backlog ghcr.io/veggiemonk/backlog doctor --fix --dry-run