@task-compass/cli

Agent-first command line for Task Compass — operate your tasks, habits, and notes from a terminal or an AI agent. Requires a Task Compass sync account and Node ≥ 20.

npx @task-compass/cli --help

Login

Auth is an emailed one-time code, two-step so agents can drive it:

task-compass login --email [email protected]   # sends a 6-digit code
task-compass login --code 123456             # verifies it
task-compass whoami

On an interactive terminal, plain task-compass login prompts inline. The session is stored in ~/.config/task-compass/ and is fully independent of your web session — logout revokes only this device.

Commands

| Command | What it does | |---|---| | list | All live tasks. --status new\|open\|snoozed\|done, --tag <name\|id>, --query <text>, --limit <n> | | next | The focus queue head — what to work on now. --limit <n>, --tag <name\|id> | | get <id> | One task with its position-ordered subtasks | | create | --title <text> (required), --description <text>, --parent <id> for a subtask | | update <id> | --title, --description, --priority true\|false, --add-tag, --remove-tag, --subtask-mode list\|sequence | | complete <id> | Mark done; --comment <text> adds a comment. Habits record lastCompleted automatically | | reopen <id> | Back to open, clears snooze | | snooze <id> | --until <ISO datetime> or --hours <n>; --comment <text> | | comment <id> <text…> | Add a comment to the task history | | delete <id…> | Soft-delete. Batches over the mass-delete guard need --force; single deletes always pass | | tag list | List live tags (apply them via update --add-tag) | | login / logout / whoami | Session management |

JSON mode and exit codes

Every command takes --json and prints exactly one envelope to stdout:

{"ok": true, "data": …}
{"ok": false, "error": {"code": "not_found", "message": "No task with id …"}}

Exit codes map 1:1 to error.code, so scripts can branch without parsing:

| Exit | error.code | Meaning | |---|---|---| | 0 | — | success | | 1 | validation | bad input value, invalid state transition | | 2 | usage | unknown command/flag, missing required flag | | 3 | not_authenticated | no session — run task-compass login | | 4 | session_expired | refresh rejected — log in again | | 5 | network | request failed; at most one retry happened | | 6 | not_found | task/tag id or name didn't resolve | | 7 | guard_refused | mass-delete guard tripped without --force | | 8 | sync_denied | the account has no sync access |

list and next include computed effectiveStatus and dueForReopen fields: a done habit that is due again behaves as open without the CLI mutating anything — your view matches the web app's even when no tab is open.

Configuration

Production is built in. For a local/self-hosted Supabase backend:

| Env var | Default | |---|---| | TASK_COMPASS_SUPABASE_URL | production project URL | | TASK_COMPASS_SUPABASE_KEY | production publishable key | | TASK_COMPASS_CONFIG_DIR | ~/.config/task-compass |