playbooks

home / skills / badlogic / pi-skills / gccli

gccli skill

/gccli

This skill helps you manage Google Calendar via CLI by listing calendars, viewing and creating events, and checking availability from your terminal.

npx playbooks add skill badlogic/pi-skills --skill gccli

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: gccli
description: Google Calendar CLI for listing calendars, viewing/creating/updating events, and checking availability.
---

# Google Calendar CLI

Command-line interface for Google Calendar operations.

## Installation

```bash
npm install -g @mariozechner/gccli
```

## Setup

### Google Cloud Console (one-time)

1. [Create a new project](https://console.cloud.google.com/projectcreate) (or select existing)
2. [Enable the Google Calendar API](https://console.cloud.google.com/apis/api/calendar-json.googleapis.com)
3. [Set app name](https://console.cloud.google.com/auth/branding) in OAuth branding
4. [Add test users](https://console.cloud.google.com/auth/audience) (all Gmail addresses you want to use)
5. [Create OAuth client](https://console.cloud.google.com/auth/clients):
   - Click "Create Client"
   - Application type: "Desktop app"
   - Download the JSON file

### Configure gccli

First check if already configured:
```bash
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

Overview

This skill provides a command-line interface for Google Calendar, letting you list calendars, view and manage events, and check attendee availability. It is built for developers and power users who prefer terminal workflows and need quick calendar operations without opening a browser. Installation is via npm and it stores OAuth credentials locally for repeated use.

How this skill works

The CLI uses Google Calendar API credentials you supply from a Google Cloud project to perform authenticated operations on behalf of Gmail accounts. It exposes commands to list calendars, query events by time range, fetch event details, create or update events, and run free/busy queries across calendars. Credentials and account tokens are kept in a local ~/.gccli directory so subsequent commands are seamless.

When to use it

  • Quickly inspect upcoming events from the terminal or inside scripts
  • Create or update calendar events without opening a browser
  • Automate schedule checks and availability using free/busy queries
  • Integrate calendar operations into CI jobs, cron tasks, or developer tools
  • Manage multiple Gmail accounts or calendars from one CLI

Best practices

  • Create a dedicated Google Cloud project and OAuth client (Desktop app) for CLI access
  • Add only required test users and limit scopes to calendar operations
  • Store credentials securely and avoid committing ~/.gccli files to version control
  • Use ISO 8601 timestamps (YYYY-MM-DDTHH:MM:SSZ) for timed events and YYYY-MM-DD for all-day events
  • Test commands with a non-critical calendar before operating on primary calendars

Example use cases

  • List all calendars for an account: gccli <email> calendars
  • Show events within a date range: gccli <email> events primary --from 2026-02-01 --to 2026-02-07
  • Create a timed event: gccli <email> create primary --summary "Sprint Planning" --start 2026-02-02T15:00:00 --end 2026-02-02T16:00:00
  • Fetch details for a specific event: gccli <email> event primary <eventId>
  • Check availability across multiple calendars: gccli <email> freebusy primary,team@group --from 2026-02-01 --to 2026-02-02

FAQ

How do I set up the OAuth credentials?

Create a Google Cloud project, enable the Calendar API, create a Desktop OAuth client, download the JSON, then run gccli accounts credentials ~/path/to/credentials.json and gccli accounts add <email>.

Where are tokens and credentials stored?

OAuth client credentials are stored in ~/.gccli/credentials.json and account tokens in ~/.gccli/accounts.json by default.

What date/time formats are supported?

Use YYYY-MM-DDTHH:MM:SSZ for UTC timed events, YYYY-MM-DDTHH:MM:SS for local time, and YYYY-MM-DD with --all-day for all-day events.