@brainfile/cli

Task management for your terminal. A full kanban board that lives in a markdown file.

• Modern, borderless TUI optimized for information density
• Vim-style navigation with intuitive keybindings
• CLI commands for scripting and automation
• MCP server for AI assistant integration

Installation

npm install -g @brainfile/cli

Verify installation:

brainfile --version

Quick Start

# Initialize a new brainfile
brainfile init

# Launch interactive TUI
brainfile

# Or use CLI commands
brainfile list                                    # List all tasks
brainfile add --title "My task" --column todo     # Add a task
brainfile move --task task-1 --column done        # Move a task

Commands

Terminal UI (TUI)

Launch an interactive task board:

brainfile                    # Auto-detect (prefers .brainfile/brainfile.md)
brainfile ./path/to/file.md  # Open specific file

Task Card Layout:

  ▌ CRIT  Implement user authentication flow
    [1/5] · Nov 30 · #auth #security                     task-39

    HIGH  Dashboard performance optimization
    [0/4] · Dec 4 · #performance #frontend               task-40

• ▌ indicator shows selected task
• Priority badge (CRIT/HIGH/MED/LOW) leads each row
• [X/Y] shows subtask progress
• Due dates with urgency coloring (red if overdue, yellow if soon)
• Tags and task ID complete the metadata row

Panel Navigation: | Key | Action | |-----|--------| | 1 | Switch to Tasks panel | | 2 | Switch to Rules panel | | 3 | Switch to Archive panel | | ? | Show help | | q | Quit |

Tasks Panel: | Key | Action | |-----|--------| | TAB / Shift+TAB | Navigate columns | | j/k or ↑/↓ | Navigate tasks | | h/l or ←/→ | Switch columns | | g/G | Jump to top/bottom | | Enter | Expand/collapse task | | / | Search tasks | | r | Refresh |

Search Filters: | Filter | Example | Description | |--------|---------|-------------| | Priority | p:high | Filter by priority | | Tag | #bug or t:feature | Filter by tag | | Assignee | @john | Filter by assignee | | Due date | due:week | overdue, today, week, month |

Combine filters with text: p:high #bug login issue

Task Management: | Key | Action | |-----|--------| | e | Edit task in $EDITOR | | m | Move task to column | | d | Delete task | | n | Quick add new task | | N | New task in $EDITOR | | p | Cycle priority | | t | Toggle subtask | | A | Archive task | | y | Copy task ID |

Rules Panel: | Key | Action | |-----|--------| | TAB / Shift+TAB | Switch rule type | | h/l | Switch rule type (always/never/prefer/context) | | j/k | Navigate rules | | n | Add new rule | | e | Edit selected rule | | d | Delete selected rule |

Archive Panel: | Key | Action | |-----|--------| | j/k | Navigate archived tasks | | Enter | Expand/collapse task | | R | Restore task to column | | d | Permanently delete task | | r | Refresh archive |

list

List all tasks with optional filtering:

brainfile list
brainfile list --column "In Progress"
brainfile list --tag bug

Options:

• -f, --file <path> - Brainfile path (default: brainfile.md)
• -c, --column <name> - Filter by column
• -t, --tag <name> - Filter by tag

show

Show full details of a single task:

brainfile show --task task-1
brainfile show -t task-1 --file ./brainfile.md

Options:

• -f, --file <path> - Brainfile path (default: brainfile.md)
• -t, --task <id> - Task ID (required)

add

Create a new task:

brainfile add --title "Implement auth" --column todo
brainfile add --title "Fix bug" --priority high --tags "bug,urgent"
brainfile add --title "Review PR" --assignee john --due-date 2025-02-01

Options:

• -t, --title <text> - Task title (required)
• -c, --column <name> - Target column (default: todo)
• -d, --description <text> - Task description
• -p, --priority <level> - low, medium, high, or critical
• --tags <list> - Comma-separated tags
• --assignee <name> - Assignee name
• --due-date <date> - Due date (YYYY-MM-DD)
• --subtasks <list> - Comma-separated subtask titles

move

Move a task to a different column:

brainfile move --task task-1 --column "In Progress"
brainfile move --task task-5 --column done

Options:

• -t, --task <id> - Task ID (required)
• -c, --column <name> - Target column (required)

patch

Update specific fields of a task:

brainfile patch --task task-1 --priority critical
brainfile patch --task task-1 --title "Updated title" --tags "new,tags"
brainfile patch --task task-1 --clear-assignee  # Remove assignee

Options:

• -t, --task <id> - Task ID (required)
• --title <text> - New title
• --description <text> - New description
• --priority <level> - New priority
• --tags <list> - New tags (comma-separated)
• --assignee <name> - New assignee
• --due-date <date> - New due date
• --clear-description - Remove description
• --clear-priority - Remove priority
• --clear-tags - Remove tags
• --clear-assignee - Remove assignee
• --clear-due-date - Remove due date

delete

Permanently delete a task:

brainfile delete --task task-1 --force

Options:

• -t, --task <id> - Task ID (required)
• --force - Confirm deletion (required)

archive

Move a task to the archive:

brainfile archive --task task-1

restore

Restore a task from the archive:

brainfile restore --task task-1 --column todo

Options:

• -t, --task <id> - Task ID (required)
• -c, --column <name> - Target column (required)

subtask

Manage subtasks:

brainfile subtask --task task-1 --add "New subtask"
brainfile subtask --task task-1 --toggle task-1-1
brainfile subtask --task task-1 --update task-1-1 --title "Updated"
brainfile subtask --task task-1 --delete task-1-2

Options:

• -t, --task <id> - Parent task ID (required)
• --add <title> - Add a new subtask
• --toggle <id> - Toggle subtask completion
• --update <id> - Update subtask (use with --title)
• --delete <id> - Delete a subtask
• --title <text> - New title (for --update)

lint

Validate and auto-fix brainfile syntax:

brainfile lint              # Check for issues
brainfile lint --fix        # Auto-fix issues
brainfile lint --check      # Exit with error code (for CI)

What it checks:

• YAML syntax errors
• Unquoted strings with colons (auto-fixable)
• Duplicate column IDs
• Missing required fields

template

Create tasks from templates:

brainfile template --list
brainfile template --use bug-report --title "Login fails"
brainfile template --use feature-request --title "Dark mode"

Built-in Templates:

• bug-report - Bug tracking with triage steps
• feature-request - Feature proposals
• refactor - Code refactoring tasks

hooks

Integrate with AI coding assistants:

brainfile hooks install claude-code
brainfile hooks install cursor --scope project
brainfile hooks install cline
brainfile hooks list
brainfile hooks uninstall claude-code --scope all

Supported Assistants:

• Claude Code
• Cursor
• Cline

Hooks provide automatic reminders to update task status during AI-assisted development.

mcp

Start an MCP (Model Context Protocol) server for AI assistant integration:

brainfile mcp
brainfile mcp --file ./project/brainfile.md

The MCP server exposes all brainfile operations as tools that AI assistants can use directly.

Available MCP Tools: | Tool | Description | |------|-------------| | list_tasks | List tasks with optional filtering | | add_task | Create a new task | | move_task | Move task between columns | | patch_task | Update task fields | | delete_task | Permanently delete a task | | archive_task | Archive a task | | restore_task | Restore from archive | | add_subtask | Add a subtask | | delete_subtask | Delete a subtask | | toggle_subtask | Toggle subtask completion | | update_subtask | Update subtask title |

Configuration for Claude Code:

Add to your MCP settings (.mcp.json or Claude Code config):

{
  "mcpServers": {
    "brainfile": {
      "command": "npx",
      "args": ["@brainfile/cli", "mcp"]
    }
  }
}

Or with a specific file:

{
  "mcpServers": {
    "brainfile": {
      "command": "npx",
      "args": ["@brainfile/cli", "mcp", "-f", "path/to/brainfile.md"]
    }
  }
}

init

Create a new brainfile:

brainfile init
brainfile init --file ./project/tasks.md  # Custom location (optional)
brainfile init --force  # Overwrite existing

migrate

Move a legacy root brainfile.md into the preferred .brainfile/ directory:

brainfile migrate
brainfile migrate --force

Output Colors

The CLI uses colors to highlight information:

| Element | Color | |---------|-------| | Task IDs | Gray | | Titles | White | | Critical Priority | Red (bold) | | High Priority | Red | | Medium Priority | Yellow | | Low Priority | Blue | | Tags | Cyan | | Completed | Green |

Package Information

• npm: https://www.npmjs.com/package/@brainfile/cli
• GitHub: https://github.com/brainfile/cli
• Core Library: @brainfile/core
• Protocol: https://brainfile.md

Development

git clone https://github.com/brainfile/cli.git
cd cli
npm install
npm run build
npm test

License

MIT