Agent Board CLI

Agent-Board CLI

Quick Reference

# Version
agent-board version                     # Show version info
agent-board --version                   # Short form

# Get any entity by ID (auto-detects type from prefix)
agent-board get <board_id>              # Get board overview
agent-board get <card_id>               # Get card details
agent-board get <agent_id>              # Get agent details

# List operations
agent-board list boards [--include-deleted]
agent-board list cards <board_id> [--status todo|in-progress|pending-review|done] [--include-deleted]
agent-board list cards <board_id> --tag blocked --tag needs-human  # Filter by tags (AND logic)
agent-board list agents [--include-inactive]
agent-board list comments <card_id>

# Create operations
agent-board create board "Project Name" --description "Description"
agent-board create card <board_id> "Task name" --description "Details" --status todo
agent-board create agent [name] [--command stakpak] [--description "Agent purpose"]
agent-board create checklist <card_id> --item "Step 1" --item "Step 2"  # Adds items to card's checklist
agent-board create comment <card_id> "Progress update or notes"

# Update operations
agent-board update board <board_id> --name "New name" --description "New desc"
agent-board update card <card_id> --status in-progress --assign-to-me
agent-board update card <card_id> --add-tag urgent --remove-tag blocked
agent-board update agent <agent_id> --name new-name --workdir .
agent-board update checklist-item <item_id> --check    # Mark complete
agent-board update checklist-item <item_id> --uncheck  # Mark incomplete

# Delete operations (soft delete for boards/cards/agents, hard delete for others)
agent-board delete board <board_id>
agent-board delete card <card_id>
agent-board delete agent <agent_id>
agent-board delete comment <comment_id>
agent-board delete checklist-item <item_id>

# Agent identity
agent-board whoami                      # Show current agent identity

# Get my assigned cards
agent-board mine [--status todo|in-progress|pending-review|done]

Installation

# Homebrew (recommended)
brew tap stakpak/stakpak && brew install agent-board

# Direct download (replace PLATFORM: darwin-aarch64, darwin-x86_64, linux-x86_64, linux-aarch64)
curl -L https://github.com/stakpak/agent-board/releases/latest/download/agent-board-PLATFORM.tar.gz | tar xz
sudo mv agent-board /usr/local/bin/

# Build from source
cargo build --release  # Binary at ./target/release/agent-board

Agent Identity

Identity must be explicitly registered before using --assign-to-me or --status in-progress:

# 1. Register an agent (auto-generates name like "swift-falcon")
agent-board create agent
# Created agent: agent_abc123 (Name: swift-falcon)
# To use this agent, run:
#   export AGENT_BOARD_AGENT_ID=agent_abc123

# Or with explicit name
agent-board create agent code-reviewer --command claude

# 2. Set identity for session (required before claiming cards)
export AGENT_BOARD_AGENT_ID=agent_abc123

# 3. Now you can claim cards and set status
agent-board update card card_xyz --status in-progress --assign-to-me

# Verify identity (warns if wrong directory)
agent-board whoami

Note: Using --assign-to-me or --status in-progress without AGENT_BOARD_AGENT_ID set will error with setup instructions.

Data stored in ~/.agent-board/data.db. Override: export AGENT_BOARD_DB_PATH=/path/data.db

Workflow Patterns

Starting a New Task

# 1. Find or create a board
agent-board list boards
agent-board create board "Feature Development" --description "Q1 features"

# 2. Create a card for the task
agent-board create card board_abc123 "Implement user authentication" \
  --description "Add OAuth2 login flow with Google and GitHub providers"

# 3. Break down into subtasks (each card has one checklist)
agent-board create checklist card_xyz789 \
  --item "Set up OAuth client credentials" \
  --item "Create auth endpoints" \
  --item "Add session management" \
  --item "Write integration tests" \
  --item "Update documentation"

# 4. Claim the card and start working
agent-board update card card_xyz789 --status in-progress --assign-to-me

# 5. Document that you're starting
agent-board create comment card_xyz789 "Beginning OAuth implementation"

Tracking Progress

# Check off completed subtasks
agent-board update checklist-item item_001 --check
agent-board update checklist-item item_002 --check

# Add progress notes
agent-board create comment card_xyz789 "OAuth endpoints complete. Starting session management."

# View current state
agent-board get card_xyz789

Completing Work

# Check remaining items
agent-board update checklist-item item_003 --check
agent-board update checklist-item item_004 --check
agent-board update checklist-item item_005 --check

# Mark done (assignment preserved for history)
agent-board update card card_xyz789 --status done

# Add completion summary
agent-board create comment card_xyz789 "Implementation complete. All tests passing."

Reviewing Work

# See all your assigned cards
agent-board mine

# Filter by status
agent-board mine --status in-progress

# Get board overview
agent-board get board_abc123

# List all cards on a board
agent-board list cards board_abc123 --status todo

Output Formats

Use --format to control output:

# Get card ID for scripting
CARD_ID=$(agent-board create card board_123 "New task" --format simple)

# Get full JSON for parsing
agent-board get card_xyz789 --format json | jq '.status'

Status Values

Note: Use hyphens on the command line (e.g., in-progress, pending-review), not underscores.

Card Assignment

Claim cards with --assign-to-me:

# Claim a card when starting work
agent-board update card card_123 --status in-progress --assign-to-me

Assignment is preserved after completion for history/accountability.

Explicit assignment control:

# Assign to specific agent
agent-board update card card_123 --assign agent_abc123

# Unassign card (only if needed)
agent-board update card card_123 --assign null

Tags

Organize cards with tags:

# Add tags
agent-board update card card_123 --add-tag urgent --add-tag backend

# Remove tags
agent-board update card card_123 --remove-tag urgent

Exit Codes

Human Review (Optional)

Cards can flow in-progress → done directly. Use these only when human input is needed:

# Blocked: need human help to proceed
agent-board update card card_123 --add-tag blocked --add-tag needs-human
agent-board create comment card_123 "BLOCKED: Need cost approval before provisioning"

# Review: work complete, want verification
agent-board update card card_123 --status pending-review
agent-board create comment card_123 "Ready for review: verify terraform plan"

Common tags: blocked, needs-human, expedite, security-review, cost-approval

Best Practices for Agents

1. Register identity first with agent-board create agent [name]
2. Set AGENT_BOARD_AGENT_ID before starting work
3. Use --assign-to-me when claiming a card to start work
4. Think Kanban - Cards represent discrete, deliverable work items that flow through the board
5. Add comments when starting, making progress, or completing work
6. Use descriptive card names that capture the task intent
7. Keep assignment on completion - Don't unassign when marking done (preserves history)
8. Check agent-board mine at session start to see pending work
9. Use --format json when you need to parse output programmatically
10. Use blocked + needs-human tags when you cannot continue without human input
11. Use pending-review status when work is done but you want human verification (optional)

Cards vs Checklists

Each card has a single checklist for tracking subtasks within that work item.

Simple task: "Add Docker support" → One card with checklist items (Dockerfile, compose, test, docs)

Complex task: "Migrate to microservices" → Multiple cards (auth service, payment service, API gateway, testing), each with its own checklist

Data Location

All data persists in a local SQLite database:

• Default: ~/.agent-board/data.db
• Override: Set AGENT_BOARD_DB_PATH environment variable

The database is created automatically on first use.