gccli

badlogic's avatarfrom badlogic

Google Calendar CLI for listing calendars, viewing/creating/updating events, and checking availability.

⭐72stars🔀6forks📁View on GitHub🕐Updated Dec 23, 2025
[Meeting Productivity]

When & Why to Use This Skill

The Google Calendar CLI (gccli) provides a powerful interface for managing schedules and events directly through command-line operations or AI agents. It solves the inefficiency of manual calendar management by enabling programmatic access to list calendars, create or update events, and perform 'freebusy' availability checks, making it an essential tool for automated scheduling and streamlined time management.

Use Cases

  • Automated Event Coordination: Programmatically schedule meetings and deadlines based on project triggers or AI-driven task management.
  • Rapid Availability Checking: Use the 'freebusy' command to instantly identify open time slots across multiple calendars without navigating a web interface.
  • Headless Calendar Administration: Manage professional schedules in terminal-heavy environments or integrate calendar actions into automated CI/CD and DevOps workflows.
  • Bulk Event Updates: Efficiently list and modify multiple calendar entries using CLI filters, saving time compared to manual GUI edits.
namegccli
descriptionGoogle Calendar CLI for listing calendars, viewing/creating/updating events, and checking availability.

Google Calendar CLI

Command-line interface for Google Calendar operations.

Installation

npm install -g @mariozechner/gccli

Setup

Google Cloud Console (one-time)

  1. Create a new project (or select existing)
  2. Enable the Google Calendar API
  3. Set app name in OAuth branding
  4. Add test users (all Gmail addresses you want to use)
  5. Create OAuth client:
    • Click "Create Client"
    • Application type: "Desktop app"
    • Download the JSON file

Configure gccli

First check if already configured:

gccli accounts list

If no accounts, guide the user through setup:

  1. Ask if they have a Google Cloud project with Calendar API enabled
  2. If not, walk them through the Google Cloud Console steps above
  3. Have them download the OAuth credentials JSON
  4. Run: gccli accounts credentials ~/path/to/credentials.json
  5. Run: gccli accounts add <email> (use --manual for browserless OAuth)

Usage

Run gccli --help for full command reference.

Common operations:

  • gccli <email> calendars - List all calendars
  • gccli <email> events <calendarId> [--from <dt>] [--to <dt>] - List events
  • gccli <email> event <calendarId> <eventId> - Get event details
  • gccli <email> create <calendarId> --summary <s> --start <dt> --end <dt> - Create event
  • gccli <email> freebusy <calendarIds> --from <dt> --to <dt> - Check availability

Use primary as calendarId for the main calendar.

Date/Time Format

  • Timed events: YYYY-MM-DDTHH:MM:SSZ (UTC) or YYYY-MM-DDTHH:MM:SS (local)
  • All-day events: YYYY-MM-DD with --all-day flag

Data Storage

  • ~/.gccli/credentials.json - OAuth client credentials
  • ~/.gccli/accounts.json - Account tokens