Configuration Reference

Complete guide to customizing BackMark through the config.yml file.

Configuration File

The config.yml file is located at:

backlog/config.yml

You can edit it directly or use the CLI commands:

backmark config get <key>
backmark config set <key> <value>

Project Configuration

project

Basic project information.

Option Type Default Description
name string 'My Project' Project name displayed in overview
createdAt string ISO timestamp Project creation timestamp

Example:

project:
  name: "My Awesome Project"
  createdAt: "2024-11-06T00:00:00.000Z"

Board Configuration

board

Customize your Kanban board columns, priorities, and completion behavior.

Option Type Default Description
columns array ['To Do', 'In Progress', 'Review', 'Done'] Task status columns for the board
priorities array ['low', 'medium', 'high', 'critical'] Available priority levels
completedStatuses array ['Done'] Statuses that mark a task as completed (triggers closed_date)

Example:

board:
  columns:
    - Backlog
    - To Do
    - In Progress
    - Review
    - Testing
    - Done
  priorities:
    - trivial
    - low
    - medium
    - high
    - critical
    - blocker
  completedStatuses:
    - Done
    - Archived

Display Configuration

display

Control how tasks and dates are displayed in the CLI.

Option Type Default Description
dateFormat string 'yyyy-MM-dd HH:mm' Date format pattern (uses date-fns)
zeroPaddedIds boolean true Display task IDs with leading zeros (#001 vs #1)
theme string 'default' Color theme (reserved for future use)

Example:

display:
  dateFormat: "dd/MM/yyyy HH:mm"
  zeroPaddedIds: false
  theme: "default"

Search Configuration

search

Fine-tune fuzzy search behavior powered by Fuse.js.

Option Type Default Description
threshold number 0.3 Search sensitivity (0.0 = exact, 1.0 = match anything)
maxResults number 50 Maximum number of search results to return

Example:

search:
  threshold: 0.4    # Less strict matching
  maxResults: 100   # More results

Performance Configuration

performance

Control the LokiJS indexing system for faster queries.

Option Type Default Description
useIndex boolean true Enable LokiJS indexed repository (50-250x faster)
rebuildIndexOnStart boolean false Rebuild the index cache on every command start

Example:

performance:
  useIndex: true
  rebuildIndexOnStart: false

💡 Performance Tip:

Keep useIndex: true for projects with 50+ tasks. The LokiJS indexed repository provides 50-250x faster queries compared to the filesystem repository.

Validations Configuration

validations.close

Configure smart validations that run when closing tasks. BackMark helps you maintain task quality and project integrity.

Option Type Default Description
check_subtasks boolean true Block close if subtasks are not done
check_dependencies boolean true Block close if dependencies are not met
check_blocked_by boolean true Block close if task is still blocked
check_acceptance_criteria boolean true Block close if acceptance criteria are not met
warn_missing_ai_review boolean true Warn if AI-assigned task has no AI review
warn_early_close boolean true Warn if closing before start date
warn_late_close boolean true Warn if closing after end date
warn_quick_close number 300 Warn if closed too quickly (seconds, 0 = disabled)
suggest_parent_close boolean true Suggest closing parent when all subtasks are done
notify_unblocked boolean true Notify about tasks that are now unblocked
allow_force boolean true Allow --force flag to bypass validations

Example:

validations:
  close:
    check_subtasks: true
    check_dependencies: true
    check_blocked_by: true
    check_acceptance_criteria: true
    warn_missing_ai_review: true
    warn_early_close: true
    warn_late_close: true
    warn_quick_close: 300       # 5 minutes
    suggest_parent_close: true
    notify_unblocked: true
    allow_force: true

Validation Behavior:

  • Block: Prevents closing the task entirely (hard validation)
  • Warn: Shows a warning but allows closing (soft validation)
  • Notify: Displays helpful information
  • Suggest: Recommends an action you might want to take

Complete Configuration Example

Full config.yml Example

project:
  name: "My Awesome Project"
  createdAt: "2024-11-06T00:00:00.000Z"

board:
  columns:
    - To Do
    - In Progress
    - Review
    - Done
  priorities:
    - low
    - medium
    - high
    - critical
  completedStatuses:
    - Done

display:
  dateFormat: "yyyy-MM-dd HH:mm"
  zeroPaddedIds: true
  theme: "default"

search:
  threshold: 0.3
  maxResults: 50

performance:
  useIndex: true
  rebuildIndexOnStart: false

validations:
  close:
    check_subtasks: true
    check_dependencies: true
    check_blocked_by: true
    check_acceptance_criteria: true
    warn_missing_ai_review: true
    warn_early_close: true
    warn_late_close: true
    warn_quick_close: 300
    suggest_parent_close: true
    notify_unblocked: true
    allow_force: true

Managing Configuration via CLI

Get Configuration Value

backmark config get <key>

Examples:

backmark config get performance.useIndex
backmark config get board.columns
backmark config get validations.close.check_subtasks

Set Configuration Value

backmark config set <key> <value>

Examples:

backmark config set performance.useIndex true
backmark config set search.threshold 0.4
backmark config set display.zeroPaddedIds false