Board Export

The board export feature generates a static Markdown snapshot of the current project state, making it easy to embed in README files, email reports, or archive in version control.

Export as Markdown Table

# Export to the default file Backlog.md
backlog board export

# Export to a specific file
backlog board export project-status.md

# Force overwrite an existing file
backlog board export --force

The exported file contains:

• Project title and export timestamp
• Version label (if --export-version is provided)
• Markdown tables grouped by status, each row showing task ID, title, assignee, and labels
• Metadata summary: task counts per status and completion percentage

Subtasks are listed under their parent with a └─ prefix; deeper descendant tasks (such as subtasks of subtasks) are also listed recursively in ID order and are not omitted.

Note: The default export destination is Backlog.md in the project root. If the file already exists and --force is not used, the command prompts for confirmation before overwriting.

Embed in README.md

To display the board status directly on the repository home page, use the --readme flag:

backlog board export --readme

This command looks for the board marker placeholders in README.md:

<!-- BACKLOG BOARD START -->
<!-- BACKLOG BOARD END -->

When found, it inserts the current board table between the two markers. If the markers do not exist in README.md, the command prompts you to add them manually.

This feature is commonly used in open-source projects so visitors can see the current iteration progress at a glance.

Export Version Label

At release points or when a milestone is completed, you can attach version information to the export:

# Simple version number
backlog board export --export-version "v1.2.3"

# Combined: embed in README and label the version
backlog board export --readme --export-version "Release 2024.12.1-beta"

The version string appears below the export table title, making it easy to distinguish from historical export records.

Automated Export Example

Integrate board export in CI/CD or release scripts:

# Automatically update the README board before a release
backlog board export --readme --force --export-version "$GITHUB_REF_NAME"
git add README.md Backlog.md
git commit -m "chore: update board snapshot"

Tip: Because backlog board export is a read-only operation, it can run safely in CI environments that do not have write access. If you need to commit the result, make sure the pipeline has the appropriate Git credentials configured.