Tasks, Projects, and Cycles

The task, project, and cycle commands work with the same tasks you see in Octarine's Tasks view. They read and write the task files under .octarine/tasks through the same storage code as the desktop app. An open Octarine window picks up the changes on its own, so you can run these commands while the app is open.

Markdown checkboxes inside notes (- [ ] Item) are separate from managed tasks. List them across the workspace with checkbox list and change one with note task set.

How Things Are Addressed

Thing	Accepted forms
Task	Its ID, such as `WEB-24`: the project's key and the task's number in that project. Tasks outside any project use the workspace key, `TASK-3` by default. A bare `24` works only when exactly one project has a task 24. The task's internal ID also works.
Project	Its key (`WEB`), its name ignoring case (a unique part of the name also works), or its ID.
Status	Its name (`In progress`) or ID (`in-progress`).
Label	Its name.
Bucket, template, filter, cycle	Their name or ID. Cycles also accept `current`, `upcoming`, `previous`, and a cycle number.

When a task moves to another project, it takes the next number there (WEB-1 becomes MOB-1), and its old ID keeps finding it. IDs are otherwise stable, so they are safe to mention in notes and commit messages.

Field values

Field	Values
`--priority`	`urgent`, `high`, `medium`, `low`, `none`, or the numbers `1` to `4` and `0`
`--due`	`YYYY-MM-DD`, `today`, `tomorrow`, or `+Nd` (such as `+3d`)
`--state` / `--status`	Any status name or ID from `task statuses`
`--cycle`	`current`, `upcoming`, a cycle number, name, or ID
Colours (`--color`)	A colour name such as `blue`, `coral`, `purple`, `green`, `red`, or `orange`
Icons (`--icon`)	A Lucide icon name, such as `lucide:Rocket` or `lucide:Bug`

Task Commands

`task list`

List tasks. Without filters, it lists every unarchived task, ordered by ID.

octarine task list [--project <project> | --no-project] [--state <status>]... [--open | --closed]
                   [--label <label>]... [--bucket <bucket>] [--cycle <cycle>] [--parent <task>]
                   [--search <text>] [--completed-within <Nd>] [--archived]
                   [--sort number|priority|due|updated|status] [--limit <n>]

Option	Effect
`--project` / `--no-project`	Tasks in one project, or only tasks without a project
`--state`	Tasks with this status; repeat for several
`--open` / `--closed`	Only open tasks, or only completed and cancelled tasks
`--label`	Tasks with this label; repeat to require several
`--bucket`	Tasks in one bucket
`--cycle`	Tasks planned in a cycle. Also accepts `none` and `previous`.
`--parent`	Only the subtasks of one task
`--search`	Text to find in titles and descriptions
`--completed-within`	Tasks completed in the last N days, such as `7d`
`--archived`	List archived tasks instead
`--sort`	`number` (default), `priority`, `due`, `updated`, or `status`

octarine task list
octarine task list --project WEB --open --sort priority
octarine task list --state in-progress --label Bug
octarine task list --cycle current --open
octarine task list --completed-within 7d --sort updated

# Every task (shown with --fields identifier,status,priority,labels,due,title)
╭────────────┬────────────┬────────┬──────────┬────────┬───────────────────────╮
│ due        ┆ identifier ┆ labels ┆ priority ┆ status ┆ title                 │
╞════════════╪════════════╪════════╪══════════╪════════╪═══════════════════════╡
│ 2026-11-20 ┆ TASK-1     ┆        ┆ none     ┆ Todo   ┆ Renew domain          │
│ 2026-11-10 ┆ WEB-1      ┆ Bug    ┆ high     ┆ Todo   ┆ Fix sync conflict     │
│ —          ┆ WEB-2      ┆        ┆ none     ┆ Todo   ┆ Ship 1.2              │
│ —          ┆ WEB-3      ┆        ┆ none     ┆ Todo   ┆ Changelog             │
│ —          ┆ WEB-4      ┆        ┆ none     ┆ Todo   ┆ Tag release           │
│ —          ┆ WEB-5      ┆        ┆ medium   ┆ Todo   ┆ Write onboarding copy │
╰────────────┴────────────┴────────┴──────────┴────────┴───────────────────────╯

# Open Website tasks by priority
╭────────────┬────────────┬────────┬──────────┬────────┬───────────────────────╮
│ due        ┆ identifier ┆ labels ┆ priority ┆ status ┆ title                 │
╞════════════╪════════════╪════════╪══════════╪════════╪═══════════════════════╡
│ 2026-11-10 ┆ WEB-1      ┆ Bug    ┆ high     ┆ Todo   ┆ Fix sync conflict     │
│ —          ┆ WEB-5      ┆        ┆ medium   ┆ Todo   ┆ Write onboarding copy │
│ —          ┆ WEB-2      ┆        ┆ none     ┆ Todo   ┆ Ship 1.2              │
│ —          ┆ WEB-3      ┆        ┆ none     ┆ Todo   ┆ Changelog             │
│ —          ┆ WEB-4      ┆        ┆ none     ┆ Todo   ┆ Tag release           │
╰────────────┴────────────┴────────┴──────────┴────────┴───────────────────────╯

Each row includes identifier, title, status, priority, labels, due, bucket, project, parent, number, and the internal id. Use --fields to keep only the columns you need.

octarine task list --label Bug --json

{"data":[{"bucket":null,"due":"2026-11-10","id":"xwpfw1g0od32d8f5l33cbw8b","identifier":"WEB-1","labels":["Bug"],"number":1,"parent":null,"priority":"high","project":"Website","status":"Todo","title":"Fix sync conflict"}],"meta":{"truncated":false},"ok":true,"schemaVersion":1}

`task show`

Show one task with its description, subtasks, resources, and revision. Add --activity to include comments and history.

octarine task show WEB-1
octarine task show WEB-1 --activity --json

# Shown with --fields identifier,title,status,priority,labels,due,project,reference,revision
╭────────────┬──────────────────────────────────────────────────────────────────╮
│ Field      ┆ Value                                                            │
╞════════════╪══════════════════════════════════════════════════════════════════╡
│ due        ┆ 2026-11-10                                                       │
│ identifier ┆ WEB-1                                                            │
│ labels     ┆ Bug                                                              │
│ priority   ┆ high                                                             │
│ project    ┆ Website                                                          │
│ reference  ┆ [[tasks:xwpfw1g0od32d8f5l33cbw8b]]                               │
│ revision   ┆ 566c10d1e6d7c254f0120ed1e614d7f0c90ad7094e7a55ba6571999cbdee1681 │
│ status     ┆ Todo                                                             │
│ title      ┆ Fix sync conflict                                                │
╰────────────┴──────────────────────────────────────────────────────────────────╯

The full result also includes description, category (the status's category), subtasks, resources, cycle, bucket, parent, archived, created, updated, and completed once the task is closed. reference is the link to paste into a note to link the task.

`task create`

Create a task with its fields in one call.

octarine task create <title> [--project <project>] [--state <status>] [--priority <priority>]
                     [--label <label>]... [--due <date>] [--bucket <bucket>] [--cycle <cycle>]
                     [--template <template> | --no-template] [--parent <task>]
                     [--subtask <title>]... [--description <markdown> | --stdin]

octarine task create "Fix sync conflict" --project WEB --label Bug --priority high --due 2026-11-10
octarine task create "Ship 1.2" --project WEB --subtask Changelog --subtask "Tag release"
octarine task create "Release 1.3" --template Release
octarine task create "Polish onboarding" --cycle current
echo "## Steps" | octarine task create "Repro crash" --project WEB --stdin

# Shown with --fields identifier,title,status,subtasks
╭────────────┬─────────────────────────────────────────────────────────────────────────────╮
│ Field      ┆ Value                                                                       │
╞════════════╪═════════════════════════════════════════════════════════════════════════════╡
│ identifier ┆ WEB-2                                                                       │
│ status     ┆ Todo                                                                        │
│ subtasks   ┆ [{"identifier":"WEB-3","title":"Changelog",…},{"identifier":"WEB-4",…}]     │
│ title      ┆ Ship 1.2                                                                    │
╰────────────┴─────────────────────────────────────────────────────────────────────────────╯

New tasks start in Todo unless you pass --state.
Pass --subtask once per subtask, or --parent to file the new task under an existing one. Subtasks go one level deep and always share their parent's project.
--template starts from a template; options you pass win over the template's values. A task created in a project with a default template starts from it unless you pass --template or --no-template.
--cycle requires cycles to be turned on with cycle settings --enable.

`task update`

Change only the fields you pass. Several task IDs apply the same change to each.

octarine task update <task>... [--title <title>] [--project <project> | --no-project]
                     [--state <status>] [--priority <priority>]
                     [--label <label>... | --add-label <label>... | --remove-label <label>...]
                     [--due <date> | --no-due] [--bucket <bucket> | --no-bucket]
                     [--cycle <cycle> | --no-cycle] [--parent <task> | --no-parent]
                     [--close-subtasks] [--description <markdown> | --stdin] [--revision <revision>]

octarine task update WEB-1 --state in-progress --add-label Improvement --due tomorrow
octarine task update WEB-1 WEB-5 --priority urgent
octarine task update WEB-1 --project MOB

# Single task (shown with --fields identifier,status,labels,due)
╭────────────┬──────────────────╮
│ Field      ┆ Value            │
╞════════════╪══════════════════╡
│ due        ┆ 2026-11-04       │
│ identifier ┆ WEB-1            │
│ labels     ┆ Bug, Improvement │
│ status     ┆ In progress      │
╰────────────┴──────────────────╯

# Several tasks return a list
╭────────────┬──────────┬───────────────────────╮
│ identifier ┆ priority ┆ title                 │
╞════════════╪══════════╪═══════════════════════╡
│ WEB-1      ┆ urgent   ┆ Fix sync conflict     │
│ WEB-5      ┆ urgent   ┆ Write onboarding copy │
╰────────────┴──────────┴───────────────────────╯

# Moving project renumbers the task
╭────────────┬───────────────────╮
│ Field      ┆ Value             │
╞════════════╪═══════════════════╡
│ identifier ┆ MOB-1             │
│ project    ┆ Mobile App        │
│ title      ┆ Fix sync conflict │
╰────────────┴───────────────────╯

--label replaces every label. --add-label and --remove-label adjust them.
--no-project, --no-due, --no-bucket, --no-cycle, and --no-parent clear a field.
A subtask always shares its parent's project, so move the parent instead.
--description replaces the whole description. Use task comment to record progress without touching it.
If a project limits its statuses, a task saved with a status the project leaves out moves to the nearest allowed one.
Moving a task to a completed status records its completion time. Closing a task that still has open subtasks fails unless you pass --close-subtasks, which closes them with it, as the app does:

octarine task update WEB-2 --state done
octarine task update WEB-2 --state done --close-subtasks

# Without --close-subtasks
error: invalid argument: that leaves open subtasks (WEB-3, WEB-4); pass --close-subtasks to mark them Done too

# With --close-subtasks (shown with --fields identifier,status,completed)
╭────────────┬──────────────────────────╮
│ Field      ┆ Value                    │
╞════════════╪══════════════════════════╡
│ completed  ┆ 2026-11-03T10:28:36.834Z │
│ identifier ┆ WEB-2                    │
│ status     ┆ Done                     │
╰────────────┴──────────────────────────╯

Pass --revision from task show when you are acting on what you read. If the task changed in the meantime, the update fails with REVISION_CONFLICT (exit code 4) instead of overwriting it:

error: revision conflict: current revision is ba4027519ed91d789066c47e7ed121ff1d575dfa803a0a0da1513fd304572dcf
  The note or task changed since you read it. Re-read it and retry with --revision <currentRevision>.

`task comment`

Add a Markdown comment to a task's activity. Use --stdin for longer comments.

octarine task comment WEB-1 "Fixed in 1a2b3c"
git log -1 --format=%B | octarine task comment WEB-1 --stdin

╭───────┬──────────────────────────╮
│ Field ┆ Value                    │
╞═══════╪══════════════════════════╡
│ at    ┆ 2026-11-03T10:28:36.802Z │
│ body  ┆ Fixed in 1a2b3c          │
│ id    ┆ n0ez94j04jyei9tgbvda4s6u │
│ type  ┆ comment                  │
╰───────┴──────────────────────────╯

`task activity`

Show a task's comments and history, oldest first. History entries record creation, status changes, project moves, and other field changes.

octarine task activity WEB-1

# Shown with --fields type,at,from,to,body
╭──────────────────────────┬───────────────┬──────┬─────────────┬─────────────────╮
│ at                       ┆ type          ┆ from ┆ to          ┆ body            │
╞══════════════════════════╪═══════════════╪══════╪═════════════╪═════════════════╡
│ 2026-11-03T10:28:36.444Z ┆ created       ┆ —    ┆ —           ┆ —               │
│ 2026-11-03T10:28:36.739Z ┆ state_changed ┆ todo ┆ in-progress ┆ —               │
│ 2026-11-03T10:28:36.802Z ┆ comment       ┆ —    ┆ —           ┆ Fixed in 1a2b3c │
╰──────────────────────────┴───────────────┴──────┴─────────────┴─────────────────╯

`task archive` and `task restore`

Archive a task to hide it from lists, and restore it later. task list --archived lists archived tasks.

octarine task archive WEB-3
octarine task list --archived
octarine task restore WEB-3

`task resource`

Keep notes, files, and links with a task. The same subcommands exist for projects as project resource.

octarine task resource list <task>
octarine task resource add <task> <path-or-url> [--title <title>]
octarine task resource remove <task> <resource id, path, URL, or title>

Paths are workspace-relative, and .md may be left off. URLs are stored as links.

octarine task resource add WEB-1 Specs/Sync.md
octarine task resource add WEB-1 https://example.com/issue/42 --title "Bug report"
octarine task resource remove WEB-1 "Bug report"

# After both adds
╭──────────────────────────┬──────┬──────────────────────────────┬────────────╮
│ id                       ┆ kind ┆ target                       ┆ title      │
╞══════════════════════════╪══════╪══════════════════════════════╪════════════╡
│ sw7kao62u8eymn9ue1exmjj3 ┆ file ┆ Specs/Sync.md                ┆ Sync       │
│ ji81b1sq850fw5ohtdyqh7f2 ┆ link ┆ https://example.com/issue/42 ┆ Bug report │
╰──────────────────────────┴──────┴──────────────────────────────┴────────────╯

Each command returns the task's full resource list after the change.

Statuses, Labels, and Buckets

`task statuses`

List the statuses tasks can use. The six built-in statuses cannot be deleted.

octarine task statuses

╭─────────┬───────────┬─────────────┬─────────────╮
│ builtIn ┆ category  ┆ id          ┆ name        │
╞═════════╪═══════════╪═════════════╪═════════════╡
│ true    ┆ backlog   ┆ backlog     ┆ Backlog     │
│ true    ┆ unstarted ┆ todo        ┆ Todo        │
│ true    ┆ started   ┆ in-progress ┆ In progress │
│ true    ┆ review    ┆ in-review   ┆ In review   │
│ true    ┆ completed ┆ done        ┆ Done        │
│ true    ┆ cancelled ┆ cancelled   ┆ Cancelled   │
╰─────────┴───────────┴─────────────┴─────────────╯

A status's category decides whether its tasks count as open (backlog, unstarted, started, review), completed (completed), or cancelled (cancelled).

`task status create`, `update`, and `delete`

Add custom statuses. A custom status's category is fixed when it is created.

octarine task status create QA --category review --color purple
octarine task status update QA --name "QA review"
octarine task status update "QA review" --no-color
octarine task status delete "QA review"

# Create
╭──────────┬──────────────────────────╮
│ Field    ┆ Value                    │
╞══════════╪══════════════════════════╡
│ category ┆ review                   │
│ color    ┆ purple                   │
│ deleted  ┆ false                    │
│ id       ┆ vh0atamrnzmzs0v0jdewtyub │
│ name     ┆ QA                       │
╰──────────┴──────────────────────────╯

Deleting a custom status moves its tasks to the built-in status of the same category.

`task labels` and `task label`

List labels with how many tasks use each, and create, rename, recolour, or delete them. New workspaces start with Bug, Feature, and Improvement.

octarine task labels
octarine task label create Docs --color green
octarine task label update Docs --name Documentation
octarine task label delete Documentation

# task labels
╭────────┬─────────────┬───────╮
│ color  ┆ name        ┆ tasks │
╞════════╪═════════════╪═══════╡
│ red    ┆ Bug         ┆ 0     │
│ purple ┆ Feature     ┆ 0     │
│ blue   ┆ Improvement ┆ 0     │
╰────────┴─────────────┴───────╯

Renaming a label updates every task that has it. Deleting a label takes it off every task.

`task buckets` and `task bucket`

Buckets are a lightweight way to say when you plan to get to something. New workspaces start with Now, Next, and Later.

octarine task buckets
octarine task bucket create "Next week" --color coral
octarine task bucket update "Next week" --name "This month"
octarine task bucket delete "This month"

# task buckets
╭────────┬──────────────────────────┬───────╮
│ color  ┆ id                       ┆ name  │
╞════════╪══════════════════════════╪═══════╡
│ orange ┆ bucketdefaultnow00000000 ┆ Now   │
│ blue   ┆ bucketdefaultnext0000000 ┆ Next  │
│ —      ┆ bucketdefaultlater000000 ┆ Later │
╰────────┴──────────────────────────┴───────╯

Deleting a bucket takes its tasks out of it.

Templates

`task templates` and `task template show`

List templates, or show one with its description.

octarine task templates
octarine task template show "Bug report"

# Shown with --fields name,project,labels,subtasks
╭────────┬────────────┬─────────┬────────────────────────╮
│ labels ┆ name       ┆ project ┆ subtasks               │
╞════════╪════════════╪═════════╪════════════════════════╡
│ Bug    ┆ Bug report ┆ —       ┆ Repro, Fix             │
│ —      ┆ Release    ┆ Website ┆ Changelog, Tag release │
╰────────┴────────────┴─────────┴────────────────────────╯

`task template create`

Create a template from options, or copy an existing task's fields, description, and subtasks with --from.

octarine task template create <name> [--from <task>] [--title <title>] [--project <project>]
                              [--state <status>] [--priority <priority>] [--label <label>]...
                              [--bucket <bucket>] [--subtask <title>]... [--description <markdown> | --stdin]

octarine task template create "Bug report" --label Bug --priority high \
  --subtask Repro --subtask Fix --description "## Steps to reproduce"
octarine task template create Release --from WEB-2

# From a task
╭──────────┬──────────────────────────╮
│ Field    ┆ Value                    │
╞══════════╪══════════════════════════╡
│ id       ┆ zbw2y0ilfkuz54ecna3ffa3f │
│ labels   ┆ —                        │
│ name     ┆ Release                  │
│ project  ┆ Website                  │
│ subtasks ┆ Changelog, Tag release   │
│ title    ┆ —                        │
╰──────────┴──────────────────────────╯

`task template update` and `delete`

update accepts the same options as create. --label and --subtask replace the existing lists. --no-project and --no-bucket clear those fields.

octarine task template update "Bug report" --priority urgent
octarine task template update Release --no-project
octarine task template delete Release

Saved Filters

Saved filters are named task searches. They appear as tabs in the Tasks view, either everywhere or on one project.

octarine task filter list
octarine task filter list --project WEB

# Shown with --fields name,project,query
╭────────────────────┬─────────┬──────────────────────────────╮
│ name               ┆ project ┆ query                        │
╞════════════════════╪═════════╪══════════════════════════════╡
│ All open           ┆ —       ┆ is:open                      │
│ Bugs               ┆ Website ┆ is:open label:Bug            │
│ Due this week      ┆ —       ┆ is:open due:<7d -due:overdue │
│ Overdue            ┆ —       ┆ is:overdue                   │
│ Recently completed ┆ —       ┆ completed:<7d                │
╰────────────────────┴─────────┴──────────────────────────────╯

New workspaces start with All open, Due this week, Overdue, and Recently completed.

`task filter create`, `update`, and `delete`

--query takes the same text you would type in the app's filter bar.

octarine task filter create Bugs --query "is:open label:Bug" --project WEB --icon lucide:Bug --color red
octarine task filter update Bugs --name "Open bugs"
octarine task filter delete "Open bugs"

╭─────────┬──────────────────────────╮
│ Field   ┆ Value                    │
╞═════════╪══════════════════════════╡
│ color   ┆ red                      │
│ icon    ┆ lucide:Bug               │
│ id      ┆ lpv435qxxaaw9vtde65m7y0h │
│ name    ┆ Bugs                     │
│ project ┆ Website                  │
│ query   ┆ is:open label:Bug        │
╰─────────┴──────────────────────────╯

--project shows the filter on that project only. Without it, the filter is shared: add it as a tab on any project with project update --add-filter.

Task Settings

`task settings`

Show the workspace's task settings, or change the key used for tasks outside any project.

octarine task settings
octarine task settings --unassigned-key TODO

╭───────────────┬────────╮
│ Field         ┆ Value  │
╞═══════════════╪════════╡
│ cycleDays     ┆ 14     │
│ cycleStartDay ┆ monday │
│ cycles        ┆ false  │
│ unassignedKey ┆ TASK   │
╰───────────────┴────────╯

After a key change, every task without a project is shown under the new key and keeps its number: TASK-1 becomes TODO-1.

Project Commands

`project list`

List projects with their open and closed task counts. Add --archived to list archived projects instead.

octarine project list
octarine project list --archived

# Shown with --fields key,name,open,closed,state
╭────────┬─────┬────────────┬──────┬────────╮
│ closed ┆ key ┆ name       ┆ open ┆ state  │
╞════════╪═════╪════════════╪══════╪════════╡
│ 0      ┆ MOB ┆ Mobile App ┆ 0    ┆ active │
│ 0      ┆ WEB ┆ Website    ┆ 5    ┆ active │
╰────────┴─────┴────────────┴──────┴────────╯

`project show`

Show a project with its description, settings, resources, and open tasks. Add --all to include closed tasks.

octarine project show WEB --json

{"data":{"archived":false,"buckets":"all","closed":3,"color":"blue","defaultTemplate":"Bug report","description":"Marketing site relaunch","filters":["Bugs"],"icon":"lucide:Globe","id":"s1uzltudzqggus7lbvpv8esb","key":"WEB","labels":"all","name":"Website","open":6,"pinned":false,"resources":[{"id":"i4jtxmdt5wx2yoj1gy7pdwf3","kind":"link","target":"https://example.com/brief","title":"Brief"}],"revision":"7f7d6d68…","state":"active","statuses":["Todo","In progress","QA","Done"],"tasks":[{"identifier":"WEB-1","title":"Fix sync conflict","status":"In progress",…},…]},"meta":{"truncated":false},"ok":true,"schemaVersion":1}

statuses, labels, and buckets are either "all" or the list the project allows.

`project create`

octarine project create <name> [--key <KEY>] [--icon <icon>] [--color <colour>]
                        [--description <markdown> | --stdin]

octarine project create Website --key WEB --icon lucide:Globe --color blue --description "Marketing site relaunch"

╭────────┬──────────────────────────╮
│ Field  ┆ Value                    │
╞════════╪══════════════════════════╡
│ closed ┆ 0                        │
│ color  ┆ blue                     │
│ icon   ┆ lucide:Globe             │
│ id     ┆ s1uzltudzqggus7lbvpv8esb │
│ key    ┆ WEB                      │
│ name   ┆ Website                  │
│ open   ┆ 0                        │
│ state  ┆ active                   │
╰────────┴──────────────────────────╯

The key is 2 to 5 letters or digits. Its tasks are numbered under it: WEB-1, WEB-2, and so on. Without --icon, the project uses lucide:ListTodo.

`project update`

Change a project's details and the choices its tasks are offered.

Option	Effect
`--name`, `--key`, `--icon`, `--color`	Rename, re-key, or restyle the project
`--state active\|completed`	Mark the project completed, or active again
`--statuses <a,b,c>` / `--all-statuses`	The only statuses its tasks can use, or every status
`--labels <a,b,c>` / `--all-labels`	The labels it offers, or every label
`--buckets <a,b,c>` / `--all-buckets`	The only buckets its tasks can use, or every bucket
`--default-template <template>` / `--no-default-template`	The template new tasks in this project start from
`--pin` / `--unpin`	Pin it in the sidebar
`--add-filter <filter>` / `--remove-filter <filter>`	Show or stop showing a shared filter as a tab; repeatable
`--description <markdown>` / `--stdin`	Replace the description

octarine project update WEB --default-template "Bug report"
octarine project update WEB --statuses "Todo,In progress,QA,Done"
octarine project update WEB --add-filter Overdue --pin
octarine project update WEB --state completed

With a default template set, a plain task create in the project picks it up:

octarine task create "Crash on launch" --project WEB
octarine task create "Tidy README" --project WEB --no-template

# Starts from "Bug report" (shown with --fields identifier,priority,labels,subtasks)
╭────────────┬─────────────────────────────────────────────────────────────────────╮
│ Field      ┆ Value                                                               │
╞════════════╪═════════════════════════════════════════════════════════════════════╡
│ identifier ┆ WEB-6                                                               │
│ labels     ┆ Bug                                                                 │
│ priority   ┆ high                                                                │
│ subtasks   ┆ [{"identifier":"WEB-7","title":"Repro",…},{"identifier":"WEB-8",…}] │
╰────────────┴─────────────────────────────────────────────────────────────────────╯

# Skips it
╭────────────┬───────╮
│ Field      ┆ Value │
╞════════════╪═══════╡
│ identifier ┆ WEB-9 │
│ labels     ┆       │
│ priority   ┆ none  │
╰────────────┴───────╯

`project resource`

Works like task resource, with a project in place of the task.

octarine project resource add Website https://example.com/brief --title Brief
octarine project resource list WEB
octarine project resource remove WEB Brief

`project archive` and `project restore`

octarine project archive "Mobile App"
octarine project restore MOB

Cycle Commands

Cycles are fixed-length planning periods, such as two-week sprints. They are off until you turn them on. While they are off, --cycle options fail with a hint:

error: invalid argument: cycles are off; turn them on with `octarine cycle settings --enable`

`cycle settings`

Turn cycles on or off and set their cadence. Lengths are 7, 14, 21, or 28 days, and cycles start on any weekday.

octarine cycle settings
octarine cycle settings --enable --days 14 --start-day monday
octarine cycle settings --disable

╭───────────────┬────────╮
│ Field         ┆ Value  │
╞═══════════════╪════════╡
│ cycleDays     ┆ 14     │
│ cycleStartDay ┆ monday │
│ cycles        ┆ true   │
│ unassignedKey ┆ TASK   │
╰───────────────┴────────╯

`cycle list`

List the current and upcoming cycles. Add --all to include ended ones.

octarine cycle list
octarine cycle list --all

# Shown with --fields number,name,start,end,state,open,closed
╭────────┬────────────┬────────────────┬────────┬──────┬────────────┬──────────╮
│ closed ┆ end        ┆ name           ┆ number ┆ open ┆ start      ┆ state    │
╞════════╪════════════╪════════════════╪════════╪══════╪════════════╪══════════╡
│ 0      ┆ 2026-11-15 ┆ Cycle 1        ┆ 1      ┆ 0    ┆ 2026-11-02 ┆ active   │
│ 0      ┆ 2026-11-29 ┆ Upcoming cycle ┆ 2      ┆ 0    ┆ 2026-11-16 ┆ upcoming │
╰────────┴────────────┴────────────────┴────────┴──────┴────────────┴──────────╯

Plan tasks into a cycle

Use --cycle on task create or task update. Subtasks follow their parent into the cycle.

octarine task update MOB-1 WEB-5 --cycle current
octarine task create "Polish onboarding" --cycle upcoming
octarine task update WEB-5 --no-cycle

`cycle show`

Show a cycle and its open tasks. Without an argument, it shows the current cycle. Add --all to include closed tasks.

octarine cycle show
octarine cycle show upcoming --all

# Shown with --fields name,goal,start,end,open,closed,state
╭────────┬───────────────────╮
│ Field  ┆ Value             │
╞════════╪═══════════════════╡
│ closed ┆ 0                 │
│ end    ┆ 2026-11-15        │
│ goal   ┆ Ship the relaunch │
│ name   ┆ Cycle 1           │
│ open   ┆ 2                 │
│ start  ┆ 2026-11-02        │
│ state  ┆ active            │
╰────────┴───────────────────╯

`cycle update`

Set or clear a cycle's goal.

octarine cycle update current --goal "Ship the relaunch"
octarine cycle update current --no-goal

`cycle complete`

End the current cycle and start the next. Unfinished tasks carry over to the next cycle; pass --return-unfinished to take them out of cycles instead.

octarine cycle complete
octarine cycle complete --return-unfinished

# Shown with --fields name,state,next,stats
╭───────┬───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Field ┆ Value                                                                                             │
╞═══════╪═══════════════════════════════════════════════════════════════════════════════════════════════════╡
│ name  ┆ Cycle 1                                                                                           │
│ next  ┆ Cycle 2                                                                                           │
│ state ┆ ended                                                                                             │
│ stats ┆ {"added":2,"cancelled":0,"carried":2,"completed":0,"planned":0,"plannedCompleted":0,"returned":0} │
╰───────┴───────────────────────────────────────────────────────────────────────────────────────────────────╯

stats records how many tasks were planned at the start, added during the cycle, completed, cancelled, carried over, and returned.

Use Tasks From An Agent

Coding agents can track their work in Octarine with these commands, from a shell or over MCP. A typical loop:

octarine task list --project WEB --open --json             # see what is planned
octarine task show WEB-24 --activity --json                # read before acting
octarine task update WEB-24 --state in-progress
octarine task comment WEB-24 "Fixed in $(git rev-parse --short HEAD)"
octarine task update WEB-24 --state done

octarine agent-guide includes a section on tasks and projects that you can paste into an agent's instructions.

Quick Answers

Can I manage Octarine tasks from the terminal?

Yes. octarine task, octarine project, and octarine cycle create, update, and organize the same tasks you see in the Tasks view. Changes show up in an open Octarine window on their own.

Where does the CLI store tasks?

In Markdown files under .octarine/tasks in the workspace, the same files the desktop app reads. See Where Tasks Are Stored.

What happened to `octarine task list --todo`?

Listing Markdown checkboxes across notes moved to octarine checkbox list, which takes the same --folder, --done, and --todo options. octarine task list now lists managed tasks.

Why did my task's ID change?

It moved to another project, so it took the next number there. Its old ID still finds it.