CLI & Terminal UI

The Brainfile CLI gives you full control over your task board from the terminal. Use the interactive TUI for a visual experience, or run commands for automation.

Installation

npm install -g @brainfile/cli

Verify installation:

brainfile --version

Core Features

• Interactive TUI: A full-featured terminal kanban board.
• Agent Coordination: Built-in support for Agent Contracts to coordinate work between AI assistants.
• Rich Task Metadata: Support for priorities, tags, assignees, due dates, and subtasks.
• Task Archival: Complete and archive tasks to searchable logs.

---

Interactive TUI

Launch an interactive kanban board in your terminal:

brainfile

Or open a specific file:

brainfile ./path/to/brainfile.md

TUI Layout

The interactive board displays your columns side by side, with tasks flowing through your workflow:

Keyboard Controls

Keyboard Quick Reference

Key	Action
TAB / Shift+TAB	Navigate between columns
j / k or ↑ / ↓	Navigate tasks
Enter	Expand/collapse task details
/	Search tasks
?	Show help
r	Refresh
q	Quit

Real-time sync

The TUI watches your file for changes — edits from your editor or AI assistants appear instantly.

---

Common Commands

Initialize a New Board

brainfile init

Creates .brainfile/ directory with brainfile.md config, board/, and logs/. Default columns: To Do and In Progress.

List Tasks

brainfile list                    # All tasks
brainfile list --column todo      # Filter by column
brainfile list --tag bug          # Filter by tag

Add Tasks

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

Move Tasks

brainfile move --task task-1 --column in-progress

Complete Tasks

brainfile complete --task task-1   # Moves from board/ to logs/

Update Tasks

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

Manage Subtasks

brainfile subtask --task task-1 --add "Write tests"
brainfile subtask --task task-1 --toggle task-1-1
brainfile subtask --task task-1 --delete task-1-2

---

Agent Contracts

Agent-to-Agent Coordination

The CLI facilitates structured coordination between agents through the contract system. Contracts define deliverables, validation commands, and constraints — enabling autonomous agent work with automated verification.

Create Task with Contract

brainfile add --title "Implement API" \
  --with-contract \
  --deliverable "src/api.ts" \
  --validation "npm test"

Worker Agent Lifecycle

1. Pickup: brainfile contract pickup -t task-1
2. Deliver: brainfile contract deliver -t task-1

PM Agent Lifecycle

1. Validate: brainfile contract validate -t task-1 (auto-checks deliverables and runs commands)
2. Complete: brainfile complete -t task-1 (after validation passes)

See the Agent Contracts Guide for the full lifecycle and best practices.

---

Archive & Restore

# Archive a task
brainfile archive --task task-5

# Restore from archive
brainfile restore --task task-5 --column todo

Validate

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

---

Templates

Create tasks from built-in templates:

brainfile template --list
brainfile template --use bug-report --title "Login fails on mobile"
brainfile template --use feature-request --title "Add dark mode"

Available templates:

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

---

Shell Aliases

Speed up your workflow

Add these to your .bashrc or .zshrc:

alias bf="brainfile"
alias bfl="brainfile list"
alias bfa="brainfile add"
alias bfm="brainfile move"

---

Next Steps

• Full Command Reference — Complete documentation for every command, option, and flag
• MCP Server — Expose Brainfile as an MCP server for AI assistant integration
• Agent Contracts Guide — Deep dive into the contract lifecycle and PM/worker coordination
• CI/CD Examples — GitHub Actions, pre-commit hooks, and npm script automation
• Core Library — Use @brainfile/core programmatically in your own tools