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
INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/ryanlewis/things-cli/main/install.sh | sh

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

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

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.

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)'