# Things Todo

Things 3 via things CLI: add, list, search, update, delete, verify.

- Repository: https://github.com/steipete/agent-scripts (7431 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add steipete/agent-scripts --skill things-todo -g -a claude-code -y`
Codex: `npx skills add steipete/agent-scripts --skill things-todo -g -a codex -y`
Cursor: `npx skills add steipete/agent-scripts --skill things-todo -g -a cursor -y`
Gemini CLI: `npx skills add steipete/agent-scripts --skill things-todo -g -a gemini-cli -y`

## Description

Things 3 via things CLI: add, list, search, update, delete, verify.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Things Todo

Use this for Things 3 tasks on Peter's Macs. Prefer `things` for Things-backed
todos; use `$reminders` only when the user asks for Apple Reminders.

## Tool

- CLI: `things`
- Repo: `https://github.com/ossianhempel/things3-cli`
- Install:

```bash
GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest
```

Auth for update URL operations:

```bash
source ~/.profile >/dev/null 2>&1 || true
things auth
```

`THINGS_AUTH_TOKEN` should come from `~/.profile` or 1Password. Never print it.
`things update --dry-run` must redact it as `auth-token=***`.

## Start

Use JSON for scripted reads and verification:

```bash
things tasks --format json --limit 20
things today --format json
things search "query" --format json
```

Things DB reads may need Full Disk Access for the calling app. Writes should go
through Things URL Scheme or AppleScript via `things`; do not write the SQLite DB
directly.

## Add

Default: add, then search/read back.

```bash
things add "Book LHR-SFO nonstop business flight" --notes "Nonstop only." --when tomorrow --tags travel
things tasks --search "LHR-SFO" --format json
```

Useful flags:

- `--notes "text"`
- `--when today|tomorrow|evening|anytime|someday|YYYY-MM-DD`
- `--deadline YYYY-MM-DD`
- `--list "Project or Area"`
- `--tags tag1,tag2`
- `--checklist-item "text"` repeatable
- `--dry-run` to inspect the `things:///` URL without mutating.

## Update / Delete

Find the UUID first, then mutate by id:

```bash
things tasks --search "flight" --format json
things update --id <uuid> "New title" --notes "Updated notes"
things tasks --search "New title" --format json
things delete --id <uuid> --confirm <uuid>
things tasks --search "New title" --format json
things trash --search "New title" --format json
```

Always read back after writes. Delete moves items to Things Trash; verify normal
search is empty and trash search contains the item when cleanup matters.

## Conventions

The rest: https://github.com/steipete/agent-scripts/blob/HEAD/skills/things-todo/SKILL.md