Add tasks and projects to Things 3 from the terminal
By Flavio
Updated
Add Things 3 to-dos with a date, deadline and tags from the terminal, import a whole project from Markdown, and read it back as text or JSON with Things CLI.
For a whole project from a discussion, see Let a coding agent turn a conversation into a Things project.
You’re in the terminal and you remember you need to call the accountant tomorrow. Things has a URL scheme for this, and on a Mac the open command hands a things:/// link to the app:
open "things:///add?title=Call%20the%20accountant&when=tomorrow"
Every space becomes %20, every option is a URL parameter, and nothing tells you what Things did with it. Cultured Code documents every parameter in the Things URL scheme reference.
Things CLI builds those URLs for you, and it can read your lists back, which the URL scheme can’t. It writes through the URL scheme and reads through JavaScript for Automation, the same Apple events AppleScript uses:
Install it
Things CLI needs macOS, Things 3 and Node.js 20 or newer, and it has no dependencies. Download the source zip from your Polar receipt, unzip it, and link the command from that folder:
npm link
No auth token, no Things account. To check it works without touching Things, ask it what it can do. This one doesn’t talk to the app at all:
things capabilities
things 0.1.1
Add, read and update projects, to-dos and notes in Things 3.
What it can do:
Add a to-do to a project with notes, schedule and tags
$ things add "Renew the domain" --project "Website" --when today --tags work
Create a new project in an area
$ things project "Launch newsletter redesign" --area "flaviocopes.com" --notes "Ship by October"
Import a whole project from a Markdown or JSON file
$ things import sponsors.md
...
Add a to-do with a date, deadline and tags
Here’s the call to the accountant, scheduled for tomorrow, with a deadline and two tags:
things add "Call the accountant" \
--when tomorrow \
--deadline 2026-11-16 \
--tags work,money
It prints Added "Call the accountant". Behind the scenes it opens this URL:
things:///add?title=Call%20the%20accountant&when=tomorrow&deadline=2026-11-16&tags=work%2Cmoney
Add --json to things add and it prints that URL too.
--when is the day you plan to work on it: today, tomorrow, evening, someday or a date like 2026-11-12. --deadline is when it has to be done. The to-do lands in Upcoming and moves to Today tomorrow.
Things ignores tags that don’t exist yet, so create work and money in Things first. --project and --heading put the to-do inside a project, and --checklist "passport,charger" adds checklist items.
Create a project from Markdown
things project creates an empty project:
things project "Close the 2026 books" \
--area "Business" \
--notes "Everything the accountant needs by the end of January."
things areas lists the areas you can use.
When you already know the tasks, write the project in Markdown and import it in one go. The # line is the project, the text under it becomes the project notes, ## lines are headings, - lines are to-dos, and indented lines under a to-do are its notes. Save this as close-the-books.md:
# Close the 2026 books
Everything the accountant needs by the end of January.
## Invoices
- Export the invoices
One CSV for the whole year.
- Match bank payments to invoices
## Expenses
- Collect the receipts
- Send the folder to the accountant
Then:
things import close-the-books.md
It prints the project name with the count of to-dos and headings it sent, here 4 to-dos and 2 headings. The CLI turns the file into this payload and sends it in a single things:///json URL:
{
"type": "project",
"attributes": {
"title": "Close the 2026 books",
"notes": "Everything the accountant needs by the end of January.",
"items": [
{ "type": "heading", "attributes": { "title": "Invoices" } },
{ "type": "to-do", "attributes": { "title": "Export the invoices", "notes": "One CSV for the whole year." } },
{ "type": "to-do", "attributes": { "title": "Match bank payments to invoices" } },
{ "type": "heading", "attributes": { "title": "Expenses" } },
{ "type": "to-do", "attributes": { "title": "Collect the receipts" } },
{ "type": "to-do", "attributes": { "title": "Send the folder to the accountant" } }
]
}
}
The parser is strict. Here’s what it does with a few lines that look fine but aren’t:
| Line in the file | Result |
|---|---|
One CSV for the whole year. indented under a to-do | That to-do’s notes |
One CSV for the whole year. not indented, after a to-do | Stops with Cannot parse line: "One CSV for the whole year." |
- [ ] Export the invoices | A to-do titled [ ] Export the invoices |
1. Export the invoices, before the first to-do | Added to the project notes |
A file without a # line | Stops with Project markdown needs a "# Title" line |
When it stops, nothing reaches Things, so fix the line and run it again.
The Markdown format has no area, so move the project in Things afterwards. And every import creates a new project, so importing the same file twice gives you two projects with the same name.
Read it back
The read commands print plain text, one line per item. Here’s things show on a fictional pottery studio project, from the Things CLI demo:

things list takes today (the default), inbox, upcoming, anytime, someday or logbook. things projects shows each project with its area and how many to-dos it has, and things areas the number of projects in each area:

To check the import from before:
things show "Close the 2026 books"
things search "accountant"
search looks through the names and notes of open to-dos only, so it doesn’t return projects or completed to-dos. It reads every to-do in Things, which takes under 3 seconds on my database. The other read commands take well under a second.
Add --json when a script or an agent reads the result. Every to-do comes with id, name, notes, status, tags, dueDate, activationDate, project and area. --when ends up in activationDate and --deadline in dueDate:
things list upcoming --json
things show "Close the 2026 books" --json
Update notes and complete to-dos
Append a line to the project notes:
things note "Close the 2026 books" --append "Accountant confirmed the deadline"
--append adds a blank line and then your text. --set replaces the notes, and --file notes.md sets them from a file, which is easier than quoting a long text in the shell.
Mark a to-do done. --in names its project:
things done "Export the invoices" --in "Close the 2026 books"
Names are matched exactly, case included, and the first match wins. Without --in, note and done look for a project with that name first, then for any to-do. So keep project names unique, and pass --in when two projects have a to-do with the same name.
There’s no delete command, on purpose. Trash things from the Things app.
Hand it to a coding agent
The source includes an Agent Skill at .agents/skills/things/SKILL.md that teaches an agent this workflow: read before updating, use --json, write a Markdown file and import it, then check the result with things show. At the end of a planning conversation you can ask:
Turn the tasks we agreed on into a Things project. Keep the background
in the project notes, group the work under headings, then show me the
imported project. Don't change anything else in Things.
The free Automate macOS course covers the pieces underneath, like the open command and Apple events.
If something looks wrong
If an add does nothing, check that Things URLs are enabled in Things → Settings → General.
If a read fails, or you clicked Don’t Allow when macOS asked whether your terminal can control Things, open System Settings → Privacy & Security → Automation and turn on Things under your terminal app.
A name that doesn’t match exits with status 1:
Project not found: Close the 2025 books
A wrong list name prints the ones it knows:
Unknown list "someplace". Use one of: inbox, today, upcoming, anytime, someday, logbook, trash
If the shell says things: command not found, run npm link again from the unzipped folder, and check that node --version prints 20 or newer.
Get Things CLI
Create, read and update Things 3 projects and tasks from your terminal or coding agent. A macOS command-line tool.
See Things CLI → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.