Start

Install

things-cli runs on macOS and ships as a single static Go binary. Pick whichever install method fits your workflow.

You’ll need Things3. This CLI talks to the Things3 app by Cultured Code — a paid task manager for macOS, iPad, iPhone, and Apple Watch. It must be installed and have been launched at least once for the database to exist. things-cli is an independent third-party tool and is not affiliated with Cultured Code.

Homebrew

brew install ryanlewis/tap/things

Or, if you’d rather add the tap explicitly:

brew tap ryanlewis/tap
brew install things

The cask is auto-published from each tagged release into ryanlewis/homebrew-tap.

One-line install script

curl -fsSL https://raw.githubusercontent.com/ryanlewis/things-cli/main/install.sh | sh

Downloads the latest release for your architecture, verifies the checksum against checksums.txt, and installs the things binary to /usr/local/bin.

The script reads three optional environment variables:

# Install somewhere other than /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/ryanlewis/things-cli/main/install.sh | INSTALL_DIR=$HOME/.local/bin sh

# Pin a specific version (defaults to the latest release)
curl -fsSL https://raw.githubusercontent.com/ryanlewis/things-cli/main/install.sh | VERSION=vX.Y.Z sh

# Override the asset download base URL (for mirrors / testing)
curl -fsSL https://raw.githubusercontent.com/ryanlewis/things-cli/main/install.sh | RELEASE_BASE_URL=https://example.com/things sh

go install

If you have a recent Go toolchain:

go install github.com/ryanlewis/things-cli/cmd/things@latest

The binary lands in $GOBIN (or $GOPATH/bin) as things.

Prebuilt binary

Grab a .tar.gz from the latest release:

things_<version>_darwin_arm64.tar.gz — Apple Silicon
things_<version>_darwin_amd64.tar.gz — Intel

Extract, move things onto your $PATH, and you’re done.

tar -xzf things_<version>_darwin_arm64.tar.gz
mv things /usr/local/bin/
things --version

Updating

things update

Updates the CLI the same way you installed it: Homebrew, the install script, or go install. Add --dry-run to see the command without running it. If it cannot reach GitHub to check the latest release, it stops rather than risk installing an older version (Homebrew excepted). See things update.

Verifying the install

things --version       # prints the build version
things                 # default view: today

The first invocation reads the Things3 database from ~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/ThingsData-*/Things Database.thingsdatabase/main.sqlite in read-only mode. Things3 must be installed and have been launched at least once for the database to exist.

If a command says the database is missing or cannot be opened, run things doctor. It tells a missing database apart from macOS refusing access, and reads no task data. See things doctor.

Quickstart

# What's on today
things

# Inbox, upcoming, anytime — all built-in views
things inbox
things upcoming -t urgent

# Capture a task
things add "Buy milk" --when today --tags errand,shopping

# Show, edit, complete
things show 3
things edit 3 --add-tags urgent --deadline 2026-05-01
things complete 3

# Reveal in the Things app
things open today

Every read command takes -j / --json for structured output:

things upcoming --json | jq '.[] | select(.deadline)'