---
name: task-cli
description: Track time and manage tasks — start/stop timers, list tasks, create tasks, get summaries, list projects. Use for any time tracking or task management request.
allowed-tools: Bash(task-cli:*)
---

# Task Management CLI

## Quick start

```bash
task-cli current                           # What timer is running?
task-cli list -s doing                     # List in-progress tasks
task-cli start <task_id> -d "Working on X" # Start timer
task-cli stop                              # Stop timer
task-cli projects                          # List internal projects
```

## Commands

### Check current timer

```bash
task-cli current
```

### List tasks

```bash
task-cli list                              # All tasks
task-cli list -s todo,doing                # Filter by status
task-cli list -c groupon                   # Filter by client
task-cli list -p ai-automations            # Filter by project
task-cli list -c business-ops -s doing     # Combine filters
```

### Get task details

```bash
task-cli get <task_id>
```

### Create a task

```bash
task-cli create -t "Task title" -c client -g "tag1,tag2" -d "Description"
task-cli create -t "AI workflow" -c business-ops -p ai-automations -d "Build new automation"
```

Flags:
- `-t` — title (required)
- `-c` — client name
- `-p` — project (for business-ops/internal tasks, see `task-cli projects`)
- `-g` — comma-separated tags
- `-d` — description

### Edit a task

```bash
task-cli edit <task_id> -t "New title"
task-cli edit <task_id> -c new-client -p new-project
task-cli edit <task_id> -s doing
task-cli edit <task_id> -g "tag1,tag2" -d "New description"
```

Flags (all optional, at least one required):
- `-t` — title
- `-c` — client
- `-p` — project
- `-g` — comma-separated tags
- `-d` — description
- `-s` — status (todo/doing/done)

### Move task status

```bash
task-cli move <task_id> todo|doing|done
```

### Delete a task

```bash
task-cli delete <task_id>
```

Permanently removes the task file. Stops the timer first if running on that task.

### Archive done tasks

```bash
task-cli archive
```

Moves all `done` tasks to `~/tasks/archive/YYYY-MM/`. This happens automatically when tasks are marked done, but can be run manually to catch stragglers.

### Search archived tasks

```bash
task-cli search-archive <query>
```

Searches through archived tasks by title, description, client, project, or tags.

### Start a timer

```bash
task-cli start <task_id>
task-cli start <task_id> -d "What I'm working on"
```

Auto-stops any running timer. Auto-moves task to `doing` if currently `todo`.

### Stop the running timer

```bash
task-cli stop
```

### Time summary

```bash
task-cli summary -s 2026-02-01 -e 2026-02-28
task-cli summary -s 2026-02-01 -e 2026-02-28 -c groupon
```

### List projects

```bash
task-cli projects
```

Shows available internal projects (from projects.json) that can be assigned to business-ops tasks.

### Manage todos

Add a todo item:
```bash
task-cli todo add <task_id> "Follow up with client"
```

Toggle a todo (check/uncheck by index):
```bash
task-cli todo toggle <task_id> 0
```

Remove a todo by index:
```bash
task-cli todo remove <task_id> 1
```

List todos for a task (included in `task-cli get`):
```bash
task-cli get <task_id>  # Todos shown in output
```

**API endpoints:**
- `POST /api/tasks/:id/todos` — body: `{ "text": "..." }` → adds unchecked todo
- `PATCH /api/tasks/:id/todos/:index` — body: `{ "done": true }` or `{ "text": "..." }` → update todo
- `DELETE /api/tasks/:id/todos/:index` → removes todo

**IPC commands:**
- `{ "type": "task_todo_add", "task_id": "...", "text": "..." }`
- `{ "type": "task_todo_toggle", "task_id": "...", "index": 0 }`
- `{ "type": "task_todo_remove", "task_id": "...", "index": 0 }`

## Task Statuses

- `todo` — Not started
- `doing` — In progress
- `done` — Completed