Skip to content

CLI API Reference

Jump to bottom
alphaelements edited this page Jun 30, 2026 · 1 revision

CLI API Reference

Since v0.15.0, all 37 MCP tools are callable directly from the shell:

handoff-mcp <group> <action> [--key value ...]

Output is JSON on stdout. Errors return exit code 1 with a JSON {"error": "..."} object.

Global options

Flag Description
--project-dir <path> Project directory (default: current directory)
--help Show help (works at any position)

Commands

init

handoff-mcp init --project-name "My Project"

task

Action Example
list handoff-mcp task list --status-filter todo
get handoff-mcp task get --task-id t1
update handoff-mcp task update --id t1 --title "New task" --status todo --priority high --estimate-hours 2
check handoff-mcp task check --task-id t1 --criterion-index 0 --checked true
bulk-update handoff-mcp task bulk-update --updates '[{"task_id":"t1","status":"done"}]'
log-time handoff-mcp task log-time --task-id t1 --hours 0.5
import handoff-mcp task import --source '{"description":"import"}' --tasks '[{"title":"Task"}]'

session

Action Example
load handoff-mcp session load
save handoff-mcp session save --summary "Done" --session-status active
list handoff-mcp session list --status-filter active
get handoff-mcp session get --session-id s-20260630-...
update handoff-mcp session update --add-decision '{"decision":"Use X","reason":"..."}'

config

Action Example
get handoff-mcp config get
update handoff-mcp config update --updates '{"settings.history_limit":50}'

memory

Action Example
save handoff-mcp memory save --text "Always use atomic_write" --kind lesson --tags safety,io
query handoff-mcp memory query --text "atomic" --limit 5
delete handoff-mcp memory delete --id m-20260630-...
cleanup handoff-mcp memory cleanup --stale-days 60

referral

Action Example
send handoff-mcp referral send --target-project other-proj --summary "Need X"
list handoff-mcp referral list --status-filter open
get handoff-mcp referral get --referral-id ref-...
update handoff-mcp referral update --referral-id ref-... --status resolved

assignee

Action Example
list handoff-mcp assignee list
add handoff-mcp assignee add --key alice --display-name "Alice Smith"
update handoff-mcp assignee update --key alice --color "#ff0000"
remove handoff-mcp assignee remove --key alice

milestone

Action Example
list handoff-mcp milestone list
add handoff-mcp milestone add --name M1 --date 2026-07-15
update handoff-mcp milestone update --name M1 --description "Updated"
remove handoff-mcp milestone remove --name M1

calendar

handoff-mcp calendar update --work-hours-per-day 6

labels

handoff-mcp labels update --labels cli,feature,bug

project

handoff-mcp project start --start-date 2026-06-30 --shift-dates true

metrics

handoff-mcp metrics --assignee alice

capacity

handoff-mcp capacity --start-date 2026-06-30 --end-date 2026-07-05

schedule

handoff-mcp schedule --dry-run true

dashboard

handoff-mcp dashboard

timer

Action Example
start handoff-mcp timer start --task-id t1
stop handoff-mcp timer stop --task-id t1
get handoff-mcp timer get --task-id t1

Flag conventions

  • Dashes in flag names map to underscores: --project-dir becomes project_dir
  • Boolean: --force (no value = true), --dry-run true, --dry-run false
  • Arrays: --tags a,b,c (comma-separated) or --tags '["a","b","c"]' (JSON)
  • Nested objects: pass as JSON string, e.g. --updates '{"settings.x": 1}'
  • Numbers: only coerced for known numeric fields (hours, limit, estimate-hours, etc.)
  • All other values stay as strings (IDs, names, dates are never coerced to numbers)

Clone this wiki locally