Things CLI

Things CLI adds a things command for Things 3 on macOS. It can create projects and tasks, read their contents, change notes and mark work complete.

Install

You need Things 3 installed separately and Node.js 20 or later. Connect your GitHub account in Polar after purchase, accept the invitation, and clone the customer repository.

From its root, install the command:

npm link
things --help

The CLI has no npm dependencies. Creation uses the Things URL scheme. Reads and updates use macOS automation, which may ask your terminal or agent for permission to control Things. Things launches when a command needs it.

Create a small project

Create a project for a fictional newsletter redesign:

things project "Newsletter redesign" --notes "Keep the existing signup form working."

Add a task to that project:

things add "Sketch the new header" --project "Newsletter redesign" --when tomorrow

Read the result back:

things show "Newsletter redesign"

--when accepts today, tomorrow, evening, someday or a YYYY-MM-DD date. You can add --deadline, comma-separated --tags, and a comma-separated --checklist when creating a task.

Import a plan from Markdown

Save this as newsletter-plan.md:

# Newsletter launch
Keep the first version small.

## Prepare
- Write the welcome email
  Explain what subscribers will receive.
- Check the signup form

## Publish
- Send a test email
- Publish the new page

Import the file and inspect the project:

things import newsletter-plan.md
things show "Newsletter launch"

The first heading becomes the project name. Text before its sections becomes project notes. Second-level headings group tasks, and indented lines beneath a task become its notes. Import creates new items; inspect Things before importing the same plan again to avoid duplicates.

Read your lists

Without a list name, things list reads Today:

things list
things list inbox
things projects
things areas
things search "newsletter"

Supported built-in lists also include Upcoming, Anytime, Someday and Logbook. list does not read custom lists or Areas. Use areas to discover Area names.

Add --json to reading commands when a script or agent needs structured output:

things show "Newsletter launch" --json
things list today --json

Update notes and complete work

Append a decision to a task’s notes:

things note "Write the welcome email" --in "Newsletter launch" --append "Use the shorter draft."

Use --set to replace notes, or --file notes.txt to read them from a file. --set - and --append - read standard input, which is useful for longer text.

Mark the task complete after doing it:

things done "Write the welcome email" --in "Newsletter launch"

Names match exactly and are case sensitive. If several items share a name, the first match wins. Pass --in for repeated task names, and read the project first when unsure. Without --in, note and completion commands look for a project before a task.

Use a coding agent

The repository includes .agents/skills/things/SKILL.md. A compatible agent can use it for requests such as “Turn this plan into a Things project, then read it back.” things capabilities --json describes the CLI without opening Things.

The CLI cannot delete items. Use Things itself to move something to Trash. Your tasks remain in Things; the CLI does not create a separate task database. Use Things’ own data and backup facilities to protect them.