## 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

```
lightsage tasks create --title "Add a quickstart page for agents"
```

Add details, a type, and an assignee:

```
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

```
lightsage tasks list --output-format json
```

Filter by date or status:

```
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

```
lightsage tasks retrieve --task-id task_123
```

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

## Update a task

```
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.

The list filter accepts the normalized group `completed`. Updates use the concrete status `done`, not `completed`.