## Tasks

Create, list, retrieve, and update daily tasks from the Lightsage CLI.

Tasks are persisted daily action items with execution instructions. Use these commands to add tasks, inspect the task queue, and update task status.

## Commands

| Command | Description |
| - | - |
| `lightsage tasks create --title <title>` | Create a task. |
| `lightsage tasks list` | List tasks. |
| `lightsage tasks retrieve --task-id <task_id>` | Retrieve one task. |
| `lightsage tasks update --task-id <task_id>` | Update one task. |

## Create a task

```bash theme={null}
lightsage tasks create --title "Add a quickstart page for agents"
```

Add details, a type, and an assignee:

```bash theme={null}
lightsage tasks create \
  --title "Add a quickstart page for agents" \
  --description "Agents cannot find the setup steps from the docs home page." \
  --task-type Docs \
  --priority high \
  --assignee-user-id user_123
```

New tasks are added to today's queue with the status `new`. The response is the created task, including its execution prompt.

| Flag | Values | Default |
| - | - | - |
| `--title` | Up to 200 characters. Required. | |
| `--description` | Markdown, up to 10,000 characters. | |
| `--task-type` | `Create`, `Refresh`, `Win back`, `Outreach`, `Community`, `Docs`, `Redirect` | `Create` |
| `--effort` | `Low`, `Medium`, `High` | `Medium` |
| `--priority` | `urgent`, `high`, `medium`, `low` | `medium` |
| `--action-type` | `agent_discovery`, `agent_usability` | `agent_discovery` |
| `--assignee-user-id` | A member of your organization. | Unassigned |

The assignee gets an email about the task unless they have turned off task notifications.

## List tasks

```bash theme={null}
lightsage tasks list --output-format json
```

Filter by date or status:

```bash theme={null}
lightsage tasks list --action-date 2026-09-06 --status completed
```

List filters include `active`, `todo`, `new`, `in_progress`, `completed`, `done`, `dismissed`, and `all`.

The response includes per-status counts that are not narrowed by the `status` filter.

## Retrieve one task

```bash theme={null}
lightsage tasks retrieve --task-id task_123
```

The response includes the task's execution prompt and metadata.

## Update a task

```bash theme={null}
lightsage tasks update --task-id task_123 --status done
```

Update statuses are `new`, `in_progress`, `added_to_sheet`, `done`, `dismissed`, and `snoozed`. Only sent fields are changed; omitted fields remain unchanged.