Skip to main content
The CLI uses issue for task commands because the API resource is named issues.

​
List issues

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

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

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

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

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

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. 
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. 
{
  "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

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: 
atoll issue archive ATOLL-42
atoll issue unarchive ATOLL-42
Permanent delete requires --force and owner/admin permissions: 
atoll issue delete ATOLL-42 --dry-run
atoll issue delete ATOLL-42 --force

​
Comments

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

atoll project list
atoll project create "Growth" --description "Growth experiments" --color "#0F766E"
atoll project view project-uuid
atoll project get project-uuid

​
Milestones

atoll milestone list --project project-uuid
atoll milestone create "Launch docs" --project project-uuid --date 2026-06-30

​
Project-scoped initiatives

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