Things3 Cross-Machine Sync

This repository exports your Things3 task list from a macOS host into a synced JSON file for consumption on non-Mac devices.

Features

• Full snapshot of open tasks from things3-cli.
• Deterministic JSON schema with a fixed schema_version.
• Atomic writes.
• Cron-friendly export workflow.
• TDD structure with Vitest tests.

Setup

1. Install things3-cli on the Mac host.
2. Install dependencies:
   • npm install

1) Export a snapshot (required before querying)

You must run export at least once so the snapshot exists before any query commands.

thingsmr export

For first-time setup in a synced folder, provide the destination explicitly:

thingsmr export ~/Sync/things3/things3-snapshot.json

If the path contains spaces, quote it:

thingsmr export "~/Sync/ThingsData/things3-snapshot.json"

Running thingsmr without export shows the CLI help.

This creates/updates:

• things3-snapshot.json

2) Schedule recurring exports

Use cron on the Mac host so the non-Mac side always sees fresh data.

*/5 * * * * cd /path/to/things3-mirror && thingsmr export >> ~/Library/Logs/things3-export.log 2>&1

3) Query the snapshot JSON

Query commands read the snapshot file and do not re-export unless configured to do so.

• Export path:
  • -f, --snapshot (default: ~/Sync/things3/things3-snapshot.json)

Common query commands:

thingsmr query
thingsmr query --today
thingsmr query --due-date 2026-03-07
thingsmr query --date-field due --due-date 2026-03-07
thingsmr query --snapshot /path/to/things3-snapshot.json
thingsmr tasks --status open --project Personal --limit 50
thingsmr areas
thingsmr projects
thingsmr tags
thingsmr today
thingsmr upcoming
thingsmr completed

Example output shape:

{
  "status": "ok",
  "date": "2026-03-07",
  "generated_at": "...",
  "count": 2,
  "tasks": [
    {
      "id": "..."
    }
  ]
}

Command-line options

Export mode

-c, --cli <command>             CLI binary or executable path (default: things)
<snapshot-path>                  Destination file or directory (default: ~/Sync/things3/things3-snapshot.json)
-h, --help                       Show help text

If <snapshot-path> is a directory, things3-snapshot.json is written there.

Query/exported data mode

-f, --snapshot <path>           Snapshot file to query (default: ~/Sync/things3/things3-snapshot.json)
-d, --due-date <yyyy-mm-dd>     Return tasks matching this due/schedule date
-t, --today                     Return tasks for local today (default when due-date omitted)
--date-field <due|when|any>     Match against due, when, or either
--format <json|jsonl|csv>       Output format
--status <status>               Filter by status: open, incomplete, completed, canceled, any
--project, --area, --tag         Field filters
--search <text>                 Full-text search
--query <query>                 Structured field query

If you want full help text at any time:

thingsmr --help
thingsmr query --help

Tests

• Run tests with:
  • npm test
  • npm run test:watch