type

reference

domain

clear

audience

practitioner

stability

structural

authority

provenance	verifiability	evidence	currency
institutional	executable	moderate	undated

epistemic-layer

practice

CLI Reference

Complete command reference for Task. For a quick start, see the README.

Global Options

All commands support these options:

Option	Description
`--json`	Output in JSON format
`--attach <url>`	Connect to external server
`--help`	Show help for command
`--version`	Show version number

Task Commands

`task add <title> [description]`

Create a new task.

task add "Buy groceries" --project "Personal" --due "2025-12-31"
task add "Fix login bug" --tag bug --tag auth
task add "Submit report" --due "next friday"

Option	Description
`-p, --project <name>`	Assign to project (creates if doesn't exist)
`-P, --parent <id>`	Set as subtask of another task
`-d, --due <date>`	Set due date (ISO 8601 or natural language)
`-t, --tag <name>`	Add tag (can be used multiple times)
`-r, --recurrence`	Set recurrence pattern

`task list`

List tasks with optional filtering.

task list                              # Active tasks
task list -a                           # All tasks including done
task list -q "groceries"               # Text search
task list --overdue                    # Overdue tasks
task list --status in-progress         # Filter by status
task list --priority 2                 # Filter by priority
task list --tag bug                    # Filter by tag
task list -s "API integration" -n 5    # Semantic search

Option	Description
`-a, --all`	Show all tasks including completed
`-p, --project <name>`	Filter by project
`-t, --tag <name>`	Filter by tag
`-q, --search <text>`	Search in title and description
`--due-before <date>`	Tasks due before date (YYYY-MM-DD)
`--due-after <date>`	Tasks due after date (YYYY-MM-DD)
`--overdue`	Show only overdue tasks
`--priority <level>`	Filter by priority: 0 (Normal), 1 (High), 2 (Urgent)
`--status <status>`	Filter by status: todo, in-progress, done
`-s, --semantic <query>`	Semantic search (requires embedding provider)
`-n, --limit <number>`	Limit results, 1-100 (semantic defaults to 10)

`task view <id>`

View task details including subtasks, comments, and attachments.

task view 42
task view 42 --json

`task update <id>`

Update a task.

task update 1 --status done
task update 1 --title "New title"
task update 42 --project "Work"
task update 42 --recurrence "every Monday"
task update 42 --clear-recurrence
task update 42 --clear-project

Option	Description
`-t, --title <title>`	Set new title
`-D, --description <desc>`	Set new description
`-s, --status <status>`	Set status: todo, in-progress, done
`-p, --priority <level>`	Set priority: 0 (Normal), 1 (High), 2 (Urgent)
`-d, --due <date>`	Set due date
`--project <name>`	Move task to project (creates if needed)
`--clear-project`	Remove task from its project
`-r, --recurrence <rule>`	Set recurrence pattern
`--clear-recurrence`	Remove recurrence

Deleting tasks

There is no standalone delete command — deletion goes through task bulk delete, for one task or many. Subtasks are cascade-deleted with their parent:

task bulk delete 42 --yes        # Delete single task
task bulk delete 1 2 3 --yes     # Delete multiple tasks

`task comment <id> <content>`

Add a comment to a task.

task comment 1 "Purchased organic vegetables"

`task attach <id> <filepath>`

Attach a file to a task.

task attach 1 ./receipt.pdf

Bulk Operations

`task bulk update <ids...>`

Update multiple tasks at once.

task bulk update 1 2 3 --status done
task bulk update 1 2 3 --priority 2

Option	Description
`-s, --status <status>`	Set status: todo, in-progress, done
`-p, --priority <level>`	Set priority: 0 (Normal), 1 (High), 2 (Urgent)

`task bulk delete <ids...>`

Delete multiple tasks at once.

task bulk delete 4 5 6 --yes

Option	Description
`-y, --yes`	Skip confirmation

`task complete-subtasks <id>`

Mark all subtasks of a task as done.

task complete-subtasks 1

Batch Operations

`task batch-add`

Create multiple tasks with subtasks in a single operation.

task batch-add --file tasks.json
echo '{"tasks":[...]}' | task batch-add

Option	Description
`-f, --file`	Read JSON input from file

Input format:

{
  "tasks": [
    {
      "title": "Main task",
      "description": "Optional description",
      "project": "ProjectName",
      "due_date": "2025-12-31",
      "due_date_natural": "next friday",
      "priority": 1,
      "tags": ["bug", "auth"],
      "context": {
        "files": [{ "path": "/src/auth.ts", "line_start": 10 }],
        "tags": ["auth", "security"]
      },
      "subtasks": [
        { "title": "Subtask 1" },
        { "title": "Subtask 2", "priority": 2 }
      ]
    }
  ]
}

Tag Management

`task tag list`

List all tags with usage counts.

`task tag add <taskId> <tags...>`

Add one or more tags to a task.

task tag add 1 bug priority

`task tag remove <taskId> <tag>`

Remove a tag from a task.

task tag remove 1 priority

`task tag rename <tagId> <newName>`

Rename a tag by ID.

task tag rename 3 "high-priority"

`task tag delete <tagId>`

Delete a tag.

task tag delete 3

Projects

There is no task project command. Projects are created implicitly the first time they are referenced:

task add "New task" --project "Work"       # Creates "Work" if needed
task update 42 --project "Work"            # Same on update
task list --project "Work"                 # Filter by project

Database Management

`task db list`

List all databases with task/project counts.

`task db create <name>`

Create a new database. Names must be lowercase with numbers, hyphens, or underscores.

`task db use <name>`

Switch to a different database.

`task db current`

Show the active database.

`task db rename <old> <new>`

Rename a database.

`task db delete <name>`

Delete a database (with confirmation).

Embeddings & Semantic Search

`task embeddings status`

Show embedding coverage statistics for tasks and comments.

`task embeddings backfill`

Generate embeddings for all tasks that don't have them.

`task embeddings provider`

Show current embedding provider configuration.

Semantic search usage:

task list --semantic "tasks about API integration"
task list -s "bug fixes" --limit 5

Google Calendar Integration

`task gcal auth`

Authenticate with Google (OAuth 2.0).

`task gcal status`

Check authentication status.

`task gcal logout`

Clear stored credentials.

`task gcal calendars`

List available calendars.

`task gcal sync [taskId]`

Sync a task (or all unsynced tasks with due dates) to Google Calendar.

task gcal sync 42                    # Use due_date, 1 hour duration
task gcal sync 42 --duration 2       # Custom duration
task gcal sync 42 --calendar "Work"  # Specific calendar
task gcal sync 42 --datetime "tomorrow 14:00" --duration 1.5  # Override date
task gcal sync --all                 # Sync all unsynced tasks with due dates

Option	Description
`--all`	Sync all unsynced tasks with due dates
`-d, --duration <hrs>`	Event duration in hours, 0-24 (default: 1)
`-c, --calendar <id>`	Target calendar ID (default: configured)
`--datetime <datetime>`	Override due date (natural language)
`--attach <url>`	Sync against an external server

If a synced event was deleted in Google Calendar, the next sync creates a fresh event and re-links the task.

`task gcal use <calendar-id>`

Set default calendar for future syncs.

Git Sync

`task sync init [remote-url]`

Initialize git repo in ~/.task-cli/ for syncing.

`task sync status`

Check sync status (branch, remote, ahead/behind).

`task sync push [-m <message>]`

Commit and push changes.

`task sync pull [--force]`

Pull changes from remote.

Workspace Automation

`task work <id>`

Create a workspace for a task and start working.

task work 42                               # Create workspace, open IDE
task work 42 --template python             # Use built-in template
task work 42 --template "Knowledge Work"   # Use configured external template
task work 42 --name my-project             # Custom directory name
task work 42 --no-open                     # Create but don't open IDE
task work 42 --open                        # Open existing workspace
task work 42 --list-templates              # Show available templates

Option	Description
`-t, --template <name>`	Use specific template (built-in or configured)
`-n, --name <name>`	Custom workspace name (default: id-slug)
`--no-open`	Create workspace but don't open IDE
`-o, --open`	Open existing workspace in IDE
`--list-templates`	List available templates (built-in and configured)

Default workspace structure (built-in templates):

~/git/42-fix-auth-bug/
├── .git/
├── README.md           # Task context for humans
├── CLAUDE.md           # Instructions for AI assistants
├── input/              # Attachments and reference materials
│   └── .task-ref.json  # Bidirectional link back to task
└── output/             # Place deliverables here

External template workspace structure:

When using a configured external template, files are copied from the template directory. Only .task-ref.json is added; no README.md, CLAUDE.md, or input/output directories are generated. Template variables like {{task.id}} are substituted in text files.

See How to Use Workspace Templates and Configuration Reference for setup.

Task Sharing

`task share <id>`

Output a formatted prompt for sharing with AI agents.

task share 42                    # Default template
task share 42 --template work    # Custom template
task share 42 --raw              # Raw JSON
task share 42 --list-templates   # List templates

Option	Description
`-t, --template <name>`	Use named template from ~/.task-cli/templates/
`--raw`	Output raw JSON instead of formatted prompt
`--list-templates`	List available templates

Reports

`task report`

Generate activity reports.

task report --period week      # Current calendar week
task report --period month     # Current calendar month
task report --period quarter   # Current calendar quarter
task report --from 2025-01-01 --to 2025-01-31  # Custom range
task report --period week --project "My Project"  # Filter by project
task report --period week --json  # JSON output

Option	Description
`--period <period>`	week, month, or quarter
`--from <date>`	Start date (YYYY-MM-DD)
`--to <date>`	End date (YYYY-MM-DD)
`--project <name>`	Filter by project

Statistics

`task stats`

Show task statistics including counts by status, priority, and project.

Server & Modes

`task serve`

Start the HTTP API server.

task serve --port 3000

Option	Description
`--port <number>`	Port to listen on (default: 3000)
`--hostname <string>`	Hostname to bind to (default: 127.0.0.1)

`task tui`

Start the interactive terminal UI.

task tui
task tui --attach http://localhost:3000

Option	Description
`--attach <url>`	Connect to external server
`--port <number>`	Port for local server (if not attaching)

Maintenance

`task truncate`

Delete all data from the database.

Option	Description
`--yes`	Skip confirmation prompt

`task upgrade`

Check for and install updates.

task upgrade           # Check and install latest version
task upgrade --check   # Only check, don't install

Connecting to External Server

CLI commands can connect to an existing server:

task list --attach http://localhost:3000
task add "Remote task" --attach http://localhost:3000

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Global Options

Task Commands

task add <title> [description]

task list

task view <id>

task update <id>

Deleting tasks

task comment <id> <content>

task attach <id> <filepath>

Bulk Operations

task bulk update <ids...>

task bulk delete <ids...>

task complete-subtasks <id>

Batch Operations

task batch-add

Tag Management

task tag list

task tag add <taskId> <tags...>

task tag remove <taskId> <tag>

task tag rename <tagId> <newName>

task tag delete <tagId>

Projects

Database Management

task db list

task db create <name>

task db use <name>

task db current

task db rename <old> <new>

task db delete <name>