google-tasks

Manage Google Tasks for creating, listing, completing, and organizing tasks. Supports two backends: gog CLI (recommended) or direct API via curl.

Option A: Using gog CLI (Recommended)

If you have gog installed and configured (gog auth add), use the gog tasks subcommands.

Setup

bash

# If gog is already configured for Gmail/Calendar, add Tasks scope:
gog auth add you@gmail.com --services tasks
export GOG_ACCOUNT=you@gmail.com

List task lists

bash

gog tasks list --json

List tasks

bash

gog tasks get <tasklistId> --json

Show only incomplete tasks:

bash

gog tasks get <tasklistId> --json --show-completed=false

Create a task

bash

gog tasks create <tasklistId> --title "Buy groceries"

With due date and notes:

bash

gog tasks create <tasklistId> --title "Review PR" --notes "Check auth changes" --due "2026-02-15T00:00:00Z"

Complete a task

bash

gog tasks done <tasklistId> <taskId>

Uncomplete a task

bash

gog tasks undo <tasklistId> <taskId>

Update a task

bash

gog tasks update <tasklistId> <taskId> --title "Updated title"

Delete a task

bash

gog tasks delete <tasklistId> <taskId>

Clear completed tasks

bash

gog tasks clear <tasklistId>

Option B: Using curl + Google Tasks API

For environments without gog, use the REST API directly.

Setup (one-time)

•Create a project in Google Cloud Console
•Enable the Google Tasks API
•Create OAuth 2.0 Client ID (Desktop application)
•Download client_secret.json, note the client_id and client_secret

Authenticate

Open in browser:

code

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080&response_type=code&scope=https://www.googleapis.com/auth/tasks&access_type=offline

After authorization, exchange the code for tokens:

bash

curl -s -X POST https://oauth2.googleapis.com/token \
  -d "client_id=$GTASKS_CLIENT_ID" \
  -d "client_secret=$GTASKS_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost:8080" \
  -d "grant_type=authorization_code" | jq .

Save the refresh_token. Refresh access tokens as needed:

bash

ACCESS_TOKEN=$(curl -s -X POST https://oauth2.googleapis.com/token \
  -d "client_id=$GTASKS_CLIENT_ID" \
  -d "client_secret=$GTASKS_CLIENT_SECRET" \
  -d "refresh_token=$GTASKS_REFRESH_TOKEN" \
  -d "grant_type=refresh_token" | jq -r '.access_token')

List task lists

bash

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq '.items[] | {id, title}'

List tasks

bash

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  | jq '.items[] | {id, title, status, due, notes}'

Show only incomplete tasks:

bash

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks?showCompleted=false" \
  | jq '.items[] | {id, title, due}'

Create a task

bash

curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "notes": "Milk, eggs, bread", "due": "2026-02-15T00:00:00.000Z"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  | jq '{id, title, status}'

Complete a task

bash

curl -s -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title, status}'

Update a task

bash

curl -s -X PATCH \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "notes": "Updated notes"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title}'

Delete a task

bash

curl -s -X DELETE \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID"
# Returns 204 No Content on success

Clear completed tasks

bash

curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/clear"

Task Properties

Field	Type	Description
`title`	string	Task title (required for create)
`notes`	string	Additional details
`status`	string	`needsAction` or `completed`
`due`	string	RFC 3339 timestamp (e.g., `2026-02-15T00:00:00.000Z`)
`completed`	string	Completion date (auto-set when status = completed)
`parent`	string	Parent task ID (for subtasks)
`position`	string	Position among siblings

Notes

•Google Tasks uses only two statuses: needsAction and completed.
•The default task list ID can be retrieved by listing all task lists — it's usually named "My Tasks" or the first entry.
•gog CLI is recommended when available — it handles OAuth automatically and supports --json output.
•The curl approach works on any platform with curl and jq.
•Google Tasks API has a generous free quota (50,000 queries/day).
•Subtasks are supported via the parent field when creating tasks.