Google Calendar CLI: Manage Events from Terminal

How do you use a Google Calendar CLI from terminal?

Authenticate once, then use nylas calendar list, nylas calendar events list, nylas calendar events create, and nylas calendar availability find. This gives you a terminal Google Calendar workflow without creating OAuth credentials or writing Calendar API code.

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 (external apps go through Google's brand verification review, 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 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)

The Nylas CLI installs in under 30 seconds on macOS and Linux via Homebrew and supports 4 install methods total. The binary is around 25 MB and auto-detects your OS architecture during setup, so there is no manual configuration after install.

Run brew install nylas/nylas-cli/nylas or see the getting started guide for shell script, PowerShell, and Go install options.

2. Authenticate with Google

Authenticating with Google Calendar through the Nylas CLI takes a single command instead of the 6-step GCP project setup required by the raw Google Calendar API. The CLI opens a browser-based OAuth2 flow, exchanges the authorization code, and stores credentials locally. Token refresh happens automatically on every subsequent call.

The nylas auth login command requests the calendar and email scopes from Google. The entire flow completes in under 60 seconds, and the stored token persists across terminal sessions until you explicitly revoke access.

nylas auth login

After authentication, verify the connection by listing calendars. A successful response shows every calendar visible to the authenticated Google account, including shared and secondary calendars. Most Google Workspace users have 3-5 calendars visible by default.

nylas calendar list

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

3. Secondary calendars and ownership transfers

Google Calendar treats secondary calendars differently from primary ones during account lifecycle events. When an employee leaves a Google Workspace domain, their primary calendar is deleted after 20 days by default, but secondary calendars they created may become orphaned. According to Google Workspace admin documentation, admins must manually transfer calendar ownership before deleting the user account.

The Nylas CLI can list all calendars visible to a grant and flag which ones are primary vs. secondary. This is useful for auditing ownership before offboarding. A typical Workspace user with 2-3 shared calendars should run this inventory check quarterly.

# 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 cal_team_launch --days 14

For Workspace-heavy teams, inventory and ownership are part of calendar operations. The Google Calendar ownership changes guide covers offboarding workflows and programmatic shared calendar transfers.

4. Workspace admin boundaries

Google Workspace distinguishes three authentication models that developers frequently confuse: user OAuth grants (what the Nylas CLI uses), service accounts for server-to-server calls, and domain-wide delegation for admin-level access across all users. According to the Google Workspace auth overview, domain-wide delegation requires a Super Admin to authorize specific OAuth scopes per service account.

The Nylas CLI operates at user-level OAuth scope, which covers personal and shared calendars visible to the authenticated user. For workflows that need to read or write across 10+ employee calendars simultaneously, domain-wide delegation through a service account is the standard Google approach. Yahoo and iCloud calendar access is mostly a personal-account problem, while Google Workspace calendar management is a tenant-policy and lifecycle problem.

5. Google Meet and event-type workflows

Google Calendar automatically attaches Google Meet conferencing details to events created with at least one participant. Google Meet generates over 100 million meeting links daily according to Google's Workspace blog, so most calendar automation scripts need to handle the conferencing field. The Nylas CLI exposes these Meet details in JSON output alongside focus time, out of office, and working-location metadata.

Creating an event with participants through the Nylas CLI triggers Google's auto-conferencing. The CLI passes the participant list and time range, and Google Calendar adds the Meet link server-side. The resulting event object includes a conferencing.details.url field with the join link.

# 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

Checking availability on Google Calendar requires querying the FreeBusy API endpoint with calendar IDs, time ranges, and timezone offsets. The Nylas CLI wraps this into a single command that checks free/busy slots across all visible calendars. For teams where employees have both a personal Gmail and a Workspace account, availability checks need to account for both identities to avoid double-booking.

The nylas calendar availability check command returns free and busy time slots for the authenticated user. The nylas calendar availability find command takes 2 or more participant email addresses and finds mutual openings. Both commands accept --start and --end flags to constrain the search window.

# 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

The Nylas CLI provides 4 core event operations for Google Calendar: list, create, update, and delete. These commands map directly to the Google Calendar API's Events resource but skip the 40-80 lines of Python boilerplate that the raw API requires. Each command works the same way regardless of whether the target calendar is a primary, secondary, or shared Workspace calendar.

The nylas calendar events list command returns events for the next N days and supports --show-tz to display timezone information alongside each event. Creating an all-day event uses the --all-day flag with a date-only --start value. Updates require the event ID, which you can retrieve from the list command's output.

# 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

Every Nylas CLI calendar command supports the --json flag, which outputs structured JSON instead of the default table format. JSON output includes 15-20 fields per event depending on the provider, covering start/end times, participants, conferencing, recurrence rules, and provider-specific metadata. Piping JSON into jq enables filtering, grouping, and reporting without writing a full script.

The JSON structure follows the Nylas event schema, where time data lives under the when key and conferencing under the conferencing key. Google Calendar events include additional metadata fields like color_id and event_type that other providers don't expose. These examples show common patterns for extracting titles, counting events per day, and filtering free slots.

# 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

The Google Calendar API requires a GCP project, OAuth consent screen, and 40-80 lines of Python to list events. The Nylas CLI achieves the same result in a single command after a 30-second install. This comparison covers 7 dimensions, from initial setup time to lines of code required for basic calendar CRUD operations.

Google Calendar-specific tips

Google Calendar has several provider-specific features that don't exist in Outlook, Yahoo, or iCloud calendars. These include 11 numeric color labels, RRULE-based recurring event expansion, automatic Google Meet link generation, and event types like focus time and working location. Understanding these 4 areas helps avoid surprises when scripting against Google Calendar data through the Nylas CLI.

Color labels

Google Calendar assigns numeric color IDs from 1 through 11 to events, with each number mapping to a named color in Google's palette (for example, color ID 11 is "Tomato"). When listing events with --json, the color_id field appears in the metadata object. Filtering by color ID is useful for scripts that categorize events by project or priority.

# 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 stores recurring events using RRULE patterns defined in RFC 5545. A weekly standup, for example, is stored as a single master event with an RRULE like FREQ=WEEKLY;BYDAY=MO, and Google expands it into individual occurrences. When the Nylas CLI lists events, each occurrence appears as a separate event object. The master_event_id field links each occurrence back to the original master event, which is useful for bulk-editing an entire series.

# 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

Google Calendar automatically generates a Meet join link for events created with at least 1 participant through a Google Workspace or personal Gmail account. The conferencing data appears in the conferencing field of the JSON event object. Events without participants, such as all-day reminders or focus time blocks, don't receive Meet links. The following jq filter extracts only events that have conferencing attached.

# 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 Calendar introduced 3 special event types that other providers don't support: focus time, out of office, and working location. These event types affect availability differently than regular meetings. A focus time block, for instance, marks the user as busy but auto-declines new meeting invitations. An out of office event auto-declines and sends a custom message to the organizer. If your scheduling script treats all events as regular meetings, it will misinterpret these Google-specific types. Inspect the metadata and status fields in JSON output to distinguish them.

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

Next steps

This guide covered Google Calendar event CRUD, availability checks, and provider-specific features like Meet links and focus time blocks. The Nylas CLI supports 6 calendar providers with the same command syntax, so most of these patterns transfer directly to Outlook, Yahoo, and iCloud calendars.

• Manage calendar events from the terminal -- DST-aware scheduling, timezone locking, and AI-powered meeting finder
• Email CLI tools compared -- compare terminal email tools that also need calendar access
• AI agent CLI for email and calendar -- expose calendar commands as JSON tools for LLM agents
• 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
• Google Calendar API pagination and sync -- nextPageToken, syncToken, 410 Gone recovery, and recurring event expansion
• Give AI agents email access via MCP -- connect Claude or Cursor to your calendar and email
• Sync calendars across providers -- ICS, CalDAV, and API-based calendar sync compared
• Best CLI calendar tools compared -- gcalcli, khal, calcurse, remind, and Nylas CLI
• Full command reference -- every calendar flag and subcommand