things-app

# Things 3 Drive Things 3 (tasks, projects, areas) through whichever modality fits the environment. Prefer the **`things` CLI** whenever there's command-line access to Things — it reads and writes the local database directly, so it's fast and needs no network round-trip. Where there's no CLI access, the fallbacks are: a connected **Things MCP** (full read + write that syncs across devices, from anywhere), the `things:///` URL scheme (any device with Things, write-only), and email-to-Things (unattended, Inbox-only capture). A **Things MCP** — a self-hosted server, or an official one Cultured Code may ship — plays the role the CLI plays locally, but reachable from anywhere, so it's the first fallback when there's no command-line access. Match its tools by their `things_*` base names; the MCP host prepends its own namespace, so the full identifier varies by client. ## Pick a modality first | Modality | Read state? | Schedule & update? | Unattended? | From phone? | |----------|:-----------:|:------------------:|:-----------:|:-----------:| | **CLI** (`things` binary) | Yes | Yes | On the Mac only | No | | **URL scheme** (`things:///`) | No | Yes (`update`/`json` need auth token) | No — someone must open the URL | Yes | | **Email-to-Things** | No | No (Inbox capture only) | Yes | Yes (send an email) | The real axis is **attended vs unattended**, not headless. A headless session someone is watching can still use the URL scheme — the agent prints the link, the user opens it. Only a routine with no one to act on its output is limited to email. Decision rules: - **Command-line access to Things (a terminal with the local Things database) → use the CLI.** The default: reads (Inbox, Today, search, projects, areas, tags) and the full write surface, all against the local DB. - **No CLI access, but a Things MCP is connected → use it.** Some setups expose Things through an MCP server (self-hosted, or a future official one); its `things_*` tools give full read + write that syncs across devices, with no Mac or device interaction required. The path for headless, remote, or cloud-routine environments. - **No terminal, but the user can act on the output → build a URL.** You construct the `things:///...` link; the user (or an iOS Shortcut) opens it on a device with Things to execute. This holds even when the agent itself is headless — being headless doesn't rule out the URL scheme; only the absence of anyone to open the link does. The mobile and attended-remote write/schedule path. - **Fully unattended (a remote/NAS routine with no one watching) → email-to-Things.** The only path that needs neither a Mac nor a human. Lands in the Inbox only — no scheduling, no project placement, no updates. Good for dropping raw captures that get triaged later on desktop. ## Credentials Two values are specific to the user's Things setup: - **Auth token** — needed only for commands that modify existing data (`update`, `update-project`, `json` with an `update` op); plain `add` / `add-project` / `add-area` don't. Things → Settings → General → Enable Things URLs → **Manage**. - **Mail-to-Things address** — the capture address for the email modality. Things → Settings → **Mail to Things**. Resolve each at use time: env var first (`THINGS_AUTH_TOKEN`, `THINGS_EMAIL`), then private hosted configuration, then ask. Never invent one; never echo either into output, commits, or logs. In a shell, these belong in the shell profile so an update can't overwrite them; the `things` CLI reads `THINGS_AUTH_TOKEN` on its own: export THINGS_AUTH_TOKEN=… export THINGS_EMAIL=…@things.email In hosted environments, check for `things.local.md` in the skill folder and apply any configuration it contains before asking the user for missing values. This file belongs only in the user's personal copy of the skill; do not commit, share, or redistribute it. --- ## 1. CLI (`things` binary) — desktop, full read + write Default modality on a Mac. Reads the local Things SQLite DB for queries; writes go through the URL scheme under the hood. Reading Things STATE is **only** possible here. Setup (skip if `which things` returns a path): `brew install ossianhempel/tap/things3-cli`. The DB lives in the Things app sandbox; the terminal may need Full Disk Access to read it. Override the DB path with `THINGSDB` or `--db=PATH` if needed. ### Read (queries the local DB) - Built-in lists: `things inbox`, `things today`, `things upcoming`, `things anytime`, `things someday`, `things logbook`, `things deadlines`, `things trash` - Time-scoped: `things logtoday` (completed today), `things createdtoday`, `things completed`, `things canceled` - Overview: `things all` (Inbox, Today, Upcoming, Anytime, Someday, Logbook, No Area, Areas in one shot) - Structure: `things projects`, `things areas`, `things tags` - Search: `things search "query"` — title/notes match; flags `--status=incomplete|completed|canceled|any`, `--project=`, `--area=`, `--tag=`, `--limit=`, `--all` (include completed/canceled/trashed), `--json` - List todos with filters: `things tasks --project "Travel"`, `things tasks --area "Work"`, `things tasks --tag focus --search "draft"` - Inspect one item (exact match): `things show "Project Name"`, `things show --id=<ID> --json` - Most read commands accept `--json` and `--no-header`. Get an item's ID from `--json` output or `things search "x" --json`. ### Write Preview any write without executing: prepend `--dry-run` (prints the URL, does not open Things). Add `--foreground` to bring Things to the front. - **Add todo:** `things add "Buy milk" --notes "2% + bananas" --when today --deadline 2026-07-01 --tags "health,phone"` - Scheduling via `--when`: `today`, `tomorrow`, `evening` (This Evening), `anytime`, `someday`, a date (`2026-07-01`), or a datetime (`"2026-07-01 18:00"` → adds a reminder). - Into a list/heading: `--list "Travel" --heading "Before"` (or `--list-id=<ID>`). - Checklist: repeat `--checklist-item "Passport" --checklist-item "Tickets"` (max 100). - Multiple at once: `--titles "Milk,Beer,Cheese"` (other flags apply to all). - From STDIN (first line = title, rest = notes): `printf 'Title\nNote line\n' | things add -` - **Update todo (needs auth token):** `things update --id=<ID> "New title" --when today --append-notes "..." --add-tags "urgent"` - Notes: `--notes` replaces; `--prepend-notes` / `--append-notes` add. Same pattern for `--checklist-item` (replace) vs `--prepend-checklist-item` / `--append-checklist-item`. - Tags: `--tags` replaces; `--add-tags` adds. - Move: `--list "Travel" --heading "Before"`. Complete/cancel: `--completed` / `--canceled`. - `--duplicate` updates a copy and leaves the original untouched. - **Areas & projects:** `things add-area "Health"`; `things add-project "New Site" --area "Work" --notes "..." --todo "Task A" --todo "Task B"` - `things update-project --id=<ID> --auth-token=$THINGS_AUTH_TOKEN "New Title" --when tomorrow --add-tags Important` (same notes/tags/scheduling flags as `update`, plus `--area` to move, `--todo` to append todos). - `things update-area --id=<ID> --add-tags Focus` (AppleScript-based; only updates tags; may prompt for automation permission). Notes on the CLI write surface: `update`/`update-project`/`update-area` only modify existing items. Repeating todos/projects reject `--when`, `--deadline`, `--completed`, `--canceled`. There is no real "delete" — complete or cancel instead. --- ## 2. URL scheme (`things:///...`) — any device, write-only Use when building something to open on an **iPhone** (or any device without terminal access). You construct the URL; it executes only when opened on a device that has Things installed. Cannot read state. Form: `things:///command?param1=value1&param2=value2`. All values are **percent-encoded** (space → `%20`, newline → `%0a`, comma stays literal in tag/list lists). `add` needs no token; `update`, `update-project`, and `json`-with-changes need `auth-token=$THINGS_AUTH_TOKEN`. Quick examples: - Capture to Inbox: `things:///add?title=Buy%20milk&notes=Low%20fat` - Schedule with a tag: `things:///add?title=Call%20doctor&when=next%20monday&tags=Errand` (natural-language dates must be English) - Into a project with a checklist: `things:///add?title=Trip%20prep&list=Travel&checklist-items=Passport%0aTickets` - Several todos: `things:///add?titles=Milk%0aBeer%0aCheese&list=Shopping` - Reschedule an existing todo: `things:///update?id=<ID>&auth-token=$THINGS_AUTH_TOKEN&when=today` - Show a built-in list: `things:///show?id=today` (ids: `inbox`, `today`, `anytime`, `upcoming`, `someday`, `logbook`, `deadlines`, etc.) The `json` batch command builds a whole project — headings, todos, notes, checklists — in one URL. For the full per-parameter reference, the `json` schema, date-string formats, and `show`/`search` ids, **read `references/url-scheme.md`** before constructing anything beyond a simple `add`. When the agent is on the Mac, prefer generating these URLs via `things --dry-run <command> ...`, which prints a correctly-encoded URL you can hand off. Otherwise encode by hand or with a small script. --- ## 3. Email-to-Things — headless capture, Inbox only The only modality that needs neither a Mac nor any device interaction, so it is the one a remote/NAS routine uses. Send an email to the mail-to-Things address (`$THINGS_EMAIL`): - **Subject → to-do title. Body → notes.** - Lands in the **Inbox only.** No scheduling, no tags, no project/area placement, no updates. Triage happens later on desktop. Use it for unattended capture (a cron job dropping raw items); reach for the CLI or URL scheme whenever scheduling or placement matters. --- ## Gotchas - **CLI is macOS-only.** It needs the Things app and its local DB present. - **Reading state (Inbox/Today/search/projects/areas/tags) only works via the CLI** against the local DB. URL scheme and email cannot read anything back. - **`update` / `update-project` / `json`-with-changes require the auth token.** Plain `add` does not. - **A `things:///` URL does nothing until opened on a device with Things.** Constructing it is not executing it. - **Email is Inbox-only** — no scheduling, no placement, no updates. - **Preview CLI writes with `--dry-run`** before running anything destructive or unfamiliar. - **Natural-language dates (`next monday`, `in 3 days`) must be in English**, regardless of device language. `yyyy-mm-dd` and `today`/`tomorrow` always work. - **No true delete** — complete (`--completed`) or cancel (`--canceled`) instead. The CLI's `--when=someday` and `--later` (This Evening) are the scheduling aliases. - **Renaming/deleting areas and deleting projects aren't in the `things` CLI or URL scheme — but `osascript` (AppleScript) does all of them.** `update-area` exposes tags only, and there's no `delete-area`/`delete-project`, so via those two modalities you can only *create* areas/projects and *reassign* todos (`update --list "..."`). The fourth path is AppleScript against the scriptable Things app — use it on the Mac for exactly these structural edits: - Rename an area: `osascript -e 'tell application "Things3" to set name of area "Hobby" to "Side"'` - Delete an area: `osascript -e 'tell application "Things3" to delete area "Strata"'` - Delete a project (its to-dos go with it): `osascript -e 'tell application "Things3" to delete project "Old Project"'` - List/identify first: `osascript -e 'tell application "Things3" to get name of every area'` Deletes move items to Things' Trash (recoverable until emptied), not a hard purge. The first `osascript` call may trigger a one-time macOS automation-permission prompt. This is Mac-only and needs no auth token. (The CLI's `update-project --id=<ID> --auth-token=$THINGS_AUTH_TOKEN --canceled` is a softer alternative that sends a project to the Logbook instead of deleting.) - **Clearing a value via URL:** include the param with an empty value, e.g. `&deadline=` removes a deadline.