things-mac

通过 macOS 上的“things” CLI 管理 Things 3（通过 URL 方案添加/更新项目+todos；从本地 Things 数据库读取/搜索/列表）。当用户要求 OpenClaw 将任务添加到事物、列出收件箱/今天/即将到来、搜索任务或检查项目/区域/标签时使用。

# Things 3 CLI

Use `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.

Setup

- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `OpenClaw.app` for gateway runs).
- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.
- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.

Read-only (DB)

- `things inbox --limit 50`
- `things today`
- `things upcoming`
- `things search "query"`
- `things projects` / `things areas` / `things tags`

Write (URL scheme)

- Prefer safe preview: `things --dry-run add "Title"`
- Add: `things add "Title" --notes "..." --when today --deadline 2026-01-02`
- Bring Things to front: `things --foreground add "Title"`

Examples: add a todo

- Basic: `things add "Buy milk"`
- With notes: `things add "Buy milk" --notes "2% + bananas"`
- Into a project/area: `things add "Book flights" --list "Travel"`
- Into a project heading: `things add "Pack charger" --list "Travel" --heading "Before"`
- With tags: `things add "Call dentist" --tags "health,phone"`
- Checklist: `things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
- From STDIN (multi-line => title + notes):
  - `cat <<'EOF' | things add -`
  - `Title line`
  - `Notes line 1`
  - `Notes line 2`
  - `EOF`

Examples: modify a todo (needs auth token)

- First: get the ID (UUID column): `things search "milk" --limit 5`
- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`
- Title: `things update --id <UUID> --auth-token <TOKEN> "New title"`
- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`

Delete a todo?

- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.

Notes

- macOS-only.
- `--dry-run` prints the URL and does not open Things.

---

## 中文说明

# Things 3 CLI

使用 `things` 读取本地 Things 数据库（inbox/today/search/projects/areas/tags），并通过 Things URL scheme 添加/更新 todos。

设置

- 安装（推荐，Apple Silicon）：`GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
- 如果数据库读取失败：为调用方应用授予**完全磁盘访问权限**（手动运行时为 Terminal；网关运行时为 `OpenClaw.app`）。
- 可选：设置 `THINGSDB`（或传递 `--db`）以指向你的 `ThingsData-*` 文件夹。
- 可选：设置 `THINGS_AUTH_TOKEN` 以避免在更新操作时传递 `--auth-token`。

只读（数据库）

- `things inbox --limit 50`
- `things today`
- `things upcoming`
- `things search "query"`
- `things projects` / `things areas` / `things tags`

写入（URL scheme）

- 优先使用安全预览：`things --dry-run add "Title"`
- 添加：`things add "Title" --notes "..." --when today --deadline 2026-01-02`
- 将 Things 置于前台：`things --foreground add "Title"`

示例：添加一个 todo

- 基础：`things add "Buy milk"`
- 带备注：`things add "Buy milk" --notes "2% + bananas"`
- 添加到项目/区域：`things add "Book flights" --list "Travel"`
- 添加到项目标题下：`things add "Pack charger" --list "Travel" --heading "Before"`
- 带标签：`things add "Call dentist" --tags "health,phone"`
- 清单：`things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
- 从 STDIN 读取（多行 => 标题 + 备注）：
  - `cat <<'EOF' | things add -`
  - `Title line`
  - `Notes line 1`
  - `Notes line 2`
  - `EOF`

示例：修改一个 todo（需要 auth token）

- 首先：获取 ID（UUID 列）：`things search "milk" --limit 5`
- 认证：设置 `THINGS_AUTH_TOKEN` 或传递 `--auth-token <TOKEN>`
- 标题：`things update --id <UUID> --auth-token <TOKEN> "New title"`
- 替换备注：`things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
- 追加/前置备注：`things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
- 移动列表：`things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
- 替换/添加标签：`things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
- 完成/取消（类似软删除）：`things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
- 安全预览：`things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`

删除一个 todo？

- 目前 `things3-cli` 不支持（没有“删除/移至废纸篓”的写入命令；`things trash` 仅为只读列表）。
- 可选方案：使用 Things UI 删除/移至废纸篓，或通过 `things update` 标记为 `--completed` / `--canceled`。

备注

- 仅限 macOS。
- `--dry-run` 打印 URL 但不会打开 Things。