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

$ gcalcli agenda

Show events starting from or between specific dates (also takes relative dates e.g. "tomorrow")
$ gcalcli agenda [mm/dd] [[mm/dd]]

List events from a specific calendar
$ gcalcli --calendar [calendar_name] agenda

Display an ASCII calendar of events by week
$ gcalcli calw

Display an ASCII calendar of events for a month
$ gcalcli calm

Quick-add an event to your calendar
$ gcalcli --calendar [calendar_name] quick "[mm/dd] [HH:MM] [event_name]"

Add an event to calendar. Triggers interactive prompt
$ gcalcli --calendar "[calendar_name]" add


gcalcli [options] command [command args or options]


gcalcli is a Python application that allows you to access your Google Calendar(s) from a command line. It's easy to get your agenda, search for events, add new events, delete events, edit events, and even import those annoying ICS/vCal invites from Microsoft Exchange and/or other sources. Additionally, gcalcli can be used as a reminder service and execute any application you want when an event is coming up.


gcalcli [-h] [--auth_host_name AUTH_HOST_NAME] [--noauth_local_webserver] [--auth_host_port [AUTH_HOST_PORT [AUTH_HOST_PORT ...]]] [--logging_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--version] [--default-calendar DEFAULT_CALENDAR] [--calendar CALENDAR] [--refresh] [--client-id CLIENT_ID] [--conky] [--nocache] [--locale LOCALE] [--noincluderc] [--lineart {fancy,unicode,ascii}] [--config-folder CONFIG_FOLDER] [--nocolor] [--client-secret CLIENT_SECRET] {list,search,edit,delete,agenda,calw,calm,quick,add,import,remind} ...

Positional arguments: {list,search,edit,delete,agenda,updates,conflicts,calw,calm,quick,add,import,remind} Invoking a subcommand with --help prints subcommand usage. list list available calendars edit edit calendar events agenda get an agenda for a time period updates get updates since a datetime for a time period conflicts find conflicts between events matching search term calw get a week-based agenda in calendar format calm get a month agenda in calendar format quick quick-add an event to a calendar add add a detailed event to the calendar import import an ics/vcal file to a calendar remind execute command if event occurs within <mins> time

Optional arguments: -h, --help show this help message and exit --auth_host_name AUTH_HOST_NAME Hostname when running a local web server. (default: localhost) --noauth_local_webserver Do not run a local web server. (default: False) --auth_host_port [AUTH_HOST_PORT [AUTH_HOST_PORT ...]] Port web server should listen on. (default: [8080, 8090]) --logging_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} Set the logging level of detail. (default: ERROR) --version show program's version number and exit --default-calendar DEFAULT_CALENDAR Optional default calendar to use if no --calendar options are given (default: []) --calendar CALENDAR Which calendars to use (default: []) --refresh Delete and refresh cached data (default: False) --client-id CLIENT_ID API client_id (default: --conky Use Conky color codes (default: False) --nocache Execute command without using cache (default: True) --locale LOCALE System locale (default: ) --noincluderc Whether to include ~/.gcalclirc when using configFolder (default: True) --lineart {fancy,unicode,ascii} Choose line art style for calendars: "fancy": for VTcodes, "unicode" for Unicode box drawing characters, "ascii" for old-school plusses, hyphens and pipes. (default: fancy) --config-folder CONFIG_FOLDER Optional directory to load/store all configuration information (default: None) --nocolor Enable/Disable all color output (default: True) --client-secret CLIENT_SECRET API client_secret (default: 3tZSxItw6_VnZMezQwC8lUqy)


"Encoding issues, wrongly printed characters, UnicodeEncodeError when using conky, in pipes or scripts"

- Set an environment variable PYTHONIOENCODING=utf8 - Use a Unicode capable font like DejaVu Sans Mono - Set option --lineart=unicode or --lineart=ascii - Upgrade to Python3

No colors or garbage characters when using inside conky

- Set option --conky


Report issues at


Eric Davis (

Brian Hartvigsen (

Joshua Crowgey (



Copied to clipboard