Board Commands
Manage tasks on the Kanban board backed by Supabase. Create, update, claim, and track tasks across projects with support for agents, priorities, labels, and an activity log.
Task Hierarchy
The board supports a three-level hierarchy via the task_type field:
- Epic -- Large initiative or feature area. Contains stories.
- Story -- A deliverable piece of work within an epic. Contains tasks.
- Task -- An actionable unit of work (default type).
Use --type when creating items and --parent to place them in the hierarchy. Use board tree to visualize the hierarchy.
Commands
board view
Display the kanban board, optionally filtered by project, status, or type.
# View the full board
optimal board view
# Filter by project
optimal board view --project marketing
# Show only in-progress tasks assigned to you
optimal board view --status in_progress --mine bot1
# Filter by task type
optimal board view --type epic
# Show hierarchical tree view
optimal board view --hierarchy
# Filter multiple statuses
optimal board view --status ready,in_progress
# Watch mode — auto-refresh every 30 seconds
optimal board view --watch
# Output as JSON for scripting
optimal board view --json| Flag | Description |
|---|---|
-p, --project | Filter by project slug |
-s, --status | Filter by status (comma-separated: todo, ready, in_progress, done, blocked) |
--mine | Show only tasks claimed by the specified agent |
--type | Filter by task type: epic, story, or task |
--hierarchy | Show hierarchical tree view |
-w, --watch | Auto-refresh the board display |
--interval | Watch refresh interval in seconds (default: 30) |
-j, --json | Output raw JSON |
board create
Create a new task (or epic/story) on the board.
# Create a basic task
optimal board create -t "Update API docs" -p docs
# Create with priority and labels
optimal board create -t "Fix login timeout" -p backend --priority 1 --labels bug,auth
# Create an epic
optimal board create -t "Content Platform v2" -p content --type epic
# Create a story under an epic
optimal board create -t "RSS scraping module" -p content --type story --parent <epic-uuid>
# Create a task under a story
optimal board create -t "Add Twitter feed parser" -p content --type task --parent <story-uuid>
# Create with a skill requirement for agent matching
optimal board create -t "Generate social posts" -p content --skill content-gen
# Create with effort estimate and blocking dependencies
optimal board create -t "Migrate auth" -p cli --effort m --blocked-by <uuid1>,<uuid2>| Flag | Description |
|---|---|
-t, --title | Task title (required) |
-p, --project | Project slug (required) |
-d, --description | Task description |
--priority | Priority 1-4 (1 = highest, default: 3) |
--type | Task type: epic, story, or task (default: task) |
--parent | Parent task ID (for stories under epics, tasks under stories) |
--skill | Skill reference for agent matching |
--source | Source repo |
--target | Target module |
--effort | Effort estimate: xs, s, m, l, xl |
--blocked-by | Comma-separated blocking task IDs |
--labels | Comma-separated label names |
board update
Update an existing task's status, assignment, or other fields.
# Move a task to in-progress
optimal board update --id <uuid> -s in_progress
# Reassign a task to a different agent
optimal board update --id <uuid> -a content-bot
# Update with a log message
optimal board update --id <uuid> -s done -m "Completed migration"
# Set a due date
optimal board update --id <uuid> --due-date 2026-04-15
# Clear a due date
optimal board update --id <uuid> --due-date none| Flag | Description |
|---|---|
--id | Task ID (required) |
-s, --status | New status |
-t, --title | New title |
-a, --agent | Assign to agent |
--priority | New priority (1-4) |
--project | Project ID |
--due-date | Due date (YYYY-MM-DD) or none to clear |
--source-repo | Source repo |
--target-module | Target module |
--effort | Estimated effort (s, m, l) |
-m, --message | Log message (adds a comment) |
board claim
Claim an unassigned task. Marks it as yours (or as a specific agent's).
# Claim a task as yourself
optimal board claim --id 42
# Claim on behalf of an agent
optimal board claim --id 42 --agent finance-bot| Flag | Description |
|---|---|
--id | Task ID (required) |
--agent | Agent name to assign (defaults to current user) |
board auto-claim
Cron-friendly worker that claims unassigned, ready-to-work tasks for a named agent up to a concurrency cap. Designed to be invoked from a systemd timer or optimal doctor --fix cron entry.
# Default: claim up to 2 sessions for the openclaw-cron agent
optimal board auto-claim
# Custom agent + concurrency
optimal board auto-claim --agent claude-code --max-sessions 4| Flag | Description |
|---|---|
--agent | Agent name to claim under (default: openclaw-cron). |
--max-sessions | Maximum concurrent sessions; the worker exits early if at or above this count (default: 2). |
board delete
Delete a task from the board.
# Preview what would be deleted
optimal board delete --id 42 --dry-run
# Delete without confirmation prompt
optimal board delete --id 42 --yes| Flag | Description |
|---|---|
--id | Task ID (required) |
--dry-run | Show what would be deleted without executing |
--yes | Skip confirmation prompt |
WARNING
Deleting a task also removes its comments and activity log entries. Use --dry-run first to verify.
board comment
Add a comment to a task.
optimal board comment --id 42 --author oracle --body "Blocked on API rate limits"| Flag | Description |
|---|---|
--id | Task ID (required) |
--author | Comment author name |
--body | Comment text |
board log
View the activity log for tasks.
# View recent activity
optimal board log --limit 20
# Filter by a specific task
optimal board log --task 42
# Filter by actor
optimal board log --actor content-bot| Flag | Description |
|---|---|
--task | Filter by task ID |
--actor | Filter by actor name |
--limit | Number of entries to show |
board stats
Display task statistics — counts by status, assignments, and more.
# Stats for all projects
optimal board stats
# Stats for a specific project
optimal board stats --project backend| Flag | Description |
|---|---|
--project | Filter stats by project |
board tui
Launch the interactive TUI (terminal user interface) menu for board management.
optimal board tuiTIP
The TUI provides a menu-driven interface for all board operations. Useful when you want to browse and act on tasks without remembering individual commands.
board tree
Show the epic/story/task tree for a given epic or story. Displays the root item and all its children and grandchildren in a hierarchical view.
# Show tree for an epic
optimal board tree --id <epic-uuid>
# Output as JSON
optimal board tree --id <epic-uuid> --json| Flag | Description |
|---|---|
--id | Epic or story ID (required) |
--json | Output as JSON |