Source: https://cli.nylas.com/guides/manage-google-calendar-cli

# Manage Google Calendar from the CLI

Google Calendar's external OAuth review can take up to six weeks for verified scopes, and most calendar scripts only need to list events, find a free slot, or create a single meeting. This guide covers those CRUD operations from the terminal without standing up a GCP project, paired with timezone and conferencing notes that trip up calendar automation specifically.

Written by [Aaron de Mello](https://cli.nylas.com/authors/aaron-de-mello) Senior Engineering Manager

Reviewed by [Nick Barraclough](https://cli.nylas.com/authors/nick-barraclough)

Updated May 2, 2026

## The Google Calendar API problem

You want to manage Google Calendar from the command line. The official route requires 6 steps before you touch a single event:

1. Create a GCP project in the [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the [Google Calendar API](https://developers.google.com/calendar/api/guides/overview)
3. Configure the OAuth consent screen (external apps go through Google's [brand verification review](https://support.google.com/cloud/answer/9110914), which can take up to six weeks for sensitive scopes)
4. Create OAuth 2.0 credentials, or a service account if you need domain-wide delegation
5. Set calendar scopes (`https://www.googleapis.com/auth/calendar` for read/write, or the narrower `calendar.events`)
6. Write code to exchange tokens and make API calls

For an internal app the GCP setup itself is fast. The expensive part is the OAuth review for any non-internal app, plus the per-user quota: the Calendar API is capped at [600 requests per minute per project](https://developers.google.com/calendar/api/guides/quota) by default, so heavy automation needs quota requests to Google. For someone who just wants to check their next meeting from the terminal, that is too much setup.

## 1. Install (skip if already set up)

Run `brew install nylas/nylas-cli/nylas` or see the [getting started guide](https://cli.nylas.com/guides/getting-started) for other methods.

## 2. Authenticate with Google

One command connects your Google Calendar account. Nylas handles the OAuth2 flow, token refresh, and scope management.

```bash
nylas auth login
```

This opens your browser, prompts Google sign-in, and stores credentials locally. The token auto-refreshes, so you won't re-authenticate unless you revoke access. Verify the connection:

```bash
nylas calendar list
```

You should see your Google calendars listed by name and ID.

## 3. Secondary calendars and ownership transfers

Google Calendar has a lifecycle problem most other providers do not. Personal calendars, secondary calendars, and Workspace resource calendars can all survive or disappear differently when an employee leaves. If your automation creates team calendars under one person's grant, you are taking on Google's ownership rules, not just event CRUD.

```bash
# List every calendar and flag non-primary ones
nylas calendar list --json | \
  jq -r '.[] | "\(.name) | primary=\(.is_primary) | id=\(.id)"'

# Pull events from a specific shared or secondary calendar
nylas calendar events list --calendar-id cal_team_launch --days 14
```

For Workspace-heavy teams, inventory and ownership are part of calendar operations. Review the [Google Calendar ownership changes guide](https://cli.nylas.com/guides/google-calendar-ownership-changes) if you offboard users or create shared calendars programmatically.

## 4. Workspace admin boundaries

Google developers often mix up three different models: user OAuth grants, service accounts, and domain-wide delegation. This guide is intentionally about user-level calendar work from the terminal. If a workflow needs to touch multiple employees' calendars, the blocker is usually admin policy and ownership, not command syntax.

That is the real Google-specific distinction in this cluster. Yahoo and iCloud are mostly personal-account problems. Google Workspace is often a tenant-policy and lifecycle problem.

## 5. Google Meet and event-type workflows

Google Calendar users care about Meet links, focus time, out of office events, and working-location metadata more than most other providers. Those fields affect how scheduling automation behaves, so inspect them directly instead of treating every event like a plain meeting row.

```bash
# Create a meeting and let Google attach conferencing details
nylas calendar events create \
  --title "Project Kickoff" \
  --start "2026-04-02 14:00" \
  --end "2026-04-02 15:00" \
  --participant alice@company.com \
  --participant bob@company.com

# Inspect Meet links and Google-specific metadata
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, meet: .conferencing, metadata: .metadata}'
```

## 6. Availability across Workspace and personal calendars

Google is also the provider where people most often mix personal Gmail calendars with Workspace calendars. The CLI can check both, but you still need to know which identity owns the meeting and which calendars are actually visible to that grant.

```bash
# Check your own free/busy slots
nylas calendar availability check

# Find a 30-minute slot across coworkers
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 30

# Constrain the search to a date range
nylas calendar availability find \
  --participants alice@company.com,bob@company.com \
  --duration 60 \
  --start "2026-04-01" \
  --end "2026-04-05"
```

## 7. Core Google Calendar commands

Once the ownership and tenant questions are settled, the basic event commands are straightforward:

```bash
# List upcoming events
nylas calendar events list --days 14 --show-tz

# Create an all-day event
nylas calendar events create \
  --title "Company Holiday" \
  --start "2026-04-10" \
  --all-day

# Reschedule an existing event
nylas calendar events update event_abc123 \
  --title "Sprint Planning (Moved)" \
  --start "2026-04-01 11:00" \
  --end "2026-04-01 12:00"

# Delete an event
nylas calendar events delete event_abc123
```

## 8. JSON output for scripting

Use `--json` when you need reporting, inventory, or filtering logic around shared calendars and Google-specific metadata.

```bash
# Get all upcoming events as JSON
nylas calendar events list --days 7 --json

# Extract event titles
nylas calendar events list --json | jq '.[].title'

# Count events per day this week
nylas calendar events list --days 7 --json | \
  jq 'group_by(.when.start_date) | map({date: .[0].when.start_date, count: length})'

# Pull free slots only
nylas calendar availability check --json | \
  jq '.time_slots[] | select(.status == "free")'
```

## Google Calendar API vs Nylas CLI

Here's what each approach requires to list your next 10 Google Calendar events:

| Task | Google Calendar API | Nylas CLI |
| --- | --- | --- |
| Initial setup | GCP project + OAuth consent screen + credentials (15-30 min) | `brew install nylas/nylas-cli/nylas` (30 sec) |
| Authentication | Write OAuth2 token exchange code, handle refresh tokens | `nylas auth login` |
| List events | Write Python/Node.js script with `calendar.events().list()` | `nylas calendar events list` |
| Check availability | `freebusy.query()` with time ranges and calendar IDs | `nylas calendar availability check` |
| Multi-provider support | Google only. Separate Microsoft Graph SDK for Outlook. | Google, Outlook, Exchange, Yahoo, iCloud, IMAP |
| Token management | Manual refresh token handling and storage | Automatic |
| Lines of code | 40-80 lines (Python) for basic CRUD | 0 lines. CLI commands only. |

## Google Calendar-specific tips

### Color labels

Google Calendar assigns numeric color IDs (1-11) to events. When you list events with `--json`, the `color_id` field maps to Google's color palette. Use this to filter events by category in scripts:

```bash
# List events with a specific color (e.g., "Tomato" = color_id 11)
nylas calendar events list --json | \
  jq '.[] | select(.metadata.color_id == "11") | .title'
```

### Recurring events

Google Calendar uses RRULE (RFC 5545) patterns for recurring events. When you create a recurring event through Nylas CLI, each occurrence appears as a separate event in the list output. The `master_event_id` field links occurrences back to the original:

```bash
# List events and filter for a recurring series
nylas calendar events list --json | \
  jq '.[] | select(.master_event_id == "event_abc123") | {title, start: .when.start_time}'
```

### Google Meet links

Events created with participants through a Google Calendar grant automatically include conferencing details. Check the `conferencing` field in JSON output:

```bash
# Find events with Google Meet links
nylas calendar events list --json | \
  jq '.[] | select(.conferencing != null) | {title, meet: .conferencing.details.url}'
```

### Working location and focus-time calendars

Google users also lean on event types such as focus time, out of office, and working location more than other providers. If your workflow depends on those distinctions, inspect the JSON output instead of assuming every event is a regular meeting. Google-specific metadata is exactly the kind of provider nuance that tends to get lost when teams build directly on generic calendar abstractions.

```bash
# Inspect Google-specific event metadata
nylas calendar events list --days 7 --json | \
  jq '.[] | {title: .title, status: .status, metadata: .metadata}'
```

## Next steps

- [Manage calendar events from the terminal](https://cli.nylas.com/guides/manage-calendar-from-terminal) -- DST-aware scheduling, timezone locking, and AI-powered meeting finder
- [List Gmail emails from the command line](https://cli.nylas.com/guides/list-gmail-emails) -- read and search your inbox without Google API setup
- [Send email from the terminal](https://cli.nylas.com/guides/send-email-from-terminal) -- compose and send emails from your CLI
- [Google Calendar ownership changes](https://cli.nylas.com/guides/google-calendar-ownership-changes) -- orphan calendars deleted April 27, new transfer API in June
- [Give AI agents email access via MCP](https://cli.nylas.com/guides/ai-agent-email-mcp) -- connect Claude or Cursor to your calendar and email
- [Full command reference](https://cli.nylas.com/docs/commands) -- every calendar flag and subcommand