gcalcli
View and manage Google Calendar from command line
TLDR
List your events for all your calendars over the next 7 days
Show events starting from or between specific dates (also takes relative dates e.g. "tomorrow")
List events from a specific calendar
Display an ASCII calendar of events by week
Display an ASCII calendar of events for a month
Quick-add an event to your calendar
Add an event to calendar. Triggers interactive prompt
SYNOPSIS
gcalcli [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS] [ARGUMENTS]
Common Commands:
gcalcli agenda [--days N] [--details]
gcalcli calw [--weekstart day]
gcalcli calm [--calendar cal]
gcalcli add "Event Title" [--when "date time"] [--duration N] [--where "location"]
gcalcli quickadd "Event description..."
gcalcli delete "Event Title" [--interactive]
gcalcli edit "Event Title" [--new_title "New Title"]
gcalcli search "keyword"
gcalcli sync sync_directory [--calendar cal]
gcalcli remind [--earlier N] [--calendar cal]
PARAMETERS
--calendar CALENDAR
Specify the calendar to use by ID or alias. Default is 'default'.
--default-calendar CALENDAR
Override the default calendar specified in the config file.
--config FILE
Specify an alternative configuration file path.
--noauth_local_webserver
Disable the local webserver for OAuth2 authentication. Useful for SSH.
--tsv
Output in Tab Separated Values format for scripting.
--client-id ID
OAuth2 client ID. Overrides the config file setting.
--client-secret SECRET
OAuth2 client secret. Overrides the config file setting.
--version
Show program's version number and exit.
--help
Show help message and exit.
agenda --days N
Show events for the next N days. Default is 7.
agenda --details
Display more event details in the agenda view.
calw --weekstart DAY
Set the day the week starts (e.g., 'Sunday', 'Monday').
add --title TITLE
Set the title of the new event.
add --when DATE_TIME
Specify the start date and time for the event.
add --duration MINUTES
Set the duration of the event in minutes (e.g., '60', '1h 30m').
add --where LOCATION
Specify the location of the event.
add --description TEXT
Add a detailed description to the event.
delete --interactive
Prompt for confirmation before deleting each matching event.
edit --new_title TITLE
Specify a new title when editing an event.
remind --earlier MINUTES
Check for events starting within the next N minutes.
DESCRIPTION
gcalcli is a powerful command-line interface for Google Calendar, enabling users to interact with their calendar events directly from the terminal. It provides functionalities to view agendas, browse monthly or weekly calendars, add new events, delete existing ones, edit event details, and search for specific entries. Designed for efficiency and automation, gcalcli is an invaluable tool for users who prefer a text-based workflow or need to script calendar operations. It supports multiple calendars, color-coding, and integrates seamlessly with other command-line utilities. Its initial setup involves an OAuth2 authentication process to connect with your Google account, after which you can effortlessly manage your schedule without leaving the terminal.
CAVEATS
Setting up gcalcli requires initial OAuth2 authentication with Google, which can be challenging in environments without a web browser (e.g., SSH sessions). The command relies on the Google Calendar API, and users might encounter API rate limits with excessive use. It primarily manages events; advanced calendar settings or shared calendar permissions are typically handled through the Google Calendar web interface.
AUTHENTICATION
The first time you run gcalcli, it will prompt you to authenticate with your Google account via an OAuth2 flow. This typically involves opening a browser window to grant permissions. If you are in a headless environment, use the --noauth_local_webserver option, which will provide a URL to open manually and paste a verification code back into the terminal.
CONFIGURATION FILE
gcalcli uses a configuration file, typically located at ~/.gcalcli_oauth.py or ~/.gcalcli_oauth.json (depending on version/setup). This file stores your API credentials, default calendar settings, calendar aliases, color preferences, and other customizations. It can be manually edited to fine-tune its behavior.
QUICK ADD FEATURE
The quickadd command allows you to add events using natural language, similar to Google Calendar's web interface. For example: gcalcli quickadd 'Lunch with John tomorrow at 1 PM at The Cafe'. This intelligently parses the event details from your descriptive text.
HISTORY
gcalcli emerged as an open-source project to bridge the gap between Google Calendar's web interface and the power of the command line. It has been actively developed by a community of contributors, focusing on providing a robust and flexible tool for system administrators, developers, and power users who need to automate or quickly access their calendar information without graphical overhead. Its development has consistently adapted to changes in the Google Calendar API and user needs for CLI-based productivity, making it a staple for text-based scheduling.