v0.1.0 to v0.2.0

92 added, 44 removed. Audit A to A.

---

name: structured

- description: "Operate the Structured day planner through the structured CLI. Use when listing, completing, creating, editing, or deleting Structured tasks, opening the Structured TUI, or recovering from structured CLI errors. Reads are safe. Writes need explicit user authorization."

+ description: "Operate the Structured day planner through the structured CLI: read a day or the inbox, show the plan to a person as a text timeline, and, with explicit authorization, create, edit, complete, or delete tasks and their subtasks. Use when the user mentions Structured tasks, their day plan, subtasks or checklists in Structured, the Structured TUI, or a structured CLI error. Reads are safe. Writes need explicit user authorization."

license: MIT

- argument-hint: "<Structured task read or authorized change>"

+ argument-hint: "<Structured read, plan review, or authorized change>"

metadata:

author: vanducng

- version: "0.1.0"

+ version: "0.2.0"

+ binary: structured

---

# structured

- Use the `structured` binary. `--help` on the command you are about to run is the flag contract. Do not call the Structured MCP server directly.

+ Use the `structured` binary. `structured <command> --help` is the flag contract. Do not call the Structured MCP server directly.

+ ```text

+ agent ── structured ... --json ──▶ Structured Cloud ◀── Structured apps

+ │ ▲

+ └─ structured today --text ──▶ person │

+ person reviews and fixes in `structured` (TUI)

+ ```

## Start

```bash

- command -v structured

- structured --version

- structured today --help

+ command -v structured && structured --version

+ structured today --json

```

- Install the latest GitHub release archive for this machine, or:

+ Missing binary: install the latest GitHub release archive for this machine, or `cargo install --git https://github.com/vanducng/structured`.

- ```bash

- cargo install --git https://github.com/vanducng/structured

- ```

+ If stderr has `"code":"AUTH"`, ask the user to run `structured login` in their own terminal. It opens a browser. Never run login from an agent shell. Never read, print, or commit `$XDG_CONFIG_HOME/structured/auth.json` (or `~/.config/structured/auth.json`).

- Confirm with `structured --version`.

+ ## Output contract

- ## Sign in

+ - Success: one JSON object on stdout when `--json` is set or stdout is not a terminal. Lists are `{"ok":true,"tasks":[...]}` (`list` adds `"truncated"`). Every write is `{"ok":true,"result":{"operation","scope","ref","task"}}`, where `scope` is `task`, `day`, or `series`.

+ - Failure: one JSON object on stderr, argument errors included: `{"ok":false,"error":{"code","message","retryable","next_steps"}}`. Codes: `AUTH`, `USAGE`, `NOT_FOUND`, `API`, `NETWORK`, `IO`, `DATA`.

+ - Retry only when `retryable` is true. Otherwise follow `next_steps` in order. Usage errors exit 2, others exit 1.

+ - Every task carries `ref`. Pass that string back as `REF`. Do not build refs by hand. Field details: [references/json.md](references/json.md).

- Start with a read:

+ ## Read

```bash

structured today --json

+ structured day tomorrow --json # YYYY-MM-DD, today, tomorrow, yesterday, +N, -N

+ structured inbox --json

+ structured list --from today --to +7 --open --search standup --json

+ structured subtask list REF --json

```

- If stderr has `"code":"AUTH"`, ask the user to run `structured login` in an interactive terminal. Login opens a browser and stores tokens at `$XDG_CONFIG_HOME/structured/auth.json`, or `~/.config/structured/auth.json`. Do not run login from a non-interactive shell. Do not read, print, or commit that file.

- ## Output

+ Report counts, times, and refs. Keep task titles and notes out of logs unless the user asked to see them.

- - Success is one JSON object on stdout when `--json` is set or stdout is not a terminal.

- - Failure is one JSON object on stderr: `error.code`, `error.message`, `error.retryable`, `error.next_steps`.

- - Retry only when `retryable` is true. Follow `next_steps` in order.

- - `--help` and `--version` are human text, not JSON.

- - Usage mistakes exit 2. Other failures exit 1.

+ ## Show the plan to a person

- ## Read

+ When the user asks "what's my day" or wants to review a plan, print the text view and paste it unchanged in a fenced `text` block. Do not rebuild it as a table.

```bash

- structured today --json

- structured inbox --json

- structured list --from 2026-10-01 --to 2026-10-07 --json

- structured account --json

+ structured today --text

+ structured day +1 --text

+ structured inbox --text

```

- Keep task titles out of logs unless the user asked to see them. Report counts and ids.

+ ```text

+ Fri 23 Oct 2026 (today) · 4 tasks, 1 done · 4h 45m planned

- A recurring row may have an empty `id` and a `recurring_id`. Later commands for that row need the recurring id and `--day YYYY-MM-DD`.

+ All day

+ [ ] Read 20 pages repeats

+ 08:30-09:15 45m [x] Team sync

+ 09:00-09:30 30m [ ] Review the pull request ! overlaps

+ · 3h 30m free

+ 13:00-16:30 3h 30m [ ] Finish the billing export (1/3)

+ [x] Map the fields

+ [ ] Write the backfill

+ [ ] Dry run on staging

+ ```

+ How to read it: `[x]` is done. `(1/3)` counts finished subtasks. `repeats` is one day of a recurring task. `! overlaps` starts before the previous task ends. `· free` is an open gap of 30 minutes or more. `--- now HH:MM ---` marks the current time on today.

## Write

- Create, edit, complete, reopen, or delete only after the user explicitly authorizes that operation. A read is not authorization.

+ Create, edit, complete, reopen, or delete only after the user explicitly authorizes that operation. A read is not authorization. Confirm the target by `ref` before writing. When the person wants to see the exact change first, add `--dry-run`: reads still run, and the write prints `"dry_run": true` with the tool and arguments it would send.

```bash

- structured add "Write the note" --day 2026-10-24 --time 09:30 --duration 30 --json

- structured add "Someday" --inbox --json

- structured done TASK_ID --json

- structured undo TASK_ID --json

- structured edit TASK_ID --title "New title" --json

- structured delete TASK_ID --yes --json

+ structured add "Write the note" --day +1 --time 09:30 --duration 30 --subtask Outline --subtask Draft --json

+ structured add "Someday" --json # no day, time, or --all-day: inbox

+ structured done REF --json

+ structured undo REF --json

+ structured edit REF --title "New title" --time 10:00 --json

+ structured edit RID@2026-10-23 --time 07:00 --scope series --json # a recurring day needs --scope

+ structured delete REF --yes --dry-run --json

+ structured delete REF --yes --json

+ structured subtask add REF "Draft" "Review" --json

+ structured subtask done REF 2 --json # SUB is a 1-based number or a subtask id

+ structured subtask edit REF 2 "Review with Sam" --json

+ structured subtask delete REF 2 --yes --json

```

- - No day, or `--inbox`, creates an inbox task.

- - A day without `--time` is all-day. `--time` is `HH:MM`. Duration is minutes.

- - `delete` refuses to run without `--yes`.

- - For a recurring id, pass `--day`. `delete` then removes that day only.

- - Deleting a calendar-imported task hides it in Structured. It does not delete the event from the external calendar.

- - The default symbol is `text.badge.checkmark`. Override with `--symbol` when the user names one.

+ - `--time` alone schedules today. `--day` alone is all-day. Duration is 0 to 1439 minutes.

+ - `delete` and `subtask delete` refuse to run without `--yes`.

+ - The server replaces a task's whole checklist on every subtask write. The CLI reads the current list first and keeps existing ids, so run subtask commands one at a time per task. Prefer the subtask id over its number when the person may be editing the same checklist in the TUI.

+ - The default symbol is `text.badge.checkmark`. Use `--symbol` only with a code the user named.

- This CLI does not create recurring series.

- ## TUI

+ ### Recurring tasks

- A person runs `structured` in a terminal to open the task manager. `structured tui` does the same. Do not launch the TUI from an agent shell. Keys: `j`/`k`, `gg`/`G`, `h`/`l`, `[`/`]`, `x` or space to tick, `a` add, `e` edit title, `d` then `y` delete, `r` refresh, `q` quit.

+ | Change on a `RECURRING_ID@DAY` ref | Scope |

+ | --- | --- |

+ | `done`, `undo`, `delete`, subtask ticks | that day only |

+ | `edit ... --scope day` | that day only; the day is split off the series and gets a new `ref` |

+ | `edit ... --scope series` | every repeat; moves (`--move-day`, `--inbox`) are refused |

+ | add, rename, or remove a subtask | that day only (splits it off, Pro plan) |

+ `edit` on a recurring day without `--scope` is a `USAGE` error that lists both choices. Ask the person which one they mean, and say the scope back before a series-wide edit. After a split, `result.ref` is the new standalone task's ref; use it for the next write. Deleting a calendar-imported task hides it in Structured. The external calendar event stays.

+ ## Hand off for review in the TUI

+ After a batch of writes, or when the user wants to adjust the plan themselves, tell them to open the TUI in their terminal. Do not launch it from an agent shell.

+ ```text

+ structured # or: structured tui

+ ```

+ Point them at what changed. For example: "Today now has 13:00-16:30 Billing export with 3 subtasks. Press `enter` on it to tick or edit the checklist." The TUI paints every edit at once, saves in the background, and puts the old value back if a save fails. Layout and keys: [references/tui.md](references/tui.md).

+ ## Recover

+ | Code | Do this |

+ | --- | --- |

+ | `AUTH` | Ask the person to run `structured login` in their own terminal, then retry the read. `login` refuses to run without a terminal. |

+ | `USAGE` | Fix the flags from `--help`. Do not retry unchanged. |

+ | `NOT_FOUND` | Follow `next_steps`: refresh refs with `structured today --json` or `structured list --from DAY --json`, or the checklist with `structured subtask list REF --json`. The lookup covers the inbox, upcoming days, and 60 days back. |

+ | `API` | Read `message`. A plan limit (for example a Pro-only recurring edit) needs the user's decision. |

+ | `NETWORK` | Retry once. |