📋  gtask-extractor

Export every field of your Google Tasks to JSON — including the hidden metadata the Tasks UI never shows.

CI / CD		Quality
Security		Community

gtask-extractor (binary: gtask-extractor) is a small, local, read-only CLI that snapshots a Google Tasks list to JSON — capturing not just titles and notes but updated (which doubles as the creation time), position, completed, hidden, deleted, parent, links, and assignment info from Docs/Chat. Fields the raw API drops (false, "", null, []) are all preserved.

• ✅ Read-only — requests only the tasks.readonly scope; it can never modify or delete tasks.
• ✅ Captures every field — its own JSON envelope preserves values the Google client would drop.
• ✅ Two modes — a friendly interactive picker, or a scriptable gtask-extractor export --list <id> / --all.
• ✅ Runs locally — your data never leaves your machine; there is no server.

$ gtask-extractor
Your task lists:
#  TITLE         UPDATED     ID
1  My Tasks      2026-08-10  MTIzNDU2Nzg5MDEyMzQ1Njc4OTA
2  Work          2026-08-11  Nzg5MDEyMzQ1Njc4OTAxMjM0NTY
3  Sandbox       2026-08-12  OTAxMjM0NTY3ODkwMTIzNDU2Nzg

Select a list to export [1-3] (q to quit): 3
✓ Exported 7 tasks from "Sandbox" → output/sandbox-OTAxMjM0NTY3ODkwMTIzNDU2Nzg-2026-08-12.json
  active: 5   completed: 2   hidden: 1   deleted: 1   assigned: 2

Requires Go 1.26+ (the tool uses crypto/rand.Text, errors.AsType, and reflect.Type.Fields).

Once a release is tagged, cross-platform archives are published via GoReleaser on the releases page. Install the latest into ~/.local/bin (user-writable, no sudo) with a single copy-paste — gtask-extractor update can self-update it in place afterward:

# Install the latest gtask-extractor release into ~/.local/bin
VER=$(curl -fsSL https://api.github.com/repos/mrz1836/gtask-extractor/releases/latest | grep '"tag_name"' | cut -d'"' -f4 | tr -d v)
OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
mkdir -p ~/.local/bin
curl -fsSL "https://github.com/mrz1836/gtask-extractor/releases/download/v${VER}/gtask-extractor_${VER}_${OS}_${ARCH}.tar.gz" | tar -xzf - -C ~/.local/bin gtask-extractor
gtask-extractor --version

If gtask-extractor isn't found afterward, add ~/.local/bin to your PATH (export PATH="$HOME/.local/bin:$PATH" in your ~/.zshrc or ~/.bashrc).

Binaries installed from a release archive self-update:

gtask-extractor update            # install the latest release (verifies the SHA-256 checksum)
gtask-extractor update --check    # only report whether a newer version exists
gtask-extractor update --force    # reinstall even if already current

It installs only from the project's GitHub release archives and refuses to overwrite a binary managed by go install or Homebrew. gtask-extractor also prints a one-line notice when a newer version is available — opt out with GTASK_EXTRACTOR_NO_UPDATE_CHECK=1, NO_UPDATE_CHECK=1, or by running in CI.

git clone https://github.com/mrz1836/gtask-extractor.git
cd gtask-extractor
go build -o bin/gtask-extractor ./cmd/gtask-extractor
./bin/gtask-extractor version

Your tasks live in a personal Google (Gmail) account. Service accounts and domain-wide delegation only apply to Google Workspace orgs — they cannot read a personal account's tasks. The only supported path is the OAuth 2.0 installed-app flow (loopback redirect + PKCE), so you need a credentials.json describing an OAuth Desktop app client. This is a one-time, ~5-minute setup in the Google Cloud Console.

⚠️ Common misconception: access is not granted through myactivity.google.com, a Google Search Services Settings page, or any "Connect Google Workspace" / "search services" screen. The only place you configure access is the Google Cloud Console, and the only "allow" you ever click is the browser consent screen this tool opens for you.

1. Create (or select) a project at https://console.cloud.google.com/projectcreate.
2. Enable the Google Tasks API: https://console.cloud.google.com/apis/library/tasks.googleapis.com → Enable.
3. Configure the OAuth consent screen (APIs & Services → OAuth consent screen, newer UI: Google Auth Platform):
   • User type / Audience: External → Create.
   • App name (anything), your email for support + developer contact. Save.
   • Add yourself as a Test user — the step that trips people up. Under Test users (newer UI: Google Auth Platform → Audience → Test users) add the exact Gmail you'll sign in with. In Testing mode only listed testers can authorize; anyone else gets "Access blocked … has not completed the Google verification process" (Error 403: access_denied).
4. Create the OAuth client ID (Credentials → Create credentials → OAuth client ID, newer UI: Clients → Create client) → Application type Desktop app → Create.
5. Download the JSON and save it as credentials.json in the directory where you'll run gtask-extractor.

credentials.json identifies the app; it is not a password, but it is still a secret — it's git-ignored by this repo.

gtask-extractor            # opens the browser once for read-only consent
# → pick a list from the numbered menu; JSON lands in ./output/

Examples call the binary as gtask-extractor (on your PATH). From a source build use the full path, e.g. ./bin/gtask-extractor.

On the first run a browser opens to Google's consent screen. Sign in with the Test-user account → "Google hasn't verified this app" → Advanced → Go to <your app name> (unsafe) → approve "View your tasks". The token is cached to token.json (0600), so later runs are silent — no browser. If the browser can't open (e.g. over SSH), the URL is printed to paste anywhere.

gtask-extractor has two modes: a friendly interactive picker (default) and a scriptable export subcommand.

gtask-extractor

Prints a numbered table of your task lists (with IDs); type a number to export one (or q to quit), then it offers to export another. Needs a terminal — if stdin/stdout aren't a TTY it exits 2 (use export below for scripts).

gtask-extractor export --list <id>                 # one list
gtask-extractor export --list <id> --list <id>     # several (repeat --list)
gtask-extractor export --all                       # every task list

# Nightly snapshot of everything into a dated folder
gtask-extractor export --all --output-dir "backups/$(date +%F)"

--list and --all are mutually exclusive; an unknown ID exits 2. The first run still opens the browser once; afterward the cached token is reused, so export runs unattended.

Global (apply to every command):

Subcommands: gtask-extractor export …, gtask-extractor update (self-update; alias upgrade), gtask-extractor version.

The machine-facing result (✓ Exported N tasks … → <path>) goes to stdout; prompts, progress, and the counts breakdown go to stderr — so gtask-extractor export --list <id> >paths.txt captures just the file paths.

Exit codes: 0 success · 2 usage / not a TTY / bad flags · 3 credentials or consent problem · 4 API/network failure · 5 failed to write output · 130 interrupted (Ctrl-C).

Each export is a single JSON document. Every field is always present — a task that was never completed still has "completed": null, a top-level task still has "parent": "", and so on. The raw Google API omits these; capturing them is the whole point.

{
  "schemaVersion": "1.0",
  "export": {
    "generatedAt": "2026-08-12T15:04:05Z",
    "tool": "gtask-extractor",
    "toolVersion": "1.0.0",
    "scope": "https://www.googleapis.com/auth/tasks.readonly",
    "listId": "MDEyMzQ1",
    "listTitle": "Sandbox",
    "counts": { "total": 7, "needsAction": 5, "completed": 2, "deleted": 1, "hidden": 1, "assigned": 2, "subtasks": 1, "topLevel": 6 }
  },
  "list": {
    "kind": "tasks#taskList",
    "id": "MDEyMzQ1",
    "etag": "\"etag-list\"",
    "title": "Sandbox",
    "updated": "2026-08-01T12:00:00.000Z",
    "selfLink": "https://tasks.googleapis.com/tasks/v1/users/@me/lists/MDEyMzQ1"
  },
  "tasks": [
    {
      "kind": "tasks#task",
      "id": "t1",
      "etag": "\"etag1\"",
      "title": "Buy groceries",
      "notes": "milk & eggs",
      "status": "needsAction",
      "updated": "2026-08-02T10:00:00.000Z",
      "selfLink": "https://tasks.googleapis.com/tasks/v1/lists/MDEyMzQ1/tasks/t1",
      "parent": "",
      "position": "00000000000000000000",
      "due": "2026-08-10T00:00:00.000Z",
      "completed": null,
      "deleted": false,
      "hidden": false,
      "links": [],
      "webViewLink": "https://tasks.google.com/task/t1",
      "assignmentInfo": null
    }
  ]
}

• Read-only. Requests only https://www.googleapis.com/auth/tasks.readonly. It cannot create, edit, or delete tasks.
• Local only. All processing happens on your machine; nothing is uploaded anywhere.
• Secrets stay put. credentials.json and token.json are git-ignored; the token cache the tool writes (token.json) is created atomically with 0600 permissions. Exported data under output/ is git-ignored too.
• Revoke any time at https://myaccount.google.com/permissions. To reset locally, delete token.json.
• Minimal, trusted dependencies — the official Google API client, the Go team's golang.org/x/oauth2 and golang.org/x/term, and Cobra. No heavyweight TUI or browser-launching third-party packages.

Read the full security policy.

All unit tests run via GitHub Actions on Go 1.26.x and make zero network requests — the Google API is exercised through an in-process httptest server, the OAuth flow through a mocked browser + fake token endpoint, and the exporter through a fake task lister.

magex test           # run all tests (fast)
magex test:race      # run tests with the race detector
magex test:coverage  # run tests with coverage
magex lint           # golangci-lint v2 (.golangci.json) + go vet

Coverage reports are uploaded to Codecov on every commit.

magex help

.
├── cmd/gtask-extractor/        # thin entrypoint: ldflags version vars → cli.Execute
└── internal/
    ├── cli/                    # Cobra tree: interactive root, `export`, `version`, self-`update`; exit-code mapping
    ├── auth/                   # OAuth loopback + PKCE, token cache, persisting refresh
    ├── tasksclient/            # paginating wrapper around the Tasks API (generic paginate; interface)
    ├── export/                 # JSON envelope, converters, atomic writer, filename slug
    └── ui/                     # numbered list table + stdin picker (stdlib only)

Read more about this Go project's code standards.

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with AI assistants.

View the contributing guidelines and please follow the code of conduct.

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

MrZ

This project is licensed under the terms of the MIT license. See LICENSE.