Skip to content

Simple read-only comand-line interface to your Things 3 database

Notifications You must be signed in to change notification settings


Repository files navigation

Things 3 CLI


Simple read-only comand-line interface to your Things 3 database (incl. CSV export). Since Things uses a SQLite database (which should come pre-installed on your Mac) we can simply query it straight from the command line. We only do read operations since we don't want to mess up your data.

Note that I've migrated this bash based version to a python based fork.

Codacy Badge Build Status download


You can use brew to install and later update the script:

  • Prepare: brew tap AlexanderWillner/tap
  • Install: brew install
  • Upgrade: brew upgrade
  • Bash autocompletion: brew install bash-completion. Then add to ~/.bashrc:
    if [ -f $(brew --prefix)/etc/bash_completion ]; then
      . $(brew --prefix)/etc/bash_completion
  • Zsh autocompletion: copy the file to a location you like, and add source /path/to/ to your ~/.zshrc

To uninstall just write brew uninstall

Example Graphs

These graphs have been generated based on the CSV export. For example: -r '-14 days' statcsv > lastTwoWeeks.csv && open lastTwoWeeks.csv (and then generating a Stacked Column graph).

Tasks in the last 14 days

Tasks in the last year

Tasks since using Things


Note that you could override the location of the database used by setting the THINGSDB environment variable. For usage information, run the script with no arguments or with "help":

$ --limitBy 5 help

  -l|--limitBy <number>    Limit output by <number> of results
  -w|--waitingTag <tag>    Set waiting/filter tag to <tag>
  -o|--orderBy <column>    Sort output by <column> (e.g. 'userModificationDate' or 'creationDate')
  -s|--string <string>     String <string> to search for
  -r|--range <string>      Limit CSV statistic export by <string>
  -e|--event <filename>    Event: <filename> that contains a list of tasks
  -t|--start <date>        Event: starts at <date>
  -d|--duration <days>     Event: ends after <days>

  inbox                    Shows 5 inbox tasks ordered by creationDate
  today                    Shows 5 todays tasks ordered by index
  upcoming                 Shows 5 upcoming tasks ordered by date
  next                     Shows 5 next tasks ordered by creationDate
  someday                  Shows 5 someday tasks ordered by creationDate
  completed                Shows 5 completed tasks ordered by creationDate
  cancelled                Shows 5 cancelled tasks ordered by cancel date
  trashed                  Shows 5 trashed tasks ordered by creationDate
  feedback                 Opens the feedback web page to request and propose changes
  all                      Shows 5 tasks ordered by creationDate
  csv                      Exports all tasks as semicolon seperated values incl. notes and Excel friendly
  due                      Shows 5 tasks ordered by due date
  headings                 Shows 5 headings ordered by creationDate
  mostClosed               Shows 5 days on which most tasks were closed
  mostCancelled            Shows 5 days on which most tasks were cancelled
  mostTrashed              Shows 5 days on which most tasks were trashed
  mostCreated              Shows 5 days on which most tasks were created
  mostTasks                Shows 5 projects that have most tasks
  mostCharacters           Shows 5 tasks that have most characters
  nextish                  Shows 5 nextish tasks ordered by creationDate
  old                      Shows 5 old tasks ordered by creationDate
  projects                 Shows 5 projects ordered by creationDate
  repeating                Shows 5 repeating tasks ordered by creationDate
  schedule                 Schedule an event by creating a number of related tasks
  search                   Searches for a specific task
  stat                     Provides a number of statistics about all tasks
  statcsv                  Exports some statistics as semicolon separated values for -1 year
  subtasks                 Shows 5 subtasks ordered by creationDate
  tag                      Shows 5 tasks with the tag "Waiting for" ordered by "creationDate"
  tags                     Shows 5 tags ordered by their usage
  waiting                  Shows 5 tasks with the tag "Waiting for" ordered by "creationDate"


CSV export and open with Excel csv > Things3Export.csv && open Things3Export.csv

Note that this command generates a standards compliant file. If you have problems opening it using Microsoft Excel, you might want to change some parameters. E.g., SEP=";" ENCODING="WINDOWS-1252//TRANSLIT" ./ csv > Things3Export.csv.


$ stat
Inbox     : 0
Today     : 7
Upcoming  : 156
Next      : 15
Someday   : 822

Completed : 11976
Cancelled : 9250
Trashed   : 545

Tasks     : 968
Subtasks  : 56
Waiting   : 111
Projects  : 89
Repeating : 89
Nextish   : 146
Headings  : 53

Oldest    : 2010-09-28|XXX|XXX
Farest    : 2021-01-04|XXX|XXX
Longest   : 167|XXXXXXXXXXXXXX
Largest   : 128|XXXXXXXXXXXXXX

Created   : 147|2017-07-04
Closed    : 124|2017-12-30
Cancelled : 324|2017-12-30
Trashed   : 109|2017-08-02
Days/Task : 41.0

Create Scheduled Event Scheduler

In case you have regularly to create projects based on a template (e.g., a business trip or family vacation), this can be automated using the following command:

$ --start 2018-03-20 --days 7 --event resources/exampleEvent.thingslist schedule

Note that you might have to Enable Things URLs in the Things preferences first.

Other Information

Things URL Helper

Things3 URL Helper

Since Version 3.4 has its own URL Scheme. It replaces the application that you can still find in the folder resources. By using most of the commands (e.g., csv) you can identify the according URL of each task and open it within any macOS application, such as spotlight. Above an example using a local web page. You can click on the links in by using CMD+DoupleClick.

Markdown Clipboard to Things Workflow

Demo Markdown Clipbaord to Things3

You can use the service/workflow in the folder resources to automatically convert MarkDown todos into Things 3 tasks. Above an example using To install you have two options:

  • Alfred Workflow: Download and double click on the workflow file
  • macOS Service: Download, unzip and copy the workflow file to ~/Library/Services (you may need to enable the service under System Preferences > Keyboard > Shortcuts > Services > General > Markdown Clipboard to Things)

Count Minutes Planned Today

It has some benefits to use time estimates in your to-do list. In case you're using tags like XXmin (XX = number in minutes), then there is one script in this repository that can calculate the total minutes of planned to-dos in your Today view. To install, download the service, unzip it and copy the workflow file to ~/Library/Services (you may need to enable the service under System Preferences > Keyboard > Shortcuts > Services > General > Markdown Clipboard to Things).

Minutes Planned Today in Things3