Tusk

A production-grade CLI tool for Google Tasks, written in Go.

Features

• Full Google Tasks Integration - List, create, update, and delete tasks and task lists
• OAuth2 Authentication - Secure authentication using Google's OAuth2 flow with PKCE
• Default List Support - Set a default task list for faster task management
• Prefix Matching - Use short ID prefixes or names to reference tasks and lists
• Command Aliases - Quick shortcuts for common operations (tusk add, tusk ls, tusk done)
• JSON Output - Machine-readable output for scripting and automation
• Shell Completion - Tab completion for Bash, Zsh, Fish, and PowerShell
• Cross-Platform - Works on macOS, Linux, and Windows

Installation

Using Go

go install github.com/hwkd/tusk/cmd/tusk@latest

From Source

git clone https://github.com/hwkd/tusk.git
cd tusk
go build -o tusk ./cmd/tusk

Pre-built Binaries

Download the latest release from the Releases page.

Setup

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Tasks API

2. Configure OAuth2 Credentials

1. Go to APIs & Services > Credentials
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as the application type
4. Download the credentials

3. Set Environment Variables

export TUSK_CLIENT_ID="your-client-id"
export TUSK_CLIENT_SECRET="your-client-secret"

4. Authenticate

tusk auth login

This will open a browser window for Google OAuth authentication.

Usage

Task Lists

# List all task lists
tusk lists

# Create a new task list
tusk lists create --title "My List"

# Set default task list (supports name or ID prefix)
tusk lists set-default "My List"
tusk lists set-default MTc4    # Using ID prefix

# Rename a task list
tusk lists rename "My List" --title "New Name"

# Delete a task list
tusk lists delete "My List"

Tasks

# List tasks in the default list
tusk tasks list

# List tasks in a specific list
tusk tasks list --list "My List"

# Add a new task
tusk tasks add --title "Buy groceries"

# Add a task with a due date
tusk tasks add --title "Meeting" --due 2025-12-25

# Add a task with notes
tusk tasks add --title "Call mom" --notes "Wish her happy birthday"

# Complete a task (supports ID prefix or title matching)
tusk tasks complete MTc4NzM5    # Full or partial ID
tusk tasks complete MTc4        # ID prefix
tusk tasks complete "Buy groceries"  # Title match

# Edit a task
tusk tasks edit MTc4 --title "Buy organic groceries"
tusk tasks edit MTc4 --due 2025-01-15 --notes "Updated notes"

# Delete a task
tusk tasks delete MTc4
tusk tasks delete "Buy groceries"

Quick Aliases

# Add a task (alias for 'tasks add')
tusk add --title "New task"

# List tasks (alias for 'tasks list')
tusk ls

# Complete a task (alias for 'tasks complete')
tusk done MTc4
tusk done "Buy groceries"

Prefix Matching

Tusk supports prefix matching for task and list IDs, so you don't need to type full IDs:

# Instead of typing the full ID:
tusk done MTc4NzM5MTIzNDU2Nzg5MDEy

# Use just a unique prefix:
tusk done MTc4

# Or match by title (case-insensitive):
tusk done "buy groceries"

If a prefix matches multiple items, you'll be prompted to use a longer prefix.

JSON Output

All commands support JSON output for scripting:

tusk tasks list --json
tusk lists list --json

Configuration

Configuration is stored in:

• macOS: ~/Library/Application Support/tusk/config.json
• Linux: ~/.config/tusk/config.json
• Windows: %AppData%\tusk\config.json

OAuth tokens are stored in:

• macOS: ~/Library/Application Support/tusk/token.json
• Linux: ~/.config/tusk/token.json
• Windows: %AppData%\tusk\token.json

Shell Completion

Tusk provides shell completion scripts for Bash, Zsh, Fish, and PowerShell.

Bash

# Add to your ~/.bashrc or ~/.bash_profile
source <(tusk completion bash)

# Or save to a file
tusk completion bash > /etc/bash_completion.d/tusk

Zsh

# Add to your ~/.zshrc
source <(tusk completion zsh)

# Or for oh-my-zsh, save to the completions directory
tusk completion zsh > "${fpath[1]}/_tusk"

Fish

# Add completions
tusk completion fish | source

# Or save to the Fish completions directory
tusk completion fish > ~/.config/fish/completions/tusk.fish

PowerShell

# Add to your PowerShell profile
tusk completion powershell | Out-String | Invoke-Expression

# Or save to a file
tusk completion powershell > tusk.ps1
. ./tusk.ps1

Due Date Formats

The following due date formats are supported:

• ISO format: 2025-12-25
• RFC3339 format: 2025-12-25T09:00:00Z

Development

Prerequisites

• Go 1.23 or later

Building

go build -o tusk ./cmd/tusk

Testing

go test ./...

Linting

golangci-lint run

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Cobra - CLI framework
• Google Tasks API - Backend API