Getting Started - BackMark

Prerequisites

System Requirements:

Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher (comes with Node.js)
Operating System: Linux, macOS, or Windows

$ node --version

v18.17.0

$ npm --version

9.6.7

Installation

Global Installation (Recommended)

Install BackMark globally to use it from anywhere:

$ npm install -g @grazulex/backmark

added 87 packages in 5s

$ backmark --version

0.8.0

Alternative: npx (No Installation)

Run BackMark without installing:

npx @grazulex/backmark init

Verify Installation

Check that BackMark is properly installed:

backmark --help

Quick Start Guide

Step 1: Initialize Your Project

Navigate to your project directory and initialize BackMark:

$ cd my-project

$ backmark init "My Awesome Project"

✓ Created backlog directory

✓ Created tasks directory

✓ Created config.yml

✓ Initialized BackMark successfully!

This creates a backlog/ directory with the following structure:

backlog/
├── tasks/          # Task markdown files
├── templates/      # Custom task templates
├── config.yml      # Project configuration
└── .cache/         # Performance cache (auto-generated)

Step 2: Create Your First Task

Create a task using the interactive prompt or command-line options:

$ backmark task create "Implement user authentication"

✓ Created task #1: Implement user authentication

📄 File: backlog/tasks/1.md

Create a task with full metadata:

$ backmark task create "Implement user auth" \

-d "JWT-based authentication with refresh tokens" \

-p high \

-a "Claude,Alice" \

-l "feature,backend,security" \

-m "v1.0"

✓ Created task #2: Implement user auth

Step 3: View Your Tasks

List all tasks or view the Kanban board:

$ backmark task list

View the Kanban board:

$ backmark board show

✓ Opening interactive Kanban board...

💡 The board opens in full-screen interactive mode. Use arrow keys to navigate, Enter to view details, 'q' to quit.

Step 4: Update Task Status

Start working on a task by changing its status:

$ backmark task edit 1 --status "In Progress"

✓ Updated task #1

📝 Status: To Do → In Progress

Step 5: AI Workflow (Optional)

If you're working with an AI assistant, use the AI workflow commands:

$ backmark task ai-plan 1 "## Implementation Steps 1. Install JWT library (jsonwebtoken) 2. Create auth middleware 3. Implement login/logout endpoints 4. Add refresh token mechanism"

✓ Added AI plan to task #1

Learn more about the AI workflow in the AI Workflow section.

Common Commands

Task Management

# Create task
backmark task create "Title"

# List tasks
backmark task list

# View task details
backmark task view 1

# Edit task
backmark task edit 1 --status "Done"

# Delete task
backmark task delete 1

Board & Search

# Show Kanban board
backmark board show

# Watch mode (auto-refresh)
backmark board show --watch

# Search tasks
backmark search "authentication"

# Project overview
backmark overview

Filtering

# Filter by status
backmark task list --status "In Progress"

# Filter by priority
backmark task list --priority high

# Filter by assignee
backmark task list --assignee Claude

# Multiple filters
backmark task list --status "To Do" \
  --priority high

AI Workflow

# AI planning
backmark task ai-plan 1 "Plan..."

# AI notes
backmark task ai-note 1 "Note..."

# AI documentation
backmark task ai-doc 1 "Docs..."

# AI review
backmark task ai-review 1 "Review..."

Next Steps

📚 Learn Vibe Coding

Understand the philosophy behind BackMark's AI-first design.

Learn More

🤖 AI Workflow

Deep dive into using BackMark with your AI assistant.

Explore Workflow

⚙️ Commands Reference

Complete list of all BackMark commands and options.

View Commands

Pro Tips

💡 Use --help with any command to see all options: backmark task create --help
💡 Enable indexing for better performance with 100+ tasks: backmark config set performance.useIndex true
💡 Customize board columns in backlog/config.yml
💡 Use templates for common task types: backmark task create-from-template feature "New feature"
💡 Tasks are just Markdown files - edit them directly with your favorite editor!
💡 Version control your backlog/ directory with Git for complete task history

Troubleshooting

Command not found: backmark

If you get "command not found" after global installation, check your npm global bin path:

npm config get prefix

Add the bin directory to your PATH, or use npx @grazulex/backmark instead.

Tasks not showing up

Make sure you're in a directory with an initialized BackMark project (contains backlog/ directory).

Need Help?

Report issues on GitHub or check the full commands reference.