Installation & Initialization

Installation

Via npm (recommended)

npm i -g @kuwork/backlog.md

Via Bun

bun add -g @kuwork/backlog.md

Via Homebrew (macOS / Linux)

The Homebrew formula currently points to the upstream repository:

brew install backlog-md

Via Nix

The Nix flake currently points to the upstream repository:

nix run github:MrLesk/Backlog.md

GitHub Releases

Visit the Releases page to download the binary for your platform.

Apple Silicon (M1/M2) note: if you run the x64 version of Node or Bun through Rosetta, the CLI launcher detects the host architecture and Rosetta state and resolves the matching arm64 platform package; if the installed package does not match the CPU architecture, it prints clear architecture info and a reinstall command to avoid illegal hardware instruction errors. If you encounter binary resolution issues, reinstall using a native arm64 runtime first.

Initialize a Project

Enter the root of your Git repository and run:

backlog init [project-name]

The interactive wizard guides you through:

• Project name
• Default task status list
• Label definitions
• AI integration mode choice (MCP / CLI instructions / skip)

When using a custom task ID prefix (--task-prefix), only letters are allowed, and doc and decision are reserved names (used by documents and decisions); all entry points reject them.

File-system-only Project Without Git

backlog init --no-git

Use this for task management in non-code projects.

Initialize in Another Directory (BACKLOG_CWD)

backlog init does not accept a --cwd command-line flag (only mcp start accepts --cwd). It supports two ways to specify the target directory: switch the shell working directory before running, or pin the directory with the BACKLOG_CWD environment variable (which takes precedence over process.cwd(), falling back to the current working directory).

# Option 1: switch to the target repo first (most straightforward)
cd /path/to/repo && backlog init my-project

# Option 2: use an environment variable in CI/scripts (directory must already exist)
BACKLOG_CWD=/path/to/repo backlog init my-project

BACKLOG_CWD requires the directory to already exist; otherwise it fails fast with Invalid directory from BACKLOG_CWD and exits. init uses the unified runtime cwd resolution (requireRuntimeCwd), so BACKLOG_CWD and all subsequent commands see the same target directory—init no longer only recognizes the process current directory. The TUI and Web server follow the same resolution rule.

Non-interactive Initialization (CI / Scripts)

--defaults skips all interactive prompts and uses default values, which is ideal for CI and scripts; other parameters are supplied on the command line as needed:

# All defaults, one-shot initialization
backlog init "My Project" --defaults

# Specify AI integration mode (cli / mcp / none, default cli)
backlog init "My Project" --defaults --integration-mode cli

# Specify agent instruction files to generate (comma-separated; cursor writes AGENTS.md; none skips)
backlog init "My Project" --defaults --agent-instructions agents,claude

Common non-interactive parameters:

Directory Structure After Initialization

backlog/
├── tasks/          # Task files
├── docs/           # Documents
├── decisions/      # Decision records
├── drafts/         # Drafts
├── milestones/     # Milestones
├── archive/        # Archived items
├── completed/      # Completed tasks
├── assets/         # Attachments
├── config.yml      # Project configuration
└── wiki/           # Knowledge base (optional)

Verify Installation

backlog --version

Running without subcommands shows the welcome screen and detects whether the current directory is initialized:

backlog

Upgrading Backlog.md

Upgrade paths mirror installation paths:

npm / Bun: update the global package to the latest version (package name @kuwork/backlog.md)

npm update -g @kuwork/backlog.md
# or force a fresh install of the latest version
npm i -g @kuwork/backlog.md@latest

Homebrew (upstream formula):

brew upgrade backlog-md

GitHub Releases binary: download the new release from Releases and replace the old binary.

After upgrading, it is recommended to:

1. Run backlog --version to confirm the new version is active.
2. Re-run backlog init in the project root (no arguments needed)—it will create any missing directories introduced by the new version (e.g., memos/, docs/, etc., via ensureBacklogStructure()) without overwriting existing configuration or data.

Configuration Management

After initialization, adjust settings through the advanced configuration wizard:

backlog config

Configurable items include:

• Task ID prefix
• Default status list
• Definition of Done default checklist
• Default editor
• Web UI port and auto-open browser
• Git integration options (auto-commit, bypass hooks, etc.)

Related Concepts

• Product Overview — Backlog.md core positioning and feature overview
• AI Integration Setup — AI integration configuration after initialization
• Configuration Management — adjusting configuration after initialization