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> [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]

--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.

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.

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.

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.

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.

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.

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.

cal(1), date(1), remind(1)