# Tasks

Use task commands for task lookup, creation, updates, and deletion.

## Commands

List tasks:

```bash
toggl --json tasks list --project-id <project-id>
toggl --json tasks list --project-id <project-id> --status-id <status-id>
```

Get one task:

```bash
toggl --json tasks get --task-id <task-id>
```

Create a task:

```bash
toggl --json tasks create --data '{"name":"Follow up with design","project_id":123456}'
```

Update a task with scalar payload flags:

```bash
toggl --json tasks update --task-id <task-id> --payload-name "Updated name"
toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
```

Update a task with a JSON payload:

```bash
toggl --json tasks update --data '{"task_id":12345,"payload":{"name":"Updated name","status_id":456789}}'
```

Delete a task only after explicit user confirmation:

```bash
toggl --json tasks delete --task-id <task-id> --yes
```

## Agent Workflow

When the user names a task but does not provide an ID, list tasks in the relevant project first. If multiple matches are plausible, ask before mutating.

When changing a task status, use `toggl --json statuses list` if the status ID is unknown.

Use `--dry-run` before non-trivial updates:

```bash
toggl tasks update --task-id <task-id> --payload-status-id <status-id> --dry-run
```

Prefer scalar flags for single-field updates. Prefer `--data -` or `--data-file` for multi-field payloads or names with tricky shell quoting.