Skip to main content
skill CX Codex

gccli — Claude Code skill for Google Calendar via CLI

gccli — a skill that teaches an AI agent to drive Google Calendar through a command-line tool. Use it when the agent needs to check availability or schedule events from chat.

MIT 177 installs ★ 2,663 updated 2026-06-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add badlogic/pi-skills --skill gccli -a claude-code
Open on GitHub

What gccli does

gccli plugs a Google Calendar CLI into your coding agent. The agent reads the skill instructions and can list calendars, create and update events, fetch event details, or check free/busy slots.

The CLI installs from npm: npm install -g @mariozechner/gccli. You also need a Google Cloud Console project with the Calendar API turned on and a Desktop app OAuth client. Accounts live in ~/.gccli/.

No OAuth setup means no working calendar. The console flow is separate from the skill install: create a project, enable the API, add test users, download the credentials file.

What it helps with

  • list calendars for a specific account
  • create an event with start and end times
  • check availability across several calendars
  • find a free slot with freebusy
  • get details of an event by ID

Example prompts for the agent

  • Show my calendars with gccli for [email protected]
  • Create a meeting in my primary calendar tomorrow from 14:00 to 15:00
  • Check if I am free on Friday between 10:00 and 12:00

How to install gccli

1Skills CLI (Vercel)

npx skills add badlogic/pi-skills --skill gccli -a claude-code

2Manually: put the files in place

~/.claude/skills/gccli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gccli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gccli

How do I install gccli in Claude Code?

Run npx skills add badlogic/pi-skills --skill gccli -a claude-code. The skill lands in ~/.claude/skills/gccli/SKILL.md.

What does gccli need to run?

Install the CLI first with npm install -g @mariozechner/gccli. Then set up OAuth in Google Cloud Console: enable the Calendar API, create a Desktop app client, and add test users.

How do I add a Google account?

Load the credentials with gccli accounts credentials ~/path/to/credentials.json, then run gccli accounts add <email>. Use --manual for browserless OAuth.

Source text

SKILL.md · MIT
---
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

© badlogic · MIT · badlogic/pi-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set8

More in the catalog

Project sponsors

Companies that keep this analytics open