explaingit

insanum/gcalcli

★ 3,721PythonAudience · developerComplexity · 2/5Setup · moderate

TLDR

gcalcli is a Python command-line app for managing Google Calendar from the terminal, supporting event viewing, creation, deletion, ICS import, and cron-based reminders.

Mindmap

mindmap
  root((repo))
    What it does
      View calendar agenda
      Add delete events
      ICS file import
      Cron reminders
    Tech stack
      Python
      Google Calendar API
      OAuth2
    Use cases
      Terminal scheduling
      Calendar automation
      Email client integration
    Audience
      CLI power users
      Developer workflows
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Check your daily agenda from the terminal without opening a browser

USE CASE 2

Add Google Calendar events from a cron job or shell script

USE CASE 3

Import ICS meeting invites from a terminal email client into Google Calendar

USE CASE 4

Set up cron-based event reminders that trigger a custom script or notification

Tech stack

PythonGoogle Calendar APIOAuth2

Getting it running

Difficulty · moderate Time to first run · 30min

Requires a Google Cloud project with the Calendar API enabled and OAuth2 credentials configured before first use.

In plain English

gcalcli is a Python command-line tool for accessing and managing Google Calendar from the terminal. If you prefer working in a shell rather than opening a browser, gcalcli lets you view your schedule, add events, delete events, edit events, and search across your calendars without leaving the command line. The tool connects to your Google Calendar through the official Google Calendar API, using OAuth2 to authenticate with your Google account. Once set up, it can display an agenda for a date range, show a visual ASCII calendar for the month, search for past and future events, and flag scheduling conflicts between events. You can add events quickly with a short text string or interactively by filling in details step by step. gcalcli also handles calendar imports, reading ICS and vCal files (the format used by Microsoft Exchange and many other calendar applications) and importing them into a Google Calendar. This makes it useful as an attachment handler in terminal-based email clients. The tool works on Linux and macOS, with packages available in several Linux distributions including Debian, Ubuntu, and Void Linux, plus Homebrew for macOS. You can also install it from PyPI using pip. For more advanced use cases, gcalcli supports running as a cron job to fire reminders, working with a specific subset of calendars by name or regex, outputting colored text, and generating shell completion scripts for bash, zsh, and fish. Anyone who lives in the terminal and uses Google Calendar will find gcalcli a practical replacement for opening a browser tab every time they need to check their schedule.

Copy-paste prompts

Prompt 1
How do I set up gcalcli with OAuth2 to connect to my Google Calendar from the command line?
Prompt 2
Show me the gcalcli commands to view today's agenda, search for events, and add a new event
Prompt 3
How do I import an ICS file from a Microsoft Exchange invite into Google Calendar using gcalcli?
Prompt 4
Set up gcalcli as a cron job to check for upcoming events and run a reminder script 10 minutes before each one
Open on GitHub → Explain another repo

← insanum on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.