th is a short macOS CLI for managing Things 3 tasks from the terminal.
It reads Things data directly from the local Things database in read-only mode for speed. Creates, updates, scheduling, completion, reveal, and trash operations still go through Things' supported AppleScript automation. It never writes directly to the Things database.
- Fast task capture with notes, tags, scheduling, deadlines, and target placement.
- Fast read commands for individual to-dos, built-in lists, projects, areas, and search.
- Update commands for names, notes, schedule dates, deadlines, list/project/area moves, completion, cancellation, and app reveal.
- Script-friendly output with concise text by default,
--jsonwhen you need structured data, and--quietwhen only the exit code matters. - Destructive commands require
--yes. - Built-in diagnostics, shell completions, and macOS-only release artifacts.
brew install --cask totocaster/tap/thgo install github.com/totocaster/things-cli-go/cmd/th@latestgit clone https://github.com/totocaster/things-cli-go.git
cd things-cli-go
make installmake install builds th and copies it to ~/.local/bin/th.
- macOS.
- Things 3 installed and scriptable as
Things3. - A readable local Things database under the Things group container.
osascriptonPATH.
Check your local setup:
th doctor
th doctor --check-automation--check-automation runs an explicit read-only AppleScript check and may trigger the macOS Automation permission prompt.
| Command | Description |
|---|---|
th add "Buy milk" |
Create a to-do in Things. |
th add "Buy milk" --today --deadline 2026-05-01 --tag Errand |
Create with schedule, deadline, and tags. |
th today / th inbox |
Show common Things lists quickly. |
th list inbox|today|anytime|upcoming|someday |
List built-in Things lists. |
th list projects / th list areas |
List project and area IDs for move/create commands. |
th get <id> |
Show one to-do with status, tags, dates, and notes. |
th search <query> |
Search Things to-dos. |
th schedule <id> 2026-04-29 / th schedule <id> none |
Set or clear the scheduled date. |
th deadline <id> 2026-05-01 / th deadline <id> none |
Set or clear the deadline. |
th due <id> 2026-05-01 |
Alias for th deadline. |
th move <id> --list today |
Move a to-do to a built-in list. |
th move <id> --project <project-id> |
Move a to-do to a project. |
th complete <id> / th cancel <id> |
Complete or cancel a to-do. |
th show <id> |
Reveal a to-do in Things. |
th delete <id> --yes |
Move a to-do to Things Trash. |
th trash empty --yes |
Permanently empty all of Things Trash. |
# Capture a task for today
th add "Send invoice" --today --tag Work
# Add a task directly to a project
th add "Draft launch notes" --project JLMPPROJECT123 --deadline 2026-05-01
# Read the day plan as text
th today
# Pipe structured data to jq
th list anytime --json | jq '.[].name'
# Clear dates
th schedule JLMPABC123 none
th due JLMPABC123 none
# Move, complete, or reveal
th move JLMPABC123 --list someday
th complete JLMPABC123 --quiet
th show JLMPABC123th defaults to compact text output:
th todayUse --json for scripts and agents:
th search invoice --json
th delete JLMPABC123 --yes --jsonUse --quiet or -q to suppress successful mutating text output:
th complete JLMPABC123 --quietErrors go to stderr and return non-zero exit codes. In JSON mode, errors are emitted as structured JSON on stderr.
Temporary zsh setup:
source <(th completion zsh)Persisted setup examples:
th completion zsh > "${fpath[1]}/_th"
th completion bash > ~/.local/share/bash-completion/completions/th
th completion fish > ~/.config/fish/completions/th.fishmake check
make test-racemake check runs formatting, module tidying, unit tests, build, and non-mutating CLI smoke checks. Run make lint too when golangci-lint is installed.
Release packaging checks:
make release-check
make release-snapshotProject notes live in docs/architecture.md, docs/guidelines.md, and docs/roadmap.md.
th is released under the MIT License.