mastermind-monotask

Monotask CLI — Agent Reference (v1.1.4)

Monotask is a P2P local-first task manager. All data is stored in SQLite (~/.local/share/monotask/monotask.db). Always use --json for machine-readable output.

---

Global Flags

--data-dir <PATH>   Override storage directory (must be consistent per instance)

---

Board

# Create — returns {id, title, deep_link}
monotask board create "Sprint 42" --json

# List — returns [{id, title}] (search by title with jq .title)
monotask board list --json

# Rename
monotask board rename <BOARD_ID> "New Title" --json

---

Column

# Create — returns {id, board_id}
monotask column create <BOARD_ID> "Todo" --json

# List — returns [{id, title, card_ids:[]}]  ← field is "title", NOT "name"
monotask column list <BOARD_ID> --json

# Rename
monotask column rename <BOARD_ID> <COL_ID> "New Title" --json

# Delete (soft-deletes all cards in it)
monotask column delete <BOARD_ID> <COL_ID> --json

---

Card

Listing

# All cards in board (flat, includes col_id + col_title per card)
monotask card list <BOARD_ID> --json

# Filter by column (server-side, fast)
monotask card list <BOARD_ID> --col <COL_ID> --json

# Filter by label (server-side, exact match)
monotask card list <BOARD_ID> --label "role:writer" --json

# Combine filters
monotask card list <BOARD_ID> --col <TODO_COL> --label "role:reviewer" --json

JSON schema per item from card list:

{ "id":"<uuid>", "title":"<str>", "col_id":"<uuid>", "col_title":"<str>",
  "labels":[], "due_date":null, "impact":null, "effort":null, "direct_priority":null }

Create / View / Move

# Create — returns {id, title, board_id, number}
CARD=$(monotask card create <BOARD_ID> <COL_ID> "Task title" --json | jq -r .id)

# View full card (includes parent + subtasks)
monotask card view <BOARD_ID> <CARD_ID> --json

# Move to different column (auto-detects current column)
monotask card move <BOARD_ID> <CARD_ID> <TO_COL_ID> --json

# Copy to another column (same board)
monotask card copy <BOARD_ID> <CARD_ID> <TARGET_COL_ID> --json

# Rename
monotask card rename <BOARD_ID> <CARD_ID> "New title" --json

# Soft-delete (hidden from all views)
monotask card delete <BOARD_ID> <CARD_ID> --json

# Soft-archive (hidden from normal views)
monotask card archive <BOARD_ID> <CARD_ID> --json

Metadata

monotask card set-description <BOARD_ID> <CARD_ID> "Markdown text" --json
monotask card set-due-date    <BOARD_ID> <CARD_ID> "2026-06-01" --json  # "none" to clear
monotask card set-cover       <BOARD_ID> <CARD_ID> "#e74c3c" --json     # "none" to clear

Priority / Scoring

# ICE scoring: priority = floor((impact + 10 - effort) / 2), range 0–10
monotask card set-impact  <BOARD_ID> <CARD_ID> 8 --json
monotask card set-effort  <BOARD_ID> <CARD_ID> 3 --json

# Direct priority (bypasses impact/effort)
monotask card set-direct-priority <BOARD_ID> <CARD_ID> 9 --json
monotask card set-direct-priority <BOARD_ID> <CARD_ID> --clear --json

# Clear all scoring
monotask card clear-priority <BOARD_ID> <CARD_ID> --json

Labels

monotask card label add    <BOARD_ID> <CARD_ID> "role:writer" --json
monotask card label remove <BOARD_ID> <CARD_ID> "role:writer" --json
monotask card label list   <BOARD_ID> <CARD_ID> --json  # → ["str",...]

Convention for org agents:

• role:<role_id> — which role should handle this card
• claimed — card has been picked up by an agent (in Doing column)

Assignee

# PUBKEY = 64-char hex (get via: monotask profile show)
monotask card set-assignee <BOARD_ID> <CARD_ID> <PUBKEY> --json
monotask card set-assignee <BOARD_ID> <CARD_ID> none --json  # clear

Comments

monotask card comment add    <BOARD_ID> <CARD_ID> "text" --json
monotask card comment list   <BOARD_ID> <CARD_ID> --json
monotask card comment delete <BOARD_ID> <CARD_ID> <COMMENT_ID> --json

Subtasks (parent/child hierarchy)

# Create a subtask (new card linked as child of PARENT_CARD)
monotask card subtask add <PARENT_BOARD> <PARENT_CARD> <CHILD_BOARD> <COL_ID> "Subtask title" --json
# → returns {id, title, board_id}

# List subtasks of a card
monotask card subtask list <BOARD_ID> <CARD_ID> --json
# → [{board_id, card_id},...]

# card view includes "subtasks" and "parent" fields automatically

Prerequisites (dependency ordering)

# PREREQ_CARD must be Done before CARD can be claimed
monotask card prerequisite add    <BOARD_ID> <CARD_ID> <PREREQ_BOARD> <PREREQ_CARD_ID> --json
monotask card prerequisite list   <BOARD_ID> <CARD_ID> --json  # → [{board_id, card_id},...]
monotask card prerequisite remove <BOARD_ID> <CARD_ID> <PREREQ_BOARD> <PREREQ_CARD_ID> --json

Attachments

# Attach image (stored as base64; returns img:<6char-id> token for markdown)
ATT=$(monotask card attach-image <BOARD_ID> <CARD_ID> screenshot.png --json | jq -r .token)
monotask card set-description <BOARD_ID> <CARD_ID> "See: ![$ATT]($ATT)"

monotask card list-attachments <BOARD_ID> <CARD_ID> --json
monotask card save-attachment  <BOARD_ID> <CARD_ID> <ATTACHMENT_ID> --output ./out.png

Checklists

CL=$(monotask checklist add      <BOARD_ID> <CARD_ID> "Definition of Done" --json | jq -r .id)
ITEM=$(monotask checklist item-add   <BOARD_ID> <CARD_ID> $CL "Write tests" --json | jq -r .id)
monotask checklist item-check   <BOARD_ID> <CARD_ID> $CL $ITEM
monotask checklist item-uncheck <BOARD_ID> <CARD_ID> $CL $ITEM

---

Space (Collaboration)

# Create / list
monotask space create "Team Name"
monotask space list   # → "<id> | <name> | <N> members"
monotask space info <SPACE_ID>

# Associate boards
monotask space boards add    <SPACE_ID> <BOARD_ID>
monotask space boards remove <SPACE_ID> <BOARD_ID>
monotask space boards list   <SPACE_ID>

# Invite / join
monotask space invite export  <SPACE_ID> invite.space  # preferred (includes space doc)
monotask space invite generate <SPACE_ID>               # token only
monotask space invite revoke   <SPACE_ID>
monotask space join invite.space                        # or raw token

# Members
monotask space members list <SPACE_ID>
monotask space members kick <SPACE_ID> <PUBKEY>

---

GitHub Integration

monotask github connect ghp_yourtoken           # save token
monotask github repos                           # list accessible repos
monotask github link <BOARD_ID> <ORG> <REPO> --done-col <COL_ID>  # link repo
monotask github unlink <BOARD_ID>
monotask github sync <BOARD_ID>                 # bidirectional sync

---

Linear Integration

monotask linear connect lin_api_yourkey         # save key
monotask linear status
monotask linear teams                           # list teams
monotask linear projects <TEAM_ID>
monotask linear link <BOARD_ID> --team <TEAM_ID> --project <PROJECT_ID> [--done-col <COL_ID>]
monotask linear unlink <BOARD_ID>
monotask linear sync <BOARD_ID>                 # bidirectional sync

---

P2P Sync Daemon

monotask sync --detach --port 7272              # start background daemon
monotask sync --status
monotask sync --stop
monotask sync --peer /ip4/192.168.1.10/tcp/7272 # connect to known peer

---

Profile

monotask profile show
monotask profile set-name "Alice"
monotask profile set-avatar ~/avatar.png
monotask profile import-ssh-key ~/.ssh/id_ed25519  # changes pubkey — run before joining spaces

---

Common Agent Workflows

Set up an org task board

BOARD=$(monotask board create "org-tasks" --json | jq -r .id)
TODO=$(monotask column create $BOARD "Todo"  --json | jq -r .id)
DOING=$(monotask column create $BOARD "Doing" --json | jq -r .id)
DONE=$(monotask column create $BOARD "Done"  --json | jq -r .id)

Task assignment loop (boss agent pattern)

# List unclaimed Todo cards
monotask card list $BOARD --col $TODO --json | jq '[.[] | select(.labels | index("claimed") | not)]'

# Claim a card for a role agent
monotask card move $BOARD $CARD_ID $DOING
monotask card label add $BOARD $CARD_ID "claimed"

# Complete a card
monotask card move $BOARD $CARD_ID $DONE

# Find all cards for a specific role across all columns
monotask card list $BOARD --label "role:writer" --json

Check prerequisites before claiming

# Get prereqs of a card
PREREQS=$(monotask card prerequisite list $BOARD $CARD_ID --json)
# Check all prereqs are in Done column
echo "$PREREQS" | jq -r '.[].card_id' | while read PREREQ_ID; do
  COL=$(monotask card list $BOARD --json | jq -r --arg id "$PREREQ_ID" '.[] | select(.id==$id) | .col_id')
  [ "$COL" != "$DONE" ] && echo "BLOCKED: $PREREQ_ID not done" && exit 1
done

Find board by title

BOARD_ID=$(monotask board list --json | jq -r '.[] | select(.title=="org-tasks") | .id')

Find column by title (field is "title", NOT "name")

COLS=$(monotask column list $BOARD --json)
TODO=$(echo "$COLS" | jq -r '.[] | select(.title=="Todo") | .id')
DONE=$(echo "$COLS" | jq -r '.[] | select(.title=="Done") | .id')

---

ID Formats

Type	Format
Board / Column / Card / Space / Comment / Checklist	UUID v4
Attachment	6-char hex (reference as img:<id> in markdown)
Card number	<prefix>-<seq> — human display only; CLI requires full UUID

HLC Timestamps

All created_at fields use Hybrid Logical Clock format <wall_ms_hex>-<logical_hex>.

ms = parseInt(hlc.split('-')[0], 16)     // → Unix ms
new Date(ms).toISOString()               // → ISO date

Error Handling

All commands exit 0 on success, non-zero on error. Errors go to stderr (never mixed into --json stdout). Common causes: ID not found, invalid UUID, corrupted board file, invalid invite token.

Key Limitations

• CLI operates on local data only — P2P sync requires the desktop app or sync --detach
• card create uses placeholder prefix "aaaa" for card numbers (full identity wiring planned)
• No board delete command — orphaned boards must be removed via SQLite directly
• card move auto-detects current column — no need to specify source column