Google Calendar and Google Tasks CLI tools. Two binaries (gcal, gtask) shipped together — they share OAuth credentials, scopes, and token files, so you authenticate once.

Installation

npm install -g @bobfrankston/gcal

Provides:

gcal — Google Calendar
gtask — Google Tasks

Both share OAuth client credentials with gcards (%APPDATA%\gcards\credentials.json).

gcal — Google Calendar

gcal <file.ics>            # Import ICS file (file association)
gcal <command> [options]
gcal help <command>        # Detailed help for one command

Commands

Command	Description
`list [n]`	List upcoming n events (default: 10)
`show <id>`	Show full details for an event (`-json` for raw JSON)
`add <title> <when> [duration]`	Add event (explicit)
`add "<free text>"`	Add event (AI-parsed)
`add -clip`	Add event from clipboard (AI-parsed)
`add`	Add event interactively
`del \| delete <id> [id2...]`	Delete event(s) by ID prefix
`remind <id> <dur> [dur2...]`	Add reminder(s)
`resched <id> <when> [duration]`	Reschedule (preserves duration)
`snooze <id> [when]`	Snooze (default `+1d`)
`import <file.ics>`	Import events from ICS
`calendars`	List available calendars
`assoc`	Set up `.ics` file association (Windows)
`help [command]`	Show help

Options

Flag	Description
`-u`, `-user <email>`	Set / use default Google account
`-c`, `-calendar <id>`	Calendar ID (default: primary)
`-n <count>`	Number of events to list
`-v`, `-verbose`	Show event IDs and links
`-b`, `-birthdays`	Include birthday events
`-clip`	Read from clipboard (for `add`)
`-r`, `-reminder <dur>`	Add popup reminder (e.g. `30m`, `1h`); repeatable
`-since <date>`	Start listing from `<date>`
`-till <date>`	End listing at `<date>`
`-all`	Delete all instances of recurring event
`-json`	Output raw JSON (for `show`)

Examples

gcal meeting.ics
gcal list
gcal list -since "10 days ago"
gcal list -since "april 1" -till "may 1"
gcal add "Dentist" "Friday 3pm" "1h"
gcal add "Lunch" "1/14/2026 12:00" "1h"
gcal add "Dentist appointment Friday 3pm for 1 hour"
gcal add -clip
gcal add "Dentist" "Friday 3pm" -r 30m
gcal show abc12345
gcal show abc12345 -json
gcal remind abc12345 30m
gcal resched abc12345 "next friday 3pm"
gcal snooze abc12345 +1w
gcal -u bob@gmail.com

Conflict / proximity warnings

When adding or rescheduling a timed event, gcal prints a warning for any existing event that overlaps the new slot or falls within 1 hour before or after it. In AI-mode add, warnings appear before the confirmation prompt so you can cancel. Warnings are informational only — the event is still created.

Reschedule / snooze notes

resched and snooze find events up to 30 days in the past by default (so stale reminders remain findable). Widen with -since <date>. For timed events, if <when> lacks a time-of-day (e.g. tomorrow), the original time is preserved. All-day events stay all-day. Relative offsets +1d / +1w / +1h / +1m advance from the event's current start.

Windows file association

gcal assoc        # Sets up .ics → gcal

On first run, gcal offers to set this up. Run gcal assoc anytime to (re)configure.

gtask — Google Tasks

gtask <command> [options]
gtask help <command>

Commands

Command	Description
`add <title> [when]`	Add a task (optional due date — date-only)
`list`	List open tasks
`lists`	List all tasklists
`done <id>`	Mark task completed
`undone <id>`	Reopen a completed task
`del <id>`	Delete a task
`edit <id> [-t title] [-when date] [-n notes]`	Update fields
`clear`	Remove all completed tasks from list
`move <id> -l <list>`	Move task to another tasklist
`help [command]`	Show help

Options

Flag	Description
`-u`, `-user <email>`	Google account
`-l`, `-list <name\|id>`	Tasklist (default: primary)
`-n`, `-notes <text>`	Notes for `add` / `edit`
`-t`, `-title <text>`	New title for `edit`
`-when <date>`	New due date for `edit`
`-a`, `-all`	Include completed tasks in `list`

Examples

gtask add "Write report"
gtask add "Write report" friday
gtask add "Pay bills" "april 30" -n "rent + utilities"
gtask add "Call plumber" tomorrow -l Errands
gtask list
gtask list -l Errands
gtask list -a
gtask done abc12345
gtask edit abc12345 -when "next monday"
gtask move abc12345 -l Personal
gtask clear -l Errands

Notes on Google Tasks

Due dates are date-only. The Tasks API stores RFC3339 timestamps, but the Google UI ignores time-of-day. gtask writes midnight UTC.
No reminders. Tasks have no notification mechanism in the API. Reminders only appear if you create the task through the Calendar UI's task-with-time feature.
No recurrence. Recurring tasks aren't exposed via the API.
Hierarchy is flat. One level of subtasks via move?parent=. Not currently surfaced by gtask.

Shared OAuth

Both tools request the combined scope set calendar + tasks (read or write depending on operation). The first time you run either tool after upgrading, Google prompts once for the new combined consent; afterward both share token.json / token-write.json.