Read your Things 3 Today list from the terminal
By Flavio
Print your Things 3 Today list, Inbox and due deadlines in the terminal with Things CLI, filter them with jq, and build a read-only morning summary.
You open the terminal first thing in the morning, and the plan for the day lives in Things 3. Switching to the app to check Today, then the Inbox, then whatever deadline you forgot, breaks the flow before it starts. What you want is your Things 3 Today list printed right there, next to git status.
Things CLI reads your Things lists from the terminal. things list prints Today as plain text, and --json gives the same to-dos to scripts and coding agents. Nothing gets written: reading never changes a to-do.
By the end you’ll have a small morning script that prints Today, counts what’s waiting in the Inbox, and lists every deadline that’s due or overdue. You’ll also know how to filter Today by tag or project, and how to hand the list to a coding agent for a second opinion without letting it touch anything.
If you want to add tasks from the terminal instead, that’s covered in Add tasks and projects to Things 3 from the terminal.
What you need
Things CLI runs on macOS. It needs Things 3, which you buy separately from Cultured Code, and Node.js 20 or newer. It has no npm dependencies.
To get it, download the source zip from your Polar receipt, unzip it, and run this from the unzipped folder:
npm link
That puts a things command on your PATH. The receipt always has the latest version, so download it again when you want to update.
For the filtering and the morning script you also need jq, the command-line JSON processor. Recent versions of macOS ship it at /usr/bin/jq. If yours doesn’t, brew install jq adds it. The jq command post covers the basics.
Check both before you start:
things --version
jq --version
things 0.2.0
jq-1.7.1-apple
Your version numbers can be higher. The first time a command reads from Things, macOS asks whether your terminal app can control Things. Click OK. Without that permission every read fails.
In the examples, the to-dos, projects and areas are examples I made up for this page: a small hosting comparison site, a side project called recipe-box, and a few personal errands. The output blocks are what Things CLI prints for those to-dos.
Print your Today list
Things keeps Today inside the app, and the only way to see it is to switch windows. things list reads the same list through macOS automation and prints it in the terminal, one line per to-do. It’s the base for everything else on this page, so check it on its own first. If this command fails, the jq filters and the morning script fail too, and the error is easier to read here. It also shows you the text format the CLI uses, with deadlines and tags in brackets, which tells you what the JSON fields will hold later.
With no list name, things list reads Today:
things list
- Send the invoice to Studio Nord [due 2026-11-14, money]
- Renew the hostingpicker.dev domain [due 2026-11-17, money, work]
- Reply to the hosting support ticket [work]
They asked for the server logs from Friday.
- Review the recipe-box pull request [work]
- Book the dentist
Each to-do is a line starting with - . The brackets hold the deadline as due YYYY-MM-DD and then the tags. Notes follow on their own lines, indented by four spaces. A to-do with no deadline, tags or notes is just its name.
Under the hood, every read runs a short JavaScript for Automation script through osascript. That script asks Things for the to-dos in the list, picks a few fields from each one, and hands them back as JSON. The CLI then formats them as text. If Things isn’t running, macOS launches it for the read.
Running the command a second time prints the same thing, as long as nothing changed in Things. Reading doesn’t mark anything as seen or move it around, so there’s nothing to undo.
Check the Inbox and Upcoming before you plan
Today only shows what you scheduled for today. The to-dos you captured yesterday without a date sit in the Inbox, and the ones scheduled for later this week sit in Upcoming. If you plan your morning from Today alone, you miss both. The Inbox is where a quick idea from a call ends up, and Upcoming is where tomorrow’s deadline hides. Reading them takes one command each, and it tells you whether you need a few minutes of sorting in the app before you start. things list takes the list name as its first argument.
things list inbox
things list upcoming
- Read the Node 24 release notes
- Fix the broken link on the about page
Reported by a reader on Sunday.
- Call the accountant [due 2026-11-20, money, work]
- Draft the December newsletter [work]
The first two lines come from the Inbox, the last two from Upcoming. The text output doesn’t show the start date, only the deadline, so for Upcoming the JSON tells you more.
The lists you can read are inbox, today, upcoming, anytime, someday, logbook and trash. An empty list prints this:
(empty)
things list doesn’t read areas or projects as lists. For a project, use things show "Project name". For the names of your areas, run things areas.
When the Inbox needs sorting, things open inbox brings Things to the front with that list showing, so you can drag to-dos where they belong.
Get the same list as JSON
Text is good for reading. It’s bad for anything else, because a script can’t tell a tag from a word in the to-do’s name. Add --json and the CLI skips the formatting and prints the data the automation script returned. Every to-do comes with the same fields, so a script can filter on them without guessing. Without this step, a filter that greps the text output breaks the first time a to-do’s name contains a bracket or the word you’re filtering on. The JSON is also what a coding agent should read, for the same reason.
things list today --json
Here’s the first to-do of the output:
[
{
"id": "A1",
"name": "Send the invoice to Studio Nord",
"notes": "",
"status": "open",
"tags": "money",
"dueDate": "2026-11-14T00:00:00.000Z",
"activationDate": "2026-11-10T00:00:00.000Z",
"project": null,
"area": "Business"
}
]
The id is Things’ own identifier for the to-do. The example IDs are short placeholders.
A few fields need a closer look:
tagsis one string with the tag names separated by a comma and a space, like"money, work", not an array. A to-do without tags has an empty string.dueDateis the deadline andactivationDateis the day it’s scheduled for, the--whendate. Both arenullwhen they’re not set.- The CLI writes dates with JavaScript’s
toISOString(), so they’re in UTC and end with milliseconds andZ. projectandareaare names, ornull.
There’s no completion date. A Logbook to-do has "status": "completed", but the JSON can’t tell you which day you finished it. So “what did I do yesterday” isn’t something you can answer from things list logbook.
Filter Today by tag or project
A full Today list is fine at 9am. At 3pm, after the calls, you want only the work to-dos, or only the ones for one project. Things can filter by tag in the app, but then you’re back in the app. With the JSON from the previous step and jq, you can slice the list any way you like. Because tags is a single string, split it on ", " first, otherwise a test for work would also match a tag called homework. The filters don’t change anything in Things, they only change what you see.
Only the to-dos tagged work:
things list today --json \
| jq -r '.[] | select(.tags | split(", ") | index("work")) | .name'
Renew the hostingpicker.dev domain
Reply to the hosting support ticket
Review the recipe-box pull request
How many to-dos each project has today, with the area as a fallback for to-dos outside a project:
things list today --json \
| jq -r 'group_by(.project // .area // "No project")
| .[] | "\(.[0].project // .[0].area // "No project") (\(length))"'
Business (1)
Personal (1)
hostingpicker.dev (2)
recipe-box (1)
group_by sorts the groups by name, which is why Business comes before the lowercase project names. To count everything on Today, pipe to jq length instead.
Build a morning summary script
You can run three commands every morning, or save them as a script and run one. A script also fixes the piece that’s easy to get wrong by hand: deadlines. A to-do that was due on Friday doesn’t jump out of a long Today list, because its date sits in brackets like every other tag. So the script collects every to-do with a deadline from Today and Upcoming, keeps the ones due today or earlier, and sorts them oldest first. It only reads, so you can run it as often as you like.
Save this as ~/bin/morning, or anywhere on your PATH:
#!/bin/sh
# morning: a read-only look at Things before you start work
today=$(date +%Y-%m-%d)
echo "Today"
things list today
echo
echo "Inbox ($(things list inbox --json | jq length) to sort)"
things list inbox
echo
echo "Deadlines on or before $today"
{ things list today --json; things list upcoming --json; } | jq -rs --arg today "$today" '
add
| map(select(.dueDate != null))
| map(.due = (.dueDate | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601 | localtime | strftime("%Y-%m-%d")))
| map(select(.due <= $today))
| sort_by(.due)
| if length == 0 then "(none)" else .[] | "- \(.due) \(.name)" end'
Then make it executable:
chmod +x ~/bin/morning
The deadline part does three things. jq -s reads both JSON arrays and add joins them into one. The sub removes the milliseconds, because jq’s date parser doesn’t accept them. Then localtime turns the UTC timestamp back into your Mac’s time zone, so the date you compare is the one on your clock, not the one in London.
Example 1: the morning summary on a Tuesday
It’s Tuesday 17 November. You open the terminal and run the script:
morning
Today
- Send the invoice to Studio Nord [due 2026-11-14, money]
- Renew the hostingpicker.dev domain [due 2026-11-17, money, work]
- Reply to the hosting support ticket [work]
They asked for the server logs from Friday.
- Review the recipe-box pull request [work]
- Book the dentist
Inbox (2 to sort)
- Read the Node 24 release notes
- Fix the broken link on the about page
Reported by a reader on Sunday.
Deadlines on or before 2026-11-17
- 2026-11-14 Send the invoice to Studio Nord
- 2026-11-17 Renew the hostingpicker.dev domain
The invoice was due on Saturday, so it goes first. The domain renewal is due today. The accountant call is due on Friday 20, so it stays out. That’s the order I’d work in.
Example 2: look a week ahead instead
On Mondays you might want the whole week. Change the cutoff from today to seven days from now. On macOS, date -v+7d adds seven days:
until=$(date -v+7d +%Y-%m-%d)
{ things list today --json; things list upcoming --json; } | jq -rs --arg until "$until" '
add
| map(select(.dueDate != null))
| map(.due = (.dueDate | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601 | localtime | strftime("%Y-%m-%d")))
| map(select(.due <= $until))
| sort_by(.due)
| .[] | "- \(.due) \(.name)"'
- 2026-11-14 Send the invoice to Studio Nord
- 2026-11-17 Renew the hostingpicker.dev domain
- 2026-11-20 Call the accountant
Now the accountant call shows up too. The -v flag is the BSD date that ships with macOS; GNU date on Linux uses -d "+7 days", but Things CLI only runs on a Mac anyway.
The script reads Today and Upcoming only. If you set deadlines on to-dos in Anytime or Someday, add things list anytime --json or things list someday --json inside the braces.
Example 3: the date parser stops the script
The first version of my deadline filter passed the date straight to fromdateiso8601:
things list today --json | jq -r '.[] | select(.dueDate != null) | .dueDate | fromdateiso8601'
jq: error (at <stdin>:1): date "2026-11-14T00:00:00.000Z" does not match format "%Y-%m-%dT%H:%M:%SZ"
jq exits with status 5 and prints nothing else. Its parser wants whole seconds, and the CLI’s dates have .000 before the Z. The fix is the sub("\\.[0-9]+Z$"; "Z") in the script above, which strips the milliseconds before parsing. In a shell string you need the two backslashes, because jq reads \\. as a literal dot.
If you’d rather not touch the script for a while, there’s nothing to undo either. Delete ~/bin/morning and nothing in Things changes, because the script never wrote to it.
Let a coding agent review your day without changing anything
Sometimes you want a second opinion on the order of the day, and a coding agent is already open in the next pane. It can run the same commands you do. The risk is that Things CLI can also write: done completes a to-do, note changes notes, and delete moves to-dos to the Trash. An agent that’s trying to help might tidy up. So say up front that this is a read-only job, and ask it to use --json so it reads the fields and not your formatting. The README has a prompt for this.
Review today's tasks. Suggest what to do first, but do not change anything.
The agent runs things list today --json, maybe things list upcoming --json, and answers in the chat. Read its suggestion, then do the work yourself or tell it which single change to make.
The source zip includes an Agent Skill at .agents/skills/things/SKILL.md. Compatible agents find it and learn the workflow, including reading before updating and using --json. If your agent doesn’t pick up skills, point it at the README instead.
If you do let it change something, remember what each write does. things done marks the to-do completed. things delete moves one open to-do to the Trash, and you can drag it back from the Trash in Things. The CLI can’t empty the Trash.
For turning a planning conversation into a whole project, see Let a coding agent turn a conversation into a Things project.
If something looks wrong
If a read waits for a long time and then prints AppleEvent timed out., look for a macOS dialog asking whether your terminal can control Things. It might be behind other windows. Answer it, then run the command again.
If you clicked Don’t Allow at that dialog, reads keep failing. Open System Settings → Privacy & Security → Automation and turn on Things under your terminal app.
If you see Unknown list "tomorrow". Use one of: inbox, today, upcoming, anytime, someday, logbook, trash, you passed a list Things CLI doesn’t know. Tomorrow’s to-dos are in upcoming. The command exits with status 1.
If things list prints (empty) but the app shows to-dos, check that you’re reading the right list. things list with no argument reads Today, not the Inbox.
If jq stops with does not match format "%Y-%m-%dT%H:%M:%SZ", the milliseconds are still in the date. Add the sub("\\.[0-9]+Z$"; "Z") step before fromdateiso8601, as in Example 3.
If a deadline shows a day earlier or later than you expect, compare the raw dueDate with your time zone. The JSON is in UTC, so convert it with localtime before you compare dates.
If the tag filter finds nothing, remember that tags is a string like "money, work". Split it on ", " before you test for one tag.
If the shell says things: command not found or jq: command not found, run npm link again in the unzipped Things CLI folder, check that node --version prints 20 or newer, and install jq with brew install jq.
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 → · 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.