Manage Google Calendar from the CLI

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
2. Enable the Google Calendar API
3. Configure the OAuth consent screen
4. Create OAuth 2.0 credentials (or a service account)
5. Set calendar scopes (https://www.googleapis.com/auth/calendar)
6. Write code to exchange tokens and make API calls

According to Google's own documentation, this process takes 15-30 minutes for experienced developers. For someone who just wants to check their next meeting from the terminal, that's too much setup.

1. Install (skip if already set up)

Run brew install nylas/nylas-cli/nylas or see the getting started guide for other methods.

2. Authenticate with Google

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

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:

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.

# 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 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.

# 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.

# 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:

# 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.

# 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:

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:

# 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:

# 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:

# 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.

# 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 -- DST-aware scheduling, timezone locking, and AI-powered meeting finder
• List Gmail emails from the command line -- read and search your inbox without Google API setup
• Send email from the terminal -- compose and send emails from your CLI
• Google Calendar ownership changes -- orphan calendars deleted April 27, new transfer API in June
• Give AI agents email access via MCP -- connect Claude or Cursor to your calendar and email
• Full command reference -- every calendar flag and subcommand