Add tasks and projects to Things 3 from the terminal

You’re in the terminal, in the middle of something, and you remember you need to call the accountant tomorrow. Switching to Things, creating a to-do and typing it in breaks your flow. You want to add it with one line, right where you are.

Things has a built-in way to do this: its URL scheme. On a Mac, the open command hands a things:/// link to the app, and Things adds the to-do:

open "things:///add?title=Call%20the%20accountant&when=tomorrow"

Every space becomes %20, every option is a URL parameter, and the terminal doesn’t tell you what Things did with it. Cultured Code documents every command in the Things URL scheme reference. Things CLI wraps the same mechanism in a normal command with flags, and it can read your lists back too, so we’ll use its things command for the rest.

What you need

Things CLI runs on macOS with Things 3 and Node.js 20 or newer. It has no dependencies. After purchasing it, connect GitHub in Polar, accept the private repository invitation, and download the source from Releases. Unzip it, open Terminal in that folder, and link the command:

npm link

You don’t need an auth token or a Things account. Things CLI writes through the official Things URL scheme, and it reads through JavaScript for Automation, Apple’s JavaScript interface for Apple events. If you’ve never sent Apple events to an app from the shell, my AppleScript by example post does it with osascript.

Add a task 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

Switch to Things. You should see the to-do in Upcoming, tagged work and money, with its deadline. Tomorrow it moves to Today on its own.

The first time something writes to Things through its URL scheme, Things asks whether to enable the feature. Click Enable.

Create a project in an area

A project is the same idea. Give it a name, an area you already have in Things, and some notes:

things project "Close the 2026 books" \
  --area "Business" \
  --notes "Everything the accountant needs by the end of January."

You should now see the project in the Business area of the Things sidebar, with the notes at the top.

If you already know the tasks, you can create the project and its tasks in one go from a Markdown file. The # line is the project, the paragraph under it becomes the project notes, ## lines are headings, and each - line is a task. Here’s a made-up example saved 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

Import it:

things import close-the-books.md

Things creates the project with its headings, tasks and notes.

Check what you added

You don’t need to switch apps to see the result. Things CLI shows today’s tasks, your projects, search results, and a single project:

things list
things projects
things search "accountant"
things show "Close the 2026 books"

Add --json when a script needs structured data instead of text:

things list today --json
things show "Close the 2026 books" --json

Update notes and complete tasks

Append a line to a project’s notes:

things note "Close the 2026 books" --append "Accountant confirmed the deadline"

Mark a task as done. The --in flag names the project the task belongs to:

things done "Export the invoices" --in "Close the 2026 books"

Open the project in Things. The new line is at the end of its notes, and the task is checked off.

There’s no delete command, on purpose. Things CLI can create, read, update and complete items, but it can’t trash them. When you want something gone, do it in the Things app.

Hand it to a coding agent

The repository includes an Agent Skill that explains this workflow to a coding agent. With it installed, you can ask for something like this at the end of a planning conversation:

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 agent writes the Markdown file, imports it, and reads the project back with --json to check it. The free Automate macOS course covers the pieces underneath, like the open command and Apple events, if you want to script other Mac apps the same way.

If something looks wrong

If nothing shows up in Things after a things add, Things may still be waiting for you to enable its URL scheme. Click Enable in the prompt, or turn it on in Things → Settings → General.

If reading fails, or macOS asked whether Terminal can control Things and you said no, open System Settings → Privacy & Security → Automation and turn on Things under your terminal app.

If a task arrives without a tag, create the tag in Things first. The URL scheme, which Things CLI writes through, doesn’t apply a tag that doesn’t exist.

If your shell says things: command not found, run npm link again from the Things CLI 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 with full MIT source.

See Things CLI → · $20 including tax, with full source code.

More tutorials for my apps →

Want me to talk about your product? You can sponsor this site.