Configuration Management

Backlog.md provides a flexible configuration system, supporting project settings through an interactive wizard or direct command-line management. Configuration is stored in YAML files and version-controlled with project code, ensuring team members use consistent workflow conventions.

Interactive Configuration Wizard

The backlog config command starts the advanced configuration wizard, guiding you through all key settings with interactive questions:

backlog config

The wizard covers the following configuration areas:

• Shell completion installation
• Cross-branch task status checking
• Git hook bypass settings
• Auto-commit enablement
• ID zero-padding formatting
• Default editor selection
• Definition of Done (DoD) default items management
• Web UI port and auto-open browser

Follow the prompts; each option has a default value and explanatory hint. After configuration completes, Backlog.md automatically writes the settings to the project configuration file.

Direct Command-Line Operations

For quickly modifying a single configuration item, use backlog config get and backlog config set.

Viewing Current Configuration

List all configured items and their current values:

backlog config list

# Plain-text output (unified convention for AI-readable output; byte-for-byte identical to output without the flag)
backlog config list --plain

--plain is listed by the overview guide as the standard way to read live configuration: output is already plain text, and the flag is accepted so that agent invocations that habitually append --plain to every command do not fail with "unknown option".

After the statuses row, config list also prints a derived terminal-status set, such as terminalStatuses: [Done, Dropped] (derived from statuses). Terminal statuses are derived from each status's category (done / dropped) in the state machine; this is read-only presentation, not a settable configuration key—to adjust terminal statuses, modify the corresponding state's category in the state machine editor.

View a single configuration item:

backlog config get projectName
backlog config get statuses
backlog config get defaultPort

Modifying Configuration Items

Set the value of a single configuration item:

backlog config set projectName "My Project"
backlog config set defaultPort 8080
backlog config set autoCommit true

Set list-type configuration items:

backlog config set statuses "To Do,In Progress,Done"
backlog config set labels "bug,feature,docs"

config get/set/list display consistent configuration items through a shared available-keys list. For list-type configurations (statuses, labels), it is recommended to use backlog config get <key> to view the current value and then edit the corresponding field in config.yml directly (supporting block YAML sequences), rather than overwriting through config set.

Key Configuration Items

Project Basics

The order of the status list determines column order on the board. The first status is treated as the initial task status; terminal statuses are determined by each status's category (done / dropped), no longer simply the last item in the list.

State Machine Configuration

statuses describes the state machine in object form; each status is an object:

statuses:
  - name: To Do
    category: active
    next:
      - to: Planning
        when: Description and acceptance criteria are complete; ready to start
        ai: allowed
  - name: Done
    category: done
    exit: complete
    next: []
  - name: Dropped
    category: dropped
    exit: archive
    display: false
    next: []

The legacy string-array format is still compatible (last item is terminal). There is no CLI command to set statuses: it is recommended to maintain it visually in the state machine editor on the Web settings page, or edit this file directly—write the whole object back without losing fields. backlog instructions overview (and the MCP overview resource of the same name) automatically renders a complete readable description of the current state machine. The first backlog init writes the built-in seven-state default machine (To Do / Planning / Plan Review / In Progress / In Review / Done / Dropped, localized with the interface language). Semantic details are in Task Lifecycle.

Task Defaults

# Set default assignee (list, comma-separated)
backlog config set defaultAssignee "@alice,@bob"

# Remove default assignee (empty value removes the key)
backlog config set defaultAssignee ""

# Clear default editor—the service default "code --wait" can hang unattended agent processes
backlog config set defaultEditor ""
backlog init --default-editor ""

defaultAssignee follows a three-state semantics:

• Not passing -a (field omitted) → apply the configured default assignee.
• Explicitly passing -a (even one value) → completely replace the default, not merged.
• Explicitly clearing --unassign (or clearing assignee chips in the Web UI) → save as an empty list, no fallback to default.

Defaults are applied at the Core creation-funnel layer, so behavior is consistent across CLI task create, draft create, the creation wizard, TUI N creator, Web POST /api/tasks, and MCP task_create.

Setting defaultEditor to an empty string means "do not use a default editor": config set defaultEditor "" skips executable validation and removes the key, and init --default-editor "" also clears any existing configuration. Non-empty values still validate that the executable exists.

Editor Resolution Priority and Vim / Neovim Configuration

When pressing E to open an editor, resolution priority is (doc-002): EDITOR environment variable > config.yml defaultEditor > platform default (nano on macOS/Linux, notepad on Windows). For Vim / Neovim, setting the environment variable is recommended:

export EDITOR=nvim          # or vim
# Or write to project config
backlog config set defaultEditor nvim

• In TUI (backlog board / backlog task <id>), pressing E suspends the character screen, exits the alternate buffer, and automatically restores terminal state after the editor exits.
• Troubleshooting: set TERM=xterm-256color for color issues; editor unresponsiveness or immediate exit usually means the editor path includes arguments—write the full executable path or use a wrapper script.
• Per-command override: EDITOR=nvim backlog board.

Branch and Git Integration

When checkActiveBranches is enabled, Backlog.md checks other local and remote branches when loading tasks to ensure cross-branch task statuses are accurate. This may affect performance in large repositories; reduce activeBranchDays to speed it up.

includeCrossBranch (corresponding to include_cross_branch in config.yml) controls display: when enabled, the board, task list, and search include tasks that exist only on other branches; when unset, local-first behavior is preserved (historical CLI behavior). It is independent of checkActiveBranches—the latter controls "whether to scan" (and determines the candidate branch set for task ID allocation), while the former controls "whether scan results are displayed". Disabling scanning also narrows the ID allocation candidate set; understand the cost together with activeBranchDays. Both toggles are in the Web settings page Advanced Settings card and take effect immediately without restart.

remoteOperations depends on checkActiveBranches; when the latter is disabled, the former automatically becomes ineffective.

Automation Behavior

The onStatusChange command is executed via sh -c in the project root, with task information injected through environment variables: $TASK_ID (task ID), $OLD_STATUS (old status), $NEW_STATUS (new status), $TASK_TITLE (title), referenced in the command string as $TASK_ID, etc. Callback failure only prints an error log and does not block the status change. A task's individual onStatusChange frontmatter field takes precedence over the global config. This key is not in the config get/set available-keys list; edit config.yml directly to set it.

When autoCommit is enabled, Backlog.md automatically runs git commit each time a task is created or modified via CLI, saving the step of manual commit. Combined with bypassGitHooks, this improves efficiency when pre-commit hooks are slow.

autoCommit only commits files actually touched by each write (new files, replaced old paths, source and destination paths of moves/archives), and does not git add the entire backlog/ directory or clear your existing staged/unstaged changes. This ensures auto-commits do not interfere with other changes in your current workspace.

filesystemOnly is suitable for pure-filesystem projects or environments without Git; enabling it disables all Git-related features.

ID and Prefixes

Prefix configuration allows customizing task and draft ID formats. For example, after setting prefixes.task to back, new task IDs become back-1, back-2, etc.

Reserved prefixes: task prefixes may only contain letters and cannot use the reserved names doc and decision (used by documents and decisions respectively). This rule is enforced consistently across all entry points—the init --task-prefix flag, interactive wizard, and browser initialization page all reject them. backlog doctor reports prefix conflicts in existing projects, and refuses to run --fix while conflicts remain (to avoid assigning new numbers into conflicting storage during duplicate-ID repair). Existing projects already using reserved prefixes continue to work normally; re-initialization does not actively rewrite them.

zeroPaddedIds controls the formatted width of IDs. When set to 3, IDs display as task-001; when set to 4, they display as task-0001. This helps maintain lexicographic consistency in filenames.

Web UI

Modify defaultPort to avoid conflicts with other local services. When autoPort is enabled (default), if the default port is occupied the server automatically uses the next available port and prints the actual address in the terminal; it only accepts ports within the user port range (1024–65535) that it scans itself, and refuses random high ports assigned by the OS. When autoPort is disabled, a port conflict produces an EADDRINUSE error directly. This toggle is also available in the Web interface "Settings" panel. Disabling autoOpenBrowser means running backlog browser only starts the server and does not pop up a browser window, suitable for remote development or server environments.

hideEmptyColumns (corresponding to hide_empty_columns in config.yml) hides status columns that currently have no tasks, reducing visual clutter; all status columns remain visible while dragging a task so it can be dropped. It can also be toggled next to the Auto Open Browser switch in the Web interface "Settings" panel.

MCP HTTP Transport

The mcp.http.* keys (mcp.http.host / mcp.http.port / mcp.http.auth.*) are currently reserved configuration only: the current MCP implementation only supports stdio transport (backlog mcp start), does not listen on any network port, and has no consumer logic for HTTP transport. Configuring these keys has no effect; continue using the stdio approach. See MCP Workflow for details.

Configuration Storage Location

Backlog.md looks for configuration files in the following priority order:

1. backlog/config.yml
2. backlog.config.yml (project root)

backlog/config.yml is recommended so configuration is stored centrally with tasks, documents, and other project data, making backup and migration easier. When using backlog.config.yml, you can specify the relative path to the backlog folder via the backlogDirectory item (such as .backlog).

Custom backlog directory fully effective: memo storage and graph scanning/watching previously hard-coded the directory name as backlog, causing read/write/watch errors and empty graphs in projects with custom directories such as .backlog. This is now resolved by uniformly parsing the configured directory. If you previously used memos in a custom-directory project, old data is still under your backlog-dir/memos and is now correctly recognized; if an empty backlog/memos was mistakenly created at the root, you can delete it manually. Re-running backlog init will also create missing directories such as memos/, docs/, etc.

Example YAML configuration file:

projectName: "My Project"
statuses:
  - Backlog
  - To Do
  - In Progress
  - Done
labels:
  - bug
  - feature
  - docs
dateFormat: "YYYY-MM-DD"
checkActiveBranches: true
include_cross_branch: false
remoteOperations: true
activeBranchDays: 30
autoCommit: false
bypassGitHooks: false
prefixes:
  task: "back"
  draft: "draft"
defaultAssignee:
  - "@alice"
defaultEditor: "vim"
defaultPort: 6420
autoPort: true
autoOpenBrowser: true
hide_empty_columns: false

Block YAML lists: list-type configurations (statuses, labels) support both the block sequence syntax shown above and inline syntax (statuses: ["To Do", "In Progress", "Done"]). The system parses block lists according to standard YAML semantics first, while remaining compatible with the legacy inline bracket format.

After modifying the configuration file, Backlog.md automatically loads the latest settings without restarting the service.