CLI Reference — Backlog

On this page

Global flags
init
project
task
plan
comment
label
profile
import-findings
import
export
sync
doctor
mcp serve
web
version / completion
Workflows

Global flags

These flags work on every command:

Flag	Description
`--db <path>`	Explicit path to `backlog.db`. Overrides all other resolution.
`--profile <name>`	Use a named workspace profile.
`--json`	Output machine-readable JSON instead of tables.
`--as <kind:name>`	Actor for this operation, e.g. `human:alice`, `ai:claude-code`.
`--quiet`	Suppress non-essential output.

DB resolution order

First match wins:

--db flag
--profile flag
$BACKLOG_DB environment variable
Walk up from current directory looking for backlog.db
Default profile from ~/.config/backlog/config.toml

init

backlog init [--profile <name>] [--path <dir>]

Create a workspace. Produces backlog.db, backlog.json, and backlog.config.

--profile <name>	Register a named profile pointing to the new workspace (default: `default`)
--path <dir>	Place the workspace at this directory instead of `~/.backlog/<profile>`

backlog init                         # creates ~/.backlog/default/
backlog init --profile work          # creates ~/.backlog/work/
backlog init --path ~/projects/app   # custom path

project

backlog project add <name> --alias <alias> [flags]

Create a project. The alias is used in all other commands.

--alias <alias>	Short identifier — lowercase alphanumeric with optional hyphens (required)
--description <text>	Human-readable description
--repo-path <path>	Filesystem path to the source repository

backlog project list [--include-archived] [--json]

List all projects. Archived projects are hidden unless --include-archived is passed.

backlog project show <alias> [--json]

Show full detail for a project.

backlog project update <alias> [--name <n>] [--description <d>] [--repo-path <p>]

Update project fields. Only flags you pass are changed.

backlog project archive <alias>

Archive a project. Hidden from listings but not deleted; tasks remain queryable.

backlog project delete <alias>

Hard delete. Removes the project and all associated tasks, plans, labels, and comments. Project must be archived first.

backlog project set-default <alias>

Set a project as the default for --project when that flag is omitted.

backlog project use <alias>

Alias for set-default. Switch the active project.

backlog project current

Show the active default project.

backlog project clear-default

Remove the active default project without deleting anything.

task

backlog task add -p <alias> -t <title> [flags]

Create a new task.

-p, --project <alias>	Project alias (required, or use `project set-default`)
-t, --title <text>	Task title (required)
--description <text>	Longer description (supports markdown)
--type <type>	`task` · `bug` · `issue` · `improvement` · `feature` · `vulnerability` · `chore` · `spike`
--priority <P1-P5>	P1 (highest) through P5 (lowest). Default: P3.
--assignee <name>	Free-text, e.g. `alice`
--source <text>	Origin system, e.g. `semgrep`
--external-ref <url>	External ticket URL or ID
--label <name>	Attach a label (repeatable)
--from-file <path.json>	Load task fields from a JSON payload file
--as <kind:name>	Actor override

# Minimal
backlog task add -p api -t "Fix login timeout"

# Full
backlog task add \
  --project api \
  --title "Reject unsigned JWTs in auth middleware" \
  --description "Auth middleware does not verify signature" \
  --type vulnerability \
  --priority P1 \
  --assignee alice \
  --source "security-review-2026-Q1" \
  --external-ref https://jira.example.com/PROJ-123 \
  --label auth \
  --as human:alice

backlog task list [filters] [--limit N] [--offset N] [--json]

List tasks. Multiple filters can be combined — all must match (AND logic).

--project <alias>	Filter by project
--status <status>	`todo` · `doing` · `done`
--type <type>	Task type filter
--priority <P1-P5>	Exact priority match
--label <name>	Filter by label (repeatable — OR logic)
--actor-kind <human\|ai>	Filter by actor kind
--actor-name <name>	Filter by actor name
--source <text>	Filter by source system
--search <query>	FTS5 full-text search. Supports prefix (`sql*`) and boolean (`jwt OR csrf`).
--include-archived	Include archived tasks in results
--limit <n>	Max results per page (default 50)
--offset <n>	Skip first N results for pagination

backlog task list                                   # all open tasks
backlog task list --project api --type vulnerability
backlog task list --actor-kind ai                   # created by AI agents
backlog task list --search "injection*"             # FTS5 prefix match
backlog task list --priority P1 --json              # JSON output

backlog task show <id> [--with-plans] [--with-comments] [--json]

Show full task detail. <id> accepts TASK-N, bare integer, ULID, or 8-char prefix.

backlog task update <id> [--title <t>] [--priority <p>] [--type <type>] [--assignee <a>] [--as <actor>]

Update task fields. Only the flags you pass are changed.

backlog task move <id> --status <todo|doing|done> [--as <actor>]

Transition a task to a new status. All transitions are valid in any direction.

backlog task archive <id>

Archive a task. Hidden from list by default but never deleted.

backlog task delete <id>

Hard delete. Also removes attached plans, comments, and label associations.

plan

backlog plan add --task <id> --title <title> [--content <body>] [--from-file <path.md>] [--as <actor>]

Attach a versioned plan to a task (creates v1).

backlog plan update <plan-id> [--title <t>] [--content <body>] [--change-note <note>] [--as <actor>]

Revise a plan. Creates a new immutable version; old versions are always readable.

backlog plan list --task <id> [--json]

List all plans on a task (current version of each).

backlog plan show <plan-id> [--version <n>] [--json]

Show a plan's content. Omit --version for current. Pass --version 1 for a specific historical version.

backlog plan history <plan-id> [--json]

List all versions of a plan with version number, actor, change note, and timestamp.

backlog plan delete <plan-id>

Delete a plan and all its versions.

backlog plan add --task TASK-1 \
  --title "Fix unsigned JWT rejection" \
  --content "## Steps\n1. Verify RS256\n2. Return 401 on failure" \
  --as ai:claude-code

backlog plan update $PLAN_ID \
  --change-note "added key rotation step" \
  --as human:alice

backlog plan history $PLAN_ID

comment

backlog comment add --task <id> <body> [--as <actor>]

Add an actor-attributed comment to a task. Comments are append-only.

backlog comment list --task <id> [--json]

List all comments on a task in chronological order.

backlog comment delete <comment-id>

Hard delete a comment by its ULID.

label

backlog label create --project <alias> <name> [--color #rrggbb]

Create a per-project label. Labels are scoped to a project — the same name in two projects is independent.

backlog label list --project <alias> [--json]

List all labels for a project.

backlog label attach --task <id> <name>

Attach a label to a task. The label must already exist in the task's project.

backlog label detach --task <id> <name>

Remove a label from a task. Does not delete the label from the project.

profile

backlog profile add <name> --path <dir>

backlog profile list

List all profiles. The active default is marked with *.

backlog profile set-default <name>

Set the default profile. Used when no --db, --profile, or $BACKLOG_DB is provided.

backlog profile clear-default

Remove the active default profile without deleting any workspace or profile entry.

backlog profile remove <name>

Remove a profile from the registry. Does not delete workspace files.

import-findings

backlog import-findings <file.json> [--project <alias>] [--dry-run] [--as <actor>]

Bulk-import tasks from a structured JSON findings file. The primary integration point for security scanners and AI agents.

--project <alias>	Override the project declared in the file
--dry-run	Report counts but write nothing
--as <actor>	Actor to attribute all created tasks to, e.g. `ai:semgrep`

findings.json format

{
  "version": 1,
  "project": "api",
  "items": [
    {
      "title": "SQL injection in /users endpoint",
      "type": "vulnerability",
      "priority": "P1",
      "source": "semgrep",
      "external_ref": "SEMGREP-001",
      "plans": [
        { "title": "Remediation", "body": "Use parameterized queries." }
      ]
    }
  ]
}

import

backlog import <other.db> [--project <alias>] [--dry-run] [--as <actor>]

Merge tasks from another backlog.db into this workspace. Imported tasks receive new ULIDs; the original ID is stored in external_ref as imported:<original-id>.

export

backlog export --format <json|csv|md> [--project <alias>] [--out <file>]

Export tasks to stdout or a file.

--format json\|csv\|md	Output format (required)
--project <alias>	Limit export to one project
--out <file>	Write to file instead of stdout

sync

backlog sync

Read backlog.json and ensure every project declared there exists in the database. Existing projects are untouched (idempotent). Useful after checkout or in CI.

backlog.json format

{
  "version": 1,
  "name": "my-workspace",
  "projects": [
    { "alias": "api", "name": "API Service", "repo_path": "/code/api" },
    { "alias": "web", "name": "Web Frontend" }
  ]
}

doctor

backlog doctor check

Run SQLite PRAGMA integrity_check and report the result.

backlog doctor backup [--to <path>]

Create an atomic backup via SQLite VACUUM INTO. Safe to run while the database is in use.

backlog doctor check
backlog doctor backup --to ~/backups/backlog-$(date +%Y%m%d).db

mcp serve

backlog mcp serve [--as <actor>] [--db <path>]

Start the MCP stdio server. Speaks JSON-RPC 2.0 over stdin/stdout. AI tools (Claude Code, Cursor, Codex, OpenCode) spawn this process to access the backlog directly.

See the MCP guide for full configuration snippets per client.

web

backlog web [--port <n>] [--no-browser]

Start the embedded HTTP server and open the browser UI. Default port: 8080. All API endpoints are also available. See the API reference.

--port <n>	Port to listen on (default 8080)
--no-browser	Don't open the browser automatically

version / completion

backlog version

Print the installed version.

backlog completion <bash|zsh|fish|powershell>

Generate shell completion script.

# zsh (add to ~/.zshrc)
source <(backlog completion zsh)

# bash (add to ~/.bashrc)
source <(backlog completion bash)

Workflows

Human + AI pair programming

# Human opens a task
backlog task add -p api -t "Slow query on /search" --type bug --priority P2 --as human:alice

# Claude drafts a plan
backlog plan add --task TASK-1 --title "Query optimization plan" \
  --content "## Plan\n1. Profile with pprof\n2. Add index on search_vector\n3. Benchmark before+after" \
  --as ai:claude-code

# Human reviews and adds a step
backlog plan update $PLAN_ID \
  --change-note "added caching layer after profiling review" --as human:alice

# AI leaves a progress comment
backlog comment add --task TASK-1 \
  "Applied index. Query time dropped from 800ms to 12ms." --as ai:claude-code

# Human closes
backlog task move TASK-1 --status done --as human:alice

Security scanner integration

# Scanner writes findings.json, then:
backlog import-findings findings.json --as ai:semgrep

# Review what was imported
backlog task list --actor-kind ai --actor-name semgrep --type vulnerability
backlog task list --source semgrep --priority P1

JSON scripting

# Get all P1 tasks as JSON and pipe to jq
backlog task list --priority P1 --json | jq '.tasks[].title'

# Capture ID from task creation
TASK_ID=$(backlog task add -p api -t "Fix bug" --json | jq -r '.id')

# Chain commands
backlog plan add --task "$TASK_ID" --title "Plan" --from-file plan.md
backlog task move "$TASK_ID" --status doing