gtcli - Google Tasks CLI

A fast, minimal command-line interface for Google Tasks. Manage your task lists and tasks directly from the terminal with simple, intuitive commands.

Features

• Multi-account support - Manage tasks across multiple Google accounts
• Full CRUD operations - Create, read, update, delete tasks and task lists
• Subtasks - Create hierarchical task structures with parent-child relationships
• Tab-separated output - Easy to parse with standard Unix tools
• Secure OAuth2 - Browser-based or manual authentication flow
• Cross-platform - Works on macOS, Linux, and Windows

Install

npm install -g @tjboudreaux/gtcli

Setup

Before using gtcli, you need OAuth2 credentials from Google Cloud Console:

1. Create a new project (or select existing)
2. Enable the Google Tasks API
3. Set app name in OAuth branding
4. Add test users (all Google accounts you want to use)
5. Create OAuth client:
   • Click "Create Client"
   • Application type: "Desktop app"
   • Download the JSON file

Then configure gtcli:

gtcli accounts credentials ~/path/to/credentials.json
gtcli accounts add [email protected]

Usage

gtcli accounts <action>                    Account management
gtcli <email> lists [command] [options]    Task list operations
gtcli <email> tasks <listId> [command]     Task operations

Commands

accounts

gtcli accounts credentials <file.json>   # Set OAuth credentials (once)
gtcli accounts list                      # List configured accounts
gtcli accounts add <email>               # Add account (opens browser)
gtcli accounts add <email> --manual      # Add account (browserless, paste redirect URL)
gtcli accounts remove <email>            # Remove account

lists

# List all task lists
gtcli <email> lists [--max N] [--page TOKEN]

# Task list operations
gtcli <email> lists get <listId>
gtcli <email> lists create <title>
gtcli <email> lists update <listId> --title <title>
gtcli <email> lists delete <listId>
gtcli <email> lists url <listIds...>

tasks

# List tasks in a task list
gtcli <email> tasks <listId> [--completed] [--hidden] [--max N]

# Task operations
gtcli <email> tasks <listId> get <taskId>
gtcli <email> tasks <listId> create <title> [--notes N] [--due DATE] [--parent ID]
gtcli <email> tasks <listId> update <taskId> [--title T] [--notes N] [--due DATE] [--status STATUS]
gtcli <email> tasks <listId> complete <taskId>
gtcli <email> tasks <listId> uncomplete <taskId>
gtcli <email> tasks <listId> delete <taskId>
gtcli <email> tasks <listId> move <taskId> [--parent ID] [--previous ID]
gtcli <email> tasks <listId> clear
gtcli <email> tasks <listId> url <taskIds...>

Status options: needsAction, completed

Due date format: RFC 3339 timestamp (e.g., 2024-12-31T00:00:00Z)

Examples

# List all task lists
gtcli [email protected] lists

# Create a new task list
gtcli [email protected] lists create "Shopping List"

# List tasks in default task list (use list ID from 'lists' command)
gtcli [email protected] tasks MTIzNDU2Nzg5

# Create a task with due date
gtcli [email protected] tasks MTIzNDU2Nzg5 create "Buy groceries" --due "2024-12-31T00:00:00Z"

# Create a task with notes
gtcli [email protected] tasks MTIzNDU2Nzg5 create "Call mom" --notes "Ask about dinner plans"

# Mark task as completed
gtcli [email protected] tasks MTIzNDU2Nzg5 complete TASK_ID

# List completed tasks
gtcli [email protected] tasks MTIzNDU2Nzg5 --completed

# Clear all completed tasks
gtcli [email protected] tasks MTIzNDU2Nzg5 clear

# Create a subtask
gtcli [email protected] tasks MTIzNDU2Nzg5 create "Buy milk" --parent PARENT_TASK_ID

# Move task to different position
gtcli [email protected] tasks MTIzNDU2Nzg5 move TASK_ID --previous SIBLING_TASK_ID

Data Storage

All data is stored in ~/.gtcli/:

• credentials.json - OAuth client credentials
• accounts.json - Account tokens

Development

npm install
npm run build
npm run check
npm test

Acknowledgements

Inspired by:

• gmcli - Gmail CLI by badlogic
• gdcli - Google Drive CLI

License

MIT