gcalcli

List your events for all your calendars over the next 7 days

$ gcalcli agenda

$ gcalcli agenda [mm/dd] [[mm/dd]]

$ gcalcli --calendar [calendar_name] agenda

$ gcalcli calw

$ gcalcli calm

$ gcalcli --calendar [calendar_name] quick "[mm/dd] [HH:MM] [event_name]"

$ gcalcli --calendar "[calendar_name]" add

gcalcli [global-options] <COMMAND> [<args>]
where COMMAND is one of: agenda, add, caladd, delete, edit, export, import, list, listcal, listnext, reminders, search

-h, --help
    Show help message and exit

--calendar CALENDAR, -c CALENDAR
    Calendar name or ID to use

--calid CALID
    Calendar ID (overrides --calendar)

--clientid CLIENTID
    Override OAuth client ID

--clientsecret CLIENTSECRET
    Override OAuth client secret

--tokenfile TOKENFILE
    Path to OAuth token file (default: ~/.gcalcli_oauth)

--noclientversion
    Don't send client version info

--nocolors
    Disable colorized output

--tsv
    Tab-separated values output

--military
    Use 24-hour time format

--nodefaults
    Disable default search values

--search SEARCH, -s SEARCH
    Google-style search string

--query QUERY, -q QUERY
    Query string with Google operators

--when WHEN, -w WHEN
    Relative date (e.g., today, next week)

--where WHERE
    Location to search

--duration DURATION, -d DURATION
    Event duration (e.g., 30m, 2h, 1day)

--who WHO
    Attendees to search/add

--description DESCRIPTION
    Event notes/description

--location LOCATION
    Event location

--reminder REMINDER, -r REMINDER
    Reminder override (e.g., 10m, never)

--allday
    All-day event (excludes --duration)

--exclude-deleted
    Exclude deleted events from results

--start START
    Absolute start time/date

--end END
    Absolute end time/date

--details
    Show full event details

--squeeze
    Squeeze repeat events to one line

--conky
    Conky-compatible output format

--week WEEK
    Week number (1-53)

--month MONTH
    Month number (1-12)

--year YEAR
    4-digit year

--firstday FIRSTDAY
    First day of week (0=Sun, 6=Sat)

--locale LOCALE
    Locale for dates (e.g., en_US)

--input INPUT
    File with event data

--action ACTION
    For edit/delete: 0=ask, 1=yes, 2=no

--recursive
    Recursive import

--xdg
    Use XDG config dir (~/.config/gcalcli)

--debug
    Enable debug logging

gcalcli is an open-source Python tool for managing Google Calendar events directly from the Linux terminal. It provides comprehensive read/write access via the Google Calendar API v3, supporting operations like viewing agendas, listing events, adding, editing, deleting, and searching calendars without a graphical interface.

Key features include OAuth2 authentication with local token storage, customizable searches using Google query syntax, reminder management, ICS import/export, and output formats for TSV, conky, or colorized views. Users can specify calendars by name or ID, set event details like duration, location, attendees, and recurring patterns. It's script-friendly for automation, such as cron jobs for reminders or desktop widgets.

Installation via pip ensures easy setup, though initial authentication requires a browser. Ideal for server environments, power users, or those preferring CLI efficiency. Supports military time, locale-specific dates, and excludes deleted events. While powerful, it requires internet and a Google account; not all advanced sharing or tasks features are fully replicated.

Requires Python 3, internet access, and Google account. Initial OAuth needs browser. Limited to API v3 features; no real-time collab editing. Token refresh may fail if Google changes auth.

pip install gcalcli
pip install --upgrade gcalcli
Or from source: git clone https://github.com/insanitybit/gcalcli

First run opens browser for OAuth consent. Tokens saved to ~/.gcalcli_oauth. Use --tokenfile or --xdg for custom paths.
Client ID/secret from Google API Console.

~/.gcalcli (or ~/.config/gcalcli/gcalcli with --xdg). Sets defaults like calendar, clientid.

Developed by Bret Fisher starting 2010 as gcalcli on Google Code. Migrated to GitHub, updated for Calendar API v3 in 2014. Maintained by volkerd (insanitybit) since 2016, with ongoing Python 3 support and bug fixes via PyPI.

cal(1), date(1), khal(1), vcal(1)