> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues, comments, projects, and milestones

> Use the Atoll CLI to list, create, update, assign, archive, and comment on work.

The CLI uses `issue` for task commands because the API resource is named `issues`.

## List issues

```bash theme={null}
atoll issue list
atoll issue list --status todo --priority 1
atoll issue list --project project-uuid
atoll issue list --team team-slug
atoll issue list --milestone milestone-uuid --q login
atoll issue list --scope blocked --initiative initiative-uuid
atoll issue list --include-archived --order-by due_date --order-dir asc
atoll issue list --limit 50 --offset 50
```

In JSON mode, project-scoped issue lists include `project_context` with the project's board columns. Column `description` values are team-authored guidance for when work belongs in each stage.

## View an issue

```bash theme={null}
atoll issue view ATOLL-42
atoll issue get ATOLL-42
```

Identifiers can be UUIDs or human-readable identifiers like `ATOLL-42`.

In JSON mode, issue detail includes `status_column` for the current status and `project_context` when the issue belongs to a project.

## Create and update

```bash theme={null}
atoll issue create --title "Fix login bug" --status todo --priority 1
atoll issue create --title "Prepare launch checklist" --project project-slug --team marketing
atoll issue create --title "Plan rollout" --project project-slug --milestone "Launch"
atoll issue create --title "Weekly status review" --due-date 2026-07-06 --recurrence weekly
atoll issue create --title "Bug bash" --labels bug,qa
atoll issue update ATOLL-42 --status in_progress
atoll issue update ATOLL-42 --recurrence custom --recurrence-interval 14
atoll issue update ATOLL-42 --clear-recurrence
atoll issue update ATOLL-42 --status in_progress --comment-body "Starting this because the activation KPI is off pace."
atoll issue update ATOLL-42 --title "Fix OAuth callback" --priority 0
```

Use `--comment-body` or `--comment-body-file` with `issue update` when a status change should also leave a durable progress note, such as strategy evidence from a heartbeat recommendation.

`issue create --project` accepts a project ID, slug, or exact name. `issue create --milestone` accepts a milestone ID, or an exact milestone name when a project is selected with `--project` or the active profile's default project.

`--recurrence` accepts `daily`, `weekly`, `biweekly`, `monthly`, or `custom`. Use `--recurrence-interval` for a positive interval, and `--clear-recurrence` to remove recurrence settings.

## Labels

```bash theme={null}
atoll label list
atoll label create --name bug --color "#dc2626"
atoll label add ATOLL-42 bug
atoll label remove ATOLL-42 bug
```

`issue create --labels` accepts comma-separated label IDs or exact names. Existing tasks use `label add` and `label remove`.

## Notifications

```bash theme={null}
atoll notification list --json
atoll notification ack notification-uuid
```

Agents should acknowledge notifications after handling them so heartbeat attention items and notification lists stay actionable.

## Subtasks and activity

```bash theme={null}
atoll subtask list ATOLL-42
atoll subtask create ATOLL-42 --title "Verify recurrence"
atoll subtask update ATOLL-42 subtask-uuid --completed
atoll subtask delete ATOLL-42 subtask-uuid
atoll activity list --filter by_me --json
atoll activity issue ATOLL-42
```

## Plan files

Use `plan validate` and `plan apply` to sync a graph of milestones, issues,
dependencies, and initiative links from one JSON file.

```bash theme={null}
atoll plan validate --file ./plan.json
atoll plan apply --file ./plan.json --dry-run
atoll plan apply --file ./plan.json
```

Plan files use `schemaVersion: "atoll.plan.v1"` and local `key` values for
cross-resource references. Issue entries support the same planning fields agents
use on individual tasks, including `startDate`, `dueDate`, `recurrenceType`,
`recurrenceInterval`, `teamId`, `assigneeId`, and `assigneeIds`.

```json theme={null}
{
  "schemaVersion": "atoll.plan.v1",
  "project": "Atoll HQ",
  "issues": [
    {
      "key": "weekly-docs",
      "title": "Review and update docs",
      "status": "todo",
      "priority": 3,
      "dueDate": "2026-07-06",
      "recurrenceType": "weekly",
      "recurrenceInterval": 1
    }
  ]
}
```

`plan validate` checks schema version, duplicate keys, missing local references,
invalid priorities/statuses/dates, recurrence values, and dependency cycles
without contacting the API. `plan apply` upserts milestones by exact name,
upserts issues by identifier or exact title within the selected project, then
applies dependencies and initiative links. Duplicate dependencies and links are
reported as already satisfied so retries are safe.

## Assign and unassign

```bash theme={null}
atoll issue assign ATOLL-42 --to member-uuid
atoll issue assign ATOLL-42 --to self
atoll issue unassign ATOLL-42
```

## Archive and delete

Prefer reversible archive:

```bash theme={null}
atoll issue archive ATOLL-42
atoll issue unarchive ATOLL-42
```

Permanent delete requires `--force` and owner/admin permissions:

```bash theme={null}
atoll issue delete ATOLL-42 --dry-run
atoll issue delete ATOLL-42 --force
```

## Comments

```bash theme={null}
atoll comment list ATOLL-42
atoll comment add ATOLL-42 --body "Working on this now"
atoll comment add ATOLL-42 --body "tagging..." --mention-member <member-id>
atoll comment add ATOLL-42 --body "tagging..." --mention "Raphael Ubales"
atoll comment update comment-uuid --body "Updated note"
atoll comment delete comment-uuid --issue ATOLL-42 --dry-run
atoll comment delete comment-uuid --issue ATOLL-42 --force
```

Comments accept Markdown/plain text or rich-text HTML. Atoll stores and returns comment bodies as sanitized HTML, and rejects comments with no visible content after sanitization.

Use `--mention-member` to send a stable Atoll org member ID in the structured
mentions payload. Use `--mention` for exact display-name lookup; the command
fails before writing the comment if the name is ambiguous. API responses include
`mentions: { requested, created, skipped }` so scripts can verify mention fanout.

## Projects

```bash theme={null}
atoll project list
atoll project create "Growth" --description "Growth experiments" --color "#0F766E"
atoll project view project-uuid
atoll project get project-uuid
```

## Milestones

```bash theme={null}
atoll milestone list --project project-uuid
atoll milestone create "Launch docs" --project project-uuid --date 2026-06-30
```

## Project-scoped initiatives

```bash theme={null}
atoll initiative list --project project-uuid
atoll initiative create --title "Activation sprint" --project project-uuid
atoll initiative create --title "Org-wide planning" --org-wide
```

When a profile has a default project, `initiative list` and `initiative create` send that project automatically. Use `--project` to override it or `--org-wide` to suppress it. Guest/project-scoped agents must use a project they can edit when creating initiatives.

## Initiative targets

Targets track initiative commitments separately from business KPIs. Use progress targets for outputs and gate targets for launch prerequisites.

```bash theme={null}
atoll initiative target list "Retailer coverage"
atoll initiative target create "Retailer coverage" \
  --title "Get 5 retailers live by July 5" \
  --mode gate \
  --target 5 \
  --current 0 \
  --unit count \
  --unit-label retailers \
  --target-date 2026-07-05 \
  --due-soon-days 7
atoll initiative target issue link "Retailer coverage" "Get 5 retailers live by July 5" ATOLL-42
```