things-cli

A command-line interface for Things 3 — read and manage your tasks from the terminal.

Reads are direct (via the things.py library against your local Things database); writes go through the Things URL scheme. Things 3 must be installed on the same Mac. See docs/plans/2026-08-09-001-feat-things-3-cli-plan.md for the full design.

Install

git clone https://github.com/crowlede/things-cli.git
cd things-cli
pip install -e .

Setup: enable the Things URL scheme

add works out of the box. complete and edit need a Things auth token:

1. Open Things 3 → Settings → General → Enable Things URLs → Manage.
2. Copy the token shown there. things-cli reads it automatically at runtime — no config file needed.

If the token isn't enabled, complete/edit will tell you to do this instead of failing silently.

Usage

things list today
things list upcoming
things list inbox
things list projects
things list areas
things list "Some Project"
things search "milk"

things add "Buy milk" --notes "2%" --when today --tag errands
things complete "Buy milk"
things edit "Buy milk" --when tomorrow
things edit "Buy milk" --clear-tags   # removes all tags; --tag alone replaces them

things list today --json

Run things --help for the full command reference.

Limitations

• macOS only, and only works while you're in a real GUI session — writes go through the Things app itself, so they don't work over SSH or when logged out.
• Reads reflect Things' local database, which only updates when Things has been opened/foregrounded recently — a very fresh change may lag by a few seconds if Things itself hasn't caught up yet.
• No iOS or Things Cloud support (no public API exists).
• Checklist items can only be set when a to-do is created, not edited afterward (a Things URL-scheme limitation).