[--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] ``` ```bash 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 ``` ```text # 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](#task-template-create); options you pass win over the template's values. A task created in a project with a [default template](#project-update) starts from it unless you pass `--template` or `--no-template`. - `--cycle` requires cycles to be turned on with [`cycle settings --enable`](#cycle-settings). ### `task update` Change only the fields you pass. Several task IDs apply the same change to each. ```text 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>] ``` ```bash 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 ``` ```text # 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`](#task-comment) to record progress without touching it. - If a project [limits its statuses](#project-update), 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: ```bash octarine task update WEB-2 --state done octarine task update WEB-2 --state done --close-subtasks ``` ```text # 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: ```text 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. ```bash octarine task comment WEB-1 "Fixed in 1a2b3c" git log -1 --format=%B | octarine task comment WEB-1 --stdin ``` ```text ╭───────┬──────────────────────────╮ │ 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. ```bash octarine task activity WEB-1 ``` ```text # 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. ```bash 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`. ```text 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. ```bash 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" ``` ```text # 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. ```bash octarine task statuses ``` ```text ╭─────────┬───────────┬─────────────┬─────────────╮ │ 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. ```bash 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" ``` ```text # 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**. ```bash octarine task labels octarine task label create Docs --color green octarine task label update Docs --name Documentation octarine task label delete Documentation ``` ```text # 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**. ```bash 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" ``` ```text # 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. ```bash octarine task templates octarine task template show "Bug report" ``` ```text # 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`. ```text octarine task template create <name> [--from <task>] [--title <title>] [--project <project>] [--state <status>] [--priority <priority>] [--label <label>]... [--bucket <bucket>] [--subtask <title>]... [--description <markdown> | --stdin] ``` ```bash 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 ``` ```text # 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. ```bash 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](/tasks/search-and-filters). They appear as tabs in the Tasks view, either everywhere or on one project. ### `task filter list` ```bash octarine task filter list octarine task filter list --project WEB ``` ```text # 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. ```bash 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" ``` ```text ╭─────────┬──────────────────────────╮ │ 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`](#project-update). ## Task Settings ### `task settings` Show the workspace's task settings, or change the key used for tasks outside any project. ```bash octarine task settings octarine task settings --unassigned-key TODO ``` ```text ╭───────────────┬────────╮ │ 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. ```bash octarine project list octarine project list --archived ``` ```text # 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. ```bash octarine project show WEB --json ``` ```text {"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` ```text octarine project create <name> [--key <KEY>] [--icon <icon>] [--color <colour>] [--description <markdown> | --stdin] ``` ```bash octarine project create Website --key WEB --icon lucide:Globe --color blue --description "Marketing site relaunch" ``` ```text ╭────────┬──────────────────────────╮ │ 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 | ```bash 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: ```bash octarine task create "Crash on launch" --project WEB octarine task create "Tidy README" --project WEB --no-template ``` ```text # 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`](#task-resource), with a project in place of the task. ```bash 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` ```bash 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: ```text 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. ```bash octarine cycle settings octarine cycle settings --enable --days 14 --start-day monday octarine cycle settings --disable ``` ```text ╭───────────────┬────────╮ │ Field ┆ Value │ ╞═══════════════╪════════╡ │ cycleDays ┆ 14 │ │ cycleStartDay ┆ monday │ │ cycles ┆ true │ │ unassignedKey ┆ TASK │ ╰───────────────┴────────╯ ``` ### `cycle list` List the current and upcoming cycles. Add `--all` to include ended ones. ```bash octarine cycle list octarine cycle list --all ``` ```text # 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`](#task-create) or [`task update`](#task-update). Subtasks follow their parent into the cycle. ```bash 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. ```bash octarine cycle show octarine cycle show upcoming --all ``` ```text # 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. ```bash 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. ```bash octarine cycle complete octarine cycle complete --return-unfinished ``` ```text # 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](/cli/agents-and-mcp#available-tools). A typical loop: ```bash 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`](/cli/agents-and-mcp#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](/tasks/overview#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.

--- title: Tasks, Projects, and Cycles description: Complete CLI reference for managed tasks, projects, cycles, statuses, labels, buckets, templates, saved filters, and resources. --- The `task`, `project`, and `cycle` commands work with the same tasks you see in Octarine's [Tasks](/tasks/overview) 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`](/cli/folders-links-and-tasks#checkbox-list) and change one with [`note task set`](/cli/notes#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`](#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. ```text octarine task list [--project | --no-project] [--state ]... [--open | --closed] [--label ]... [--bucket ] [--cycle ] [--parent ] [--search ] [--completed-within ] [--archived] [--sort number|priority|due|updated|status] [--limit ] ``` | 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` | ```bash 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 ``` ```text # 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`](/cli/commands#global-options) to keep only the columns you need. ```bash octarine task list --label Bug --json ``` ```text {"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. ```bash octarine task show WEB-1 octarine task show WEB-1 --activity --json ``` ```text # 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](/tasks/linking-and-deep-links). ### `task create` Create a task with its fields in one call. ```text octarine task create [--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] ``` ```bash 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 ``` ```text # 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](#task-template-create); options you pass win over the template's values. A task created in a project with a [default template](#project-update) starts from it unless you pass `--template` or `--no-template`. - `--cycle` requires cycles to be turned on with [`cycle settings --enable`](#cycle-settings). ### `task update` Change only the fields you pass. Several task IDs apply the same change to each. ```text 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>] ``` ```bash 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 ``` ```text # 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`](#task-comment) to record progress without touching it. - If a project [limits its statuses](#project-update), 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: ```bash octarine task update WEB-2 --state done octarine task update WEB-2 --state done --close-subtasks ``` ```text # 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: ```text 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. ```bash octarine task comment WEB-1 "Fixed in 1a2b3c" git log -1 --format=%B | octarine task comment WEB-1 --stdin ``` ```text ╭───────┬──────────────────────────╮ │ 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. ```bash octarine task activity WEB-1 ``` ```text # 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. ```bash 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`. ```text 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. ```bash 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" ``` ```text # 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. ```bash octarine task statuses ``` ```text ╭─────────┬───────────┬─────────────┬─────────────╮ │ 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. ```bash 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" ``` ```text # 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**. ```bash octarine task labels octarine task label create Docs --color green octarine task label update Docs --name Documentation octarine task label delete Documentation ``` ```text # 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**. ```bash 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" ``` ```text # 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. ```bash octarine task templates octarine task template show "Bug report" ``` ```text # 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`. ```text octarine task template create <name> [--from <task>] [--title <title>] [--project <project>] [--state <status>] [--priority <priority>] [--label <label>]... [--bucket <bucket>] [--subtask <title>]... [--description <markdown> | --stdin] ``` ```bash 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 ``` ```text # 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. ```bash 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](/tasks/search-and-filters). They appear as tabs in the Tasks view, either everywhere or on one project. ### `task filter list` ```bash octarine task filter list octarine task filter list --project WEB ``` ```text # 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. ```bash 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" ``` ```text ╭─────────┬──────────────────────────╮ │ 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`](#project-update). ## Task Settings ### `task settings` Show the workspace's task settings, or change the key used for tasks outside any project. ```bash octarine task settings octarine task settings --unassigned-key TODO ``` ```text ╭───────────────┬────────╮ │ 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. ```bash octarine project list octarine project list --archived ``` ```text # 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. ```bash octarine project show WEB --json ``` ```text {"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` ```text octarine project create <name> [--key <KEY>] [--icon <icon>] [--color <colour>] [--description <markdown> | --stdin] ``` ```bash octarine project create Website --key WEB --icon lucide:Globe --color blue --description "Marketing site relaunch" ``` ```text ╭────────┬──────────────────────────╮ │ 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 | ```bash 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: ```bash octarine task create "Crash on launch" --project WEB octarine task create "Tidy README" --project WEB --no-template ``` ```text # 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`](#task-resource), with a project in place of the task. ```bash 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` ```bash 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: ```text 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. ```bash octarine cycle settings octarine cycle settings --enable --days 14 --start-day monday octarine cycle settings --disable ``` ```text ╭───────────────┬────────╮ │ Field ┆ Value │ ╞═══════════════╪════════╡ │ cycleDays ┆ 14 │ │ cycleStartDay ┆ monday │ │ cycles ┆ true │ │ unassignedKey ┆ TASK │ ╰───────────────┴────────╯ ``` ### `cycle list` List the current and upcoming cycles. Add `--all` to include ended ones. ```bash octarine cycle list octarine cycle list --all ``` ```text # 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`](#task-create) or [`task update`](#task-update). Subtasks follow their parent into the cycle. ```bash 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. ```bash octarine cycle show octarine cycle show upcoming --all ``` ```text # 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. ```bash 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. ```bash octarine cycle complete octarine cycle complete --return-unfinished ``` ```text # 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](/cli/agents-and-mcp#available-tools). A typical loop: ```bash 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`](/cli/agents-and-mcp#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](/tasks/overview#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.