gtasks-cli

Example 1: Create a shopping list and add items

gtasks tasklists add -t "Shopping"
gtasks tasks add -l "Shopping" -t "Milk"
gtasks tasks add -l "Shopping" -t "Bread"
gtasks tasks add -l "Shopping" -t "Eggs"

Example 2: Review and complete work tasks

gtasks tasks view -l "Work" --sort=due
gtasks tasks done 1 -l "Work"

Example 3: Add task with deadline

gtasks tasks add -l "Work" -t "Submit proposal" -n "Include budget and timeline" -d "next Friday"

Example 4: Export completed tasks

gtasks tasks view --completed --format=json -l "Work" > completed_work.json

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

1. GTasks Installation

Check if gtasks is installed on the system:

# Cross-platform check (works on macOS, Linux, Windows Git Bash)
gtasks --version 2>/dev/null || gtasks.exe --version 2>/dev/null || echo "gtasks not found"
Or use which/where commands
macOS/Linux:
which gtasks
Windows (Command Prompt):
where gtasks
Windows (PowerShell):
Get-Command gtasks

If gtasks is not installed:

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 3. Verify installation: gtasks --version

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:

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

How to get credentials: 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 - http://localhost:9091/callback

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:

# Recommended: store in a file with restricted permissions
echo 'export GTASKS_CLIENT_ID="your-client-id"' >> ~/.gtasks_env
echo 'export GTASKS_CLIENT_SECRET="your-client-secret"' >> ~/.gtasks_env
chmod 600 ~/.gtasks_env
Source it from your shell profile
echo 'source ~/.gtasks_env' >> ~/.zshrc

2. Authentication

Once environment variables are set, authenticate with Google:

gtasks login

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.

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

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

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

4. Use appropriate output format: - Table format for human-readable output - JSON for parsing/integration with other tools - CSV for spreadsheet import

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

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.