AppleScript is a scripting language that allows you to automate actions in Things. This guide explains how to write scripts for working with to-dos, projects, areas, tags, and more.

If you’re new to AppleScript, the best way to get started is by reading our introductory article: Using AppleScript. You can also review Apple’s Introduction to AppleScript and Commands Reference. Come back to this page once you’re ready to write your own scripts.

Scripts are written with Apple’s Script Editor app. To inspect Things’ full suite of commands, open Script Editor and go to File → Open Dictionary... and choose Things from the list of apps.

You’ll find some example scripts below. To run them, simply paste them into Script Editor and click the ⏵ button.

AppleScript is only available for Mac. Consider using Apple Shortcuts instead; it’s available on all devices, and provides functionality that isn’t possible via AppleScript (e.g., editing headings and checklists).

  1. The Basics
  2. To-Dos
  3. Projects
  4. Areas
  5. Tags
  6. Move Items Around
  7. User Interface Interactions
  8. Integration
  9. Other Actions

The Basics

In-built lists

Each in-built list in Things’ sidebar can be accessed.

  • Inbox: list "Inbox"
  • Today: list "Today"
  • Anytime: list "Anytime"
  • Upcoming: list "Upcoming"
  • Someday: list "Someday"
  • Logbook: list "Logbook"
  • Trash: list "Trash"

These lists are predefined; you cannot create new ones using the make command. If running Things in a language that’s not English, you must use the name as it appears in the app.

Each in-built list contains collections of items which can be returned via to dos and projects. Note that the order or items returned in a collection will match their order in Things’ UI.

Example

tell application "Things3"
 set inboxToDos to to dos of list "Inbox"
 repeat with inboxToDo in inboxToDos
  --- do something with each inbox to-do using the inboxToDo variable
 end repeat
end tell

tell application "Things3"
 set upcomingToDos to to dos of list "Upcoming"
 repeat with upcomingToDo in upcomingToDos
  --- to-dos are sorted by start date, just like in Things’ UI
 end repeat
end tell

Paste examples into Apple’s Script Editor app, then click the ⏵ button to execute them.

To-Dos

Get to-dos

Access all to-dos via Things’ to dos collection. You can also access a to-do by name.

tell application "Things3"
 repeat with toDo in to dos
  --- do something with each to-do using the toDo variable
 end repeat
  
  --- get a to-do by name
  set callMom to to do named "Call mom"
end tell

Get to-dos of an in-built list

Use the collection to dos of a in-built list.

tell application "Things3"
 repeat with inboxToDo in to dos of list "Inbox"
  --- do something with each to-do using the inboxToDo variable
 end repeat
end tell

Get to-dos of a project

Access all of a Project’s to-dos using its to dos collection.

tell application "Things3"
 repeat with romeToDo in to dos of project "Vacation in Rome"
  --- do something with each to-do using the romeToDo variable
 end repeat
end tell

Get to-dos of an area

Access all of an Area’s to-dos using its to dos collection.

tell application "Things3"
 repeat with familyToDo in to dos of area "Family"
  --- do something with each to-do using the familyToDo variable
 end repeat
end tell

Create a new to-do

Use the standard make command.

tell application "Things3"
 set newToDo to make new to do ¬
  with properties {name:"New to-do", due date:current date}
end tell

You can also specify the container for the new to-do immediately. It can be one of the in-built lists, or a Project or Area that you have created.

Set a to-do’s properties

Use properties with a record for bulk setting, or set each property directly.

tell application "Things3"
 set newToDo to make new to do ¬
  with properties {name:"New to-do", due date:current date} ¬
  at beginning of list "Anytime"

 set name of newToDo to "This to-do has been renamed!"
 set notes of newToDo to "www.apple.com" & linefeed & "Call Steve for more details."
 set due date of newToDo to (current date) + 7 * days
 set completion date of newToDo to current date
 set tag names of newToDo to "Home, Mac"
end tell

Note that the due date property sets the to-do’s deadline, not its start date.

More examples:

  • Add a file link to a to-do’s notes
  • Place a to-do at the beginning of an in-built list
  • Assign a to-do to a Project or Area
tell application "Things3"
 --- add a to-do with a link to a file
 set newToDo to make new to do with properties {name:"Install Xcode", notes: "file:///Users/steve/Downloads/Xcode_26_beta.xip"} ¬
  at beginning of list "Today"

 --- put a to-do in an in-built list
 set newToDo to make new to do with properties {name:"New to-do", due date:current date} ¬
  at beginning of list "Today"

 tell list "Someday"
  set newToDo to make new to do ¬
   with properties {name:"New to-do for someday"}
 end tell

 --- put a to-do in a project
 set newToDo to make new to do ¬
  with properties {name:"Buy milk", due date:current date} ¬
  at beginning of project "Groceries"
    
 tell project "Groceries"
  set newToDo to make new to do ¬
   with properties {name:"Buy bread"}
 end tell

 --- put a to-do in an area
 set newToDo to make new to do ¬
  with properties {name:"New work to-do"} ¬
  at beginning of area "Work"
    
 tell area "Work"
  set newToDo to make new to do with properties {name:"Another work to-do"}
 end tell
end tell

Other available properties include creation date, modification date, cancellation date, and status (open/completed/canceled).

Delete a to-do

Use the standard delete command. Moves the to-do to the Trash.

tell application "Things3"
 set aToDo to to do named "To-do to remove"
 delete aToDo
end tell

Projects

Get projects

Access all Projects via Things’ projects collection. You can also access a project by name.

tell application "Things3"
 repeat with aProject in projects
  --- do something with each project using the aProject variable
 end repeat
 
 --- get a project by name
 set myProject to project "My Project"
end tell

Create a new project

Use the standard make command.

tell application "Things3"
 set newProject to make new project ¬
  with properties {name:"My Project", notes:"Some notes."}
end tell

Set a project’s properties

Use properties with a record for bulk setting, or set each property directly.

tell application "Things3"
 set newProject to make new project ¬
  with properties {name:"My Project", notes: "Some notes."}

 set name of newProject to "This project has been renamed!"
 set notes of newProject to "www.apple.com" & linefeed & "Call Steve for more details."
 set due date of newProject to (current date) + 7 * days
 set completion date of newProject to current date
 set tag names of newProject to "Home, Mac"
end tell

Note that the due date property sets the project’s deadline, not its start date.

Delete a project

Use the standard delete command. This moves the project and its children to the Trash.

tell application "Things3"
 set xProject to project named "Project to remove"
 delete xProject
end tell

Areas

Get areas

Access all Areas via Things’ areas collection. You can also access an area by name.

tell application "Things3"
 repeat with anArea in areas
  --- do something with each area using the anArea variable
 end repeat
 
 --- get an area by name
 set personalArea to area "Personal"
end tell

Create a new area

Use the standard make command.

tell application "Things3"
 set newArea to make new area ¬
  with properties {name:"Health"}
end tell

Set an area’s properties

Use properties with a record for bulk setting, or set each property directly.

tell application "Things3"
 set newArea to make new area with properties {name:"My Area", tag names:"Home, Mac"}

 set name of newArea to "This area has been renamed!"
end tell

Delete an area

Use the standard delete command. An area is not moved to the Trash, but its children will be.

tell application "Things3"
 set xArea to area named "Area to Delete"
 delete xArea
end tell

Tags

Get all tags

Access all available Tags via Things’ tags collection.

tell application "Things3"
  repeat with aTag in tags
    --- do something with each tag using the aTag variable
  end repeat
end tell

Get items’ tags

Access items’ tag names as strings or objects.

tell application "Things3"
  set aToDo to first to do of list "Inbox"

  --- output: a string (e.g. "Home, Mac")
  set tagNames to tag names of aToDo

  --- output: a list of tag objects
  set tagList to tags of aToDo
  repeat with aTag in tagList
    --- do something with each tag using the aTag variable
  end repeat
end tell

Create a new tag

Use the standard make command.

tell application "Things3"
  set newTag to make new tag with properties {name:"Home"}
end tell

Set tags

Use the tag names property.

tell application "Things3"
  set aToDo to first to do of list "Today"
  set tag names of aToDo to "Home, Mac"
end tell

Work with tag hierarchies

Use the parent tag property.

tell application "Things3"
  set homeTag to tag "Home"
  set parent tag of homeTag to tag "Places"
end tell

Delete tags

Use the standard delete command.

tell application "Things3"
  set aTag to tag "Errands"
  delete aTag
end tell

Move Items Around

Move a to-do or project to an in-built list

Use Things’ move command.

tell application "Things3"
 set newToDo to make new to do ¬
  with properties {name:"New to-do for today"} at beginning of list "Inbox"

 move newToDo to list "Today"
end tell

To move a to-do or project to the Logbook:

  • Use the standard move command, or
  • Set the status property to completed/canceled
tell application "Things3"
 --- move to Logbook
 set finishedProject to project "Things"
 move finishedProject to list "Logbook"
 
 --- move to Logbook by completing
 set finishedToDo to to do named "To-do to complete"
 set status of finishedToDo to completed
 
 --- move to Logbook by canceling
 set canceledToDo to to do named "To-do to cancel"
 set status of canceledToDo to canceled
end tell

To move an item to the Trash:

Exception: You cannot move a to-do or project to Upcoming. Use Things’ schedule command instead.

tell application "Things3"
 set toDo to first to do of list "Inbox"
 schedule toDo for (current date) + 1 * days
end tell

Move a to-do or project to a parent

  • Set a to-do’s area or project property.
  • Set a project’s area property.
tell application "Things3"
 set aToDo to to do "Buy milk"
 set aProject to project "Replace Fridge"
 
 --- move the to-do
 set area of aToDo to area "Shopping"
 set project of aToDo to project "Groceries"
 --- move the project
 set area of aProject to area "Home"
end tell

Detach a to-do or project from its parent

Use the delete command on an item’s area or project property.

tell application "Things3"
 --- detach the to-do from its project
 set orphanToDo to first to do of project named "Vacation in Rome"
 delete project of orphanToDo

 --- detach the project from its area
 set orphanProject to project "Vacation in Rome"
 delete area of orphanProject
end tell

User Interface Interactions

Get selected to-dos

Use selected to dos.

tell application "Things3"
 repeat with selectedToDo in selected to dos
  move selectedToDo to list "Today"
 end repeat
end tell

Show a to-do, project, or area

Use Things’ show command to reveal an item in the app.

tell application "Things3"
 --- navigates to the appropriate list and selects the to-do
 show to do "Book flights"

 --- selects the project/area in the sidebar and shows its contents
 show project "Vacation in Rome"
 show area "Personal"
end tell

Edit a to-do or project

Use Things’ edit command to reveal a to-do or project for editing. Not supported for areas.

tell application "Things3"
 set toDoToEdit to make new to do ¬
  with properties {name:"This title can now be edited"} ¬
  at beginning of list "Today"

 --- navigate to the to-do and expand it for editing
 edit toDoToEdit

 --- same for projects
 set projectToEdit to make new project ¬
  with properties {name:"This title can now be edited"}
 edit projectToEdit
end tell

Integration

Show the Quick Entry popover

Use Things’ show quick entry panel command. You can pre-fill its properties. You can also use autofill to grab content from other apps (if they support it).

--- show it empty
tell application "Things3"
 show quick entry panel
end tell

--- show it with pre-filled properties
tell application "Things3"
 show quick entry panel with properties ¬
  {name:"Buy flowers", notes:"She loves tulips."}
end tell

--- engage autofill to grab content from other apps (if supported)
tell application "Things3"
 show quick entry panel with autofill yes
end tell

Learn more about Quick Entry.

Other Actions

Clear properties

Set properties to nil via "" to remove values that have been set.

tell application "Things3"
 set newToDo to make new to do with properties {name:"New to-do", tag names:"Personal"}
 
 --- remove the previously-set tag
 set tag names of newToDo to ""
end tell

Empty the trash

Use Things’ empty trash command:

tell application "Things3"
 empty trash
end tell

Log completed items

If Things’ is set to log Manually, use the log completed now command.

tell application "Things3"
 log completed now
end tell
Related Articles