Google Tasks CLI Skill

This skill enables you to manage Google Tasks directly from the command line using the gtasks CLI tool.

Prerequisites

Before using any commands, ensure the following requirements are met:

1. GTasks Installation

Check if gtasks is installed on the system:

CODEBLOCK0

If gtasks is not installed:

1. 1. Download the binary for your system from GitHub Releases
2. Install it:

- macOS/Linux: Move to /usr/local/bin or add to PATH - Windows: Add to a folder in your PATH environment variable

1. 3. Verify installation: INLINECODE2

IMPORTANT for Agents: Always check if gtasks is installed before attempting to use it. If the command is not found, inform the user and provide installation instructions.

2. Environment Variables

Set up Google OAuth2 credentials as environment variables:

CODEBLOCK1

How to get credentials:

1. 1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Tasks API
4. Create OAuth2 credentials (Application type: "Desktop app")
5. Note the authorized redirect URIs that gtasks uses:

- http://localhost:8080/callback
- http://localhost:8081/callback
- http://localhost:8082/callback
- http://localhost:9090/callback
- INLINECODE7

For persistent setup, use a secrets manager or a ~/.env file with restrictive permissions — do not commit these values to version control or add them to shared shell profile files:

CODEBLOCK2

2. Authentication

Once environment variables are set, authenticate with Google:

CODEBLOCK3

This will open a browser for OAuth2 authentication. The token is stored in ~/.gtasks/token.json with 0600 permissions. Verify with ls -la ~/.gtasks/token.json. If you no longer need access, run gtasks logout to revoke and delete the token.

Core Concepts

• - Task Lists: Containers that hold tasks (like "Work", "Personal", "Shopping")
• Tasks: Individual to-do items within a task list
• Task Properties: Title (required), notes/description (optional), due date (optional), status (pending/completed)

Command Structure

All commands follow this pattern:
CODEBLOCK4

Authentication

Login

gtasks login

Opens browser for Google OAuth2 authentication. Required before using any other commands.

Logout

gtasks logout

Removes stored credentials from ~/.gtasks/token.json.

Task List Management

View All Task Lists

gtasks tasklists view

Displays all task lists with numbered indices.

Output Example:
CODEBLOCK8

Create a Task List

gtasks tasklists add -t "Work Projects"
gtasks tasklists add --title "Shopping List"

Creates a new task list with the specified title.

Flags:

• - -t, --title: Task list title (required)

Delete a Task List

gtasks tasklists rm

Interactive prompt to select and delete a task list.

Update Task List Title

gtasks tasklists update -t "New Title"

Interactive prompt to select a task list and update its title.

Flags:

• - -t, --title: New title for the task list (required)

Task Management

All task commands can optionally specify a task list using the -l flag. If omitted, you'll be prompted to select one interactively.

View Tasks

Basic view:
CODEBLOCK12

Include completed tasks:
CODEBLOCK13

Show only completed tasks:
CODEBLOCK14

Sort tasks:
CODEBLOCK15

Output formats:
CODEBLOCK16

Table Output Example:
CODEBLOCK17

JSON Output Example:
CODEBLOCK18

Create a Task

Interactive mode:

gtasks tasks add
gtasks tasks add -l "Work"

Prompts for title, notes, and due date.

Flag mode:
CODEBLOCK20

Flags:

• - -t, --title: Task title (required for non-interactive mode)
• INLINECODE17: Task notes/description (optional)
• INLINECODE18: Due date (optional, flexible format)

Date Format Examples:
The date parser supports many formats:

• - 2024-12-25 (ISO format)
• INLINECODE20
• INLINECODE21
• INLINECODE22
• INLINECODE23
• INLINECODE24

See dateparse examples for all supported formats.

Mark Task as Complete

With task number:
CODEBLOCK21

Interactive mode:

gtasks tasks done
gtasks tasks done -l "Personal"

Prompts to select a task from the list.

Delete a Task

With task number:
CODEBLOCK23

Interactive mode:

gtasks tasks rm
gtasks tasks rm -l "Work"

Prompts to select a task to delete.

View Task Details

With task number:
CODEBLOCK25

Interactive mode:
CODEBLOCK26

Output Example:
CODEBLOCK27

Common Workflows

Quick Task Creation

When a user says "add a task to my work list": CODEBLOCK28

Check Today's Tasks

CODEBLOCK29

Complete Multiple Tasks

CODEBLOCK30

View All Tasks Across Lists

Run view command multiple times for each list, or first list all task lists: CODEBLOCK31

Export Tasks

CODEBLOCK32

Best Practices

1. 1. Always check authentication first: If commands fail with authentication errors, run INLINECODE25

1. 2. Use task list flag for automation: When scripting or when the user specifies a list name, use -l flag to avoid interactive prompts

1. 3. Leverage flexible date parsing: The --due flag accepts natural language dates like "tomorrow", "next week", etc.

1. 4. Use appropriate output format:

- Table format for human-readable output - JSON for parsing/integration with other tools - CSV for spreadsheet import

1. 5. Task numbers are ephemeral: Task numbers change when tasks are added, completed, or deleted. Always view the list first to get current numbers.

1. 6. Handle missing lists gracefully: If a user specifies a non-existent list name, the command will error. Always verify list names first with gtasks tasklists view.

Error Handling

Common errors and solutions:

• - "Failed to get service" or Authentication errors:

- First, ensure environment variables are set: echo $GTASKS_CLIENT_ID - If variables are not set, export them (see Prerequisites section) - Then run gtasks login to authenticate

• - "incorrect task-list name": The specified list name doesn't exist. Use gtasks tasklists view to see available lists
• "Incorrect task number": The task number is invalid. Use gtasks tasks view to see current task numbers
• "Date format incorrect": The date string couldn't be parsed. Use formats like "2024-12-25", "tomorrow", or "Dec 25"

Examples

Example 1: Create a shopping list and add items

CODEBLOCK33

Example 2: Review and complete work tasks

CODEBLOCK34

Example 3: Add task with deadline

CODEBLOCK35

Example 4: Export completed tasks

CODEBLOCK36

Tips for Agents

Before Running Any Commands

1. 1. Check gtasks installation first:

   # Try to run gtasks version check
   gtasks --version 2>/dev/null || gtasks.exe --version 2>/dev/null
   

If this fails, inform the user that gtasks is not installed and provide installation instructions from the Prerequisites section.

1. 2. Verify environment variables are set:

CODEBLOCK38

1. 3. Check authentication status:

CODEBLOCK39

General Tips

• - When the user mentions "tasks" without specifying a tool, ask if they want to use Google Tasks
• If the user asks about their tasks, first run gtasks tasklists view to see available lists
• Always confirm which task list to use if not specified by the user
• When creating tasks with dates, prefer explicit date formats (YYYY-MM-DD) over relative terms for clarity
• Remember that task numbers are 1-indexed and change after modifications
• If a command requires interaction but you're running non-interactively, use flags to provide all required information