gtasks

Google Tasks CLI

gtasks: A CLI Tool for Google Tasks

Docs

Refer to the docs website to read about available commands.

AI Agent Skills

GTasks includes an embedded Agent Skill that can be installed for supported AI agents.

Supported targets:

• Claude Code via ~/.claude/skills/gtasks-cli/
• Codex-compatible agents via ~/.agents/skills/gtasks-cli/
• OpenClaw via ~/.openclaw/skills/gtasks-cli/

Commands:

gtasks skills status
gtasks skills install
gtasks skills install --agent codex
gtasks skills uninstall --agent codex

For contributors: the canonical skill files live in internal/skills/assets/gtasks-cli/.

Installation

macOS / Linux (recommended):

curl -fsSL https://gtasks.sidv.dev/install | bash

Installs to ~/.local/bin by default. Override with INSTALL_DIR:

INSTALL_DIR=/usr/local/bin curl -fsSL https://gtasks.sidv.dev/install | bash

Manual install: Download the binary for your system from releases, move it to a directory in your PATH, and chmod +x gtasks.

Go install:

go install github.com/BRO3886/gtasks@latest

Instructions to Run and Build from Source:

Prerequisites

• Go 1.24+
• Google Cloud Console OAuth2 credentials (see Configuration section)

Setup

1. Clone the repository:

git clone https://github.com/BRO3886/gtasks
cd gtasks

1. Set up credentials (see Configuration section below).

Build Commands

# Development build
make dev

# Development build with embedded credentials from .env
make dev EMBED_CREDS=1

# Build for specific platforms
make linux    # Linux (amd64 + arm64)
make windows  # Windows (amd64)
make mac      # macOS (amd64 + arm64)

# Build for all platforms
make all

# Create release packages
make release

Configuration

To use GTasks, you need to set up Google OAuth2 credentials:

1. Go to Google Cloud Console

2. Create a new project or select existing one

3. Enable the Google Tasks API

4. Create OAuth2 credentials:

   • Application type: "Web application"
   • Add authorized redirect URIs:
     • http://localhost:8080/callback
     • http://localhost:8081/callback
     • http://localhost:8082/callback
     • http://localhost:9090/callback
     • http://localhost:9091/callback

5. Supply credentials via environment variables:

export GTASKS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GTASKS_CLIENT_SECRET="your-client-secret"

Or add them to ~/.config/gtasks/config.toml (persistent, no shell profile changes needed):

[credentials]
client_id     = "your-client-id.apps.googleusercontent.com"
client_secret = "your-client-secret"

When building from source, you can also pass credentials at build time:

make dev EMBED_CREDS=1   # reads GTASKS_CLIENT_ID/SECRET from .env

Token Storage and Configuration

GTasks stores authentication tokens and the optional config file in the same directory. Discovery order (first existing directory wins):

1. $XDG_CONFIG_HOME/gtasks/ — XDG standard path; XDG_CONFIG_HOME defaults to ~/.config
2. ~/.gtasks/ — legacy path, used automatically when that directory already exists

New installations use ~/.config/gtasks/ by default.

Files stored:

See the Configuration docs for the full config file reference.

• Usage

Usage:
  gtasks [command]

Available Commands:
  help        Help about any command
  login       Logging into Google Tasks
  tasklists   View and create tasklists for currently signed-in account
  tasks       View, create, list and delete tasks in a tasklist

Flags:
  -h, --help     help for gtasks
  -t, --toggle   Help message for toggle

Use "gtasks [command] --help" for more information about a command.

Commands

Help

• To see details about a command

gtasks <COMMAND> help

Auth

• Login

gtasks login

• Logout

gtasks logout

Tasklists

• Viewing Tasklists

gtasks tasklists view

• Creating a Tasklist

gtasks tasklists add -t 'title'
gtasks tasklists add --title 'title'

• Deleting a Tasklist

gtasks tasklists rm

Tasks

• To pre-select tasklist, provide it's title as follows:

gtasks tasks -l <title> subcommand [--subcommand-flags]

Examples:

gtasks tasks [--tasklist|-l] "DSC VIT" view [--include-completed | -i]

Note: If the -l flag is not provided you will be able to choose a tasklist from the prompt

• Viewing tasks

gtasks tasks view

• Include completed tasks

gtasks tasks view -i
gtasks tasks view --include-completed

• Sort options

gtasks tasks view ... --sort [due,title,position, default=position]

• Limit results

gtasks tasks view --max 10  # Show only first 10 tasks

• Adding a task

gtasks tasks add

• Adding a recurring task

# Create 5 daily tasks starting from Feb 10
gtasks tasks add -t "Standup" -d "2025-02-10" --repeat daily --repeat-count 5

# Create weekly tasks until March 10
gtasks tasks add -t "Weekly sync" -d "2025-02-10" --repeat weekly --repeat-until "2025-03-10"

Repeat patterns: daily, weekly, monthly, yearly

• Mark task as completed

gtasks tasks done

• Undo a completed task (mark as incomplete)

gtasks tasks undo

• Clear completed tasks (hide from API)

gtasks tasks clear
gtasks tasks clear --force  # Skip confirmation

• View detailed task information (including links/URLs)

gtasks tasks info [task-number]

• Update an existing task

# Interactive mode - shows current values and prompts for changes
gtasks tasks update [task-number]

# Flag mode - update specific fields
gtasks tasks update 1 --title "New title"
gtasks tasks update 1 --note "Updated note" --due "tomorrow"

• Deleting a task

gtasks tasks rm