Skip to content
agent-board-cli logo

Agent-Board CLI

agent-board-cli

Command-line task management tool for AI coding agents and humans. Provides local SQLite-based task boards for tracking work items, checklists, and comments without requiring an external API. Use this skill when: - Managing multi-step coding tasks - Tracking progress on complex implementations -...

SKILL.md

Full skill instructions

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 is auto-created when you use --assign-to-me or --status in-progress:

# Just start working - identity created automatically
agent-board update card card_xyz --status in-progress
# Note: Created agent identity agent_abc123 for this session.
#       To persist: export AGENT_BOARD_AGENT_ID=agent_abc123

# Set the env var to persist across commands
export AGENT_BOARD_AGENT_ID=agent_abc123

Or register explicitly:

# Register (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

# Set identity for session
export AGENT_BOARD_AGENT_ID=agent_abc123

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

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:

FormatUse Case
tableHuman-readable display (default)
jsonParsing with jq, programmatic access
simpleJust IDs, one per line, for scripting
# 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

StatusCLI ValueMeaning
TodotodoNot started
In Progressin-progressCurrently being worked on
Pending Reviewpending-reviewWork complete, awaiting review
DonedoneCompleted and reviewed

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

CodeMeaning
0Success
1General error
2Invalid arguments
4Not found (card, board, etc.)
5Permission denied
6Session conflict

Human Review (Optional)

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

ScenarioMechanismWhen
Blocked--add-tag blocked --add-tag needs-humanCannot continue without human input
Review--status pending-reviewWork done, want human verification
# 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.

Use CardsUse Checklists
Parallelizable workSequential steps in one deliverable
Different dependenciesShared dependencies
Independent status trackingLinear progress within a card

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.

More Productivity & Planning skills

brainstorming logo
Productivity & Planning

brainstorming

Structured design dialogue that validates ideas before implementation begins.

295.4K 385.7K
View
ui-ux-pro-max logo
Productivity & Planning

ui-ux-pro-max

Comprehensive design intelligence for web and mobile UI/UX across 10 technology stacks.

133.1K 383.9K
View
writing-plans logo
Productivity & Planning

writing-plans

Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.

295.4K 268K
View
using-superpowers logo
Productivity & Planning

using-superpowers

Introduction to the obra skills system with mandatory skill invocation rules and best practices.

295.4K 259.8K
View
executing-plans logo
Productivity & Planning

executing-plans

Execute a written implementation plan with critical review and task checkpoints.

295.4K 229.1K
View
dispatching-parallel-agents logo
Productivity & Planning

dispatching-parallel-agents

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K
View
using-git-worktrees logo
Productivity & Planning

using-git-worktrees

Isolated git worktrees with smart directory selection and safety verification.

295.4K 205.2K
View
webapp-testing logo
Productivity & Planning

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

179.7K 170.6K
View
content-strategy logo
Productivity & Planning

content-strategy

Plan searchable and shareable content that drives traffic, builds authority, and generates leads.

53.3K 150.9K
View
repo-intake-and-plan logo
Productivity & Planning

repo-intake-and-plan

README-first repository scanner that extracts commands and classifies reproduction candidates without executing them.

497 139.6K
View
marketing-ideas logo
Productivity & Planning

marketing-ideas

Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.

53.3K 137.2K
View
site-architecture logo
Productivity & Planning

site-architecture

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View

Productivity AI tools

Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View
SaveDay logo
Productivity

SaveDay

Capture, organize, and utilize your knowledge effortlessly.

Free
View
Any Summary logo
Productivity

Any Summary

Instant Summaries of Audio & Video Interviews with AnySummary

Freemium
View
M
Productivity

Map This

Transform PDFs into engaging mind maps.

Freemium
View
ChatPDF logo
Productivity

ChatPDF

Chat with any PDF instantly

Free
View
I
Productivity

intellisay

Create an optimal daily plan using your voice

Paid
View
A
Productivity

Aurora AI

A productivity platform to centralize organizational knowledge and workflows with contextual AI assistance.

Paid
View
AskYourPDF logo
Productivity

AskYourPDF

AskYourPDF Pricing Plans: Tailored to Your Needs

Free
View