Guide

Manage Calendar Events from Terminal

Most calendar integrations stop at CRUD. The Nylas CLI goes further with DST-aware event creation, configurable working hours and break protection, timezone locking for travel, and AI-powered natural language scheduling. Works with Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP.

Written by Prem Keshari Senior SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.1 · Google Calendar, Outlook Calendar · last tested April 11, 2026

Why manage your calendar from the terminal?

Managing calendar events from the terminal eliminates the context switch between your editor and a browser tab. According to a 2023 study by Qatalog and Cornell, context switching costs knowledge workers an average of 9.5 minutes per interruption -- and checking a calendar in a browser is one of the most common interruptions during coding sessions. A CLI-based calendar keeps you in the terminal for the full workflow.

  • Check your next meeting without leaving your editor
  • Script recurring event creation for standup meetings or 1:1s
  • Integrate calendar checks into CI/CD or deployment scripts
  • Pipe availability data into scheduling bots or agents
  • Create events across timezones without mental math

1. Quick setup

Setting up the Nylas CLI for calendar management takes under 2 minutes. Install via Homebrew, authenticate with your calendar provider through OAuth, and verify the connection by listing your calendars. The CLI supports Google Calendar, Outlook, Exchange, Yahoo, iCloud, and IMAP -- all through one interface.

Homebrew is the fastest install method on macOS and Linux. The formula pulls the latest release binary and adds it to your PATH automatically.

brew install nylas/nylas-cli/nylas

Alternative install methods (shell script, PowerShell, Go) are in the getting started guide. After installing, authenticate and confirm your calendars are accessible.

nylas auth login
nylas calendar list  # verify

2. List upcoming events

The nylas calendar events list command displays upcoming events from all connected calendars -- primary, shared, and subscribed. By default it shows the next 7 days. The --timezone flag converts all displayed times to a specific IANA zone, and --show-tz appends the timezone abbreviation to each time. These two flags work together for distributed teams spanning 5 or more timezones.

The command queries the provider's API and returns events sorted chronologically. Use --days to extend the look-ahead window up to 90 days, and --json for structured output you can pipe into jq or other tools.

# Next 7 days (default)
nylas calendar events list

# Next 14 days
nylas calendar events list --days 14

# With timezone info shown
nylas calendar events list --show-tz

# Convert all times to a different timezone
nylas calendar events list --timezone America/Los_Angeles

# Combine both
nylas calendar events list --timezone Europe/London --show-tz

Example output

Each event displays its title, date/time range, location (if set), guest count, and internal event ID. The event ID is what you pass to nylas calendar events update or nylas calendar events delete when modifying events later.

$ nylas calendar events list --days 7

Team Standup
  When: Mon, Feb 16, 2026, 9:00 AM - 9:30 AM
  Location: Conference Room A
  Guests: 5 participant(s)
  ID: event_abc123

Project Review
  When: Tue, Feb 17, 2026, 2:00 PM - 3:00 PM
  Guests: 3 participant(s)
  ID: event_def456

Found 4 event(s)

3. Create events

The nylas calendar events create command adds events to your connected calendar with 3 required flags: --title, --start, and --end. For all-day events, pass date-only values (YYYY-MM-DD) with --end set to the following day. The command supports up to 100 participants per event through the --participants flag, and Google Calendar automatically sends invite notifications to all attendees.

Start and end times accept ISO 8601 format. The --participants flag takes a comma-separated list of email addresses. Add --location for a physical or virtual meeting location, and --description for an event body or agenda.

# Basic event
nylas calendar events create \
  --title "Sprint Planning" \
  --start "2026-02-20T10:00:00Z" \
  --end "2026-02-20T11:00:00Z"

# All-day event (use date-only format, --end is the day after)
nylas calendar events create \
  --title "Team Offsite" \
  --start "2026-03-01" \
  --end "2026-03-02"

# With participants
nylas calendar events create \
  --title "Design Review" \
  --start "2026-02-21T14:00:00Z" \
  --end "2026-02-21T15:00:00Z" \
  --participants alice@company.com,bob@company.com

4. DST-aware scheduling

Daylight Saving Time affects roughly 1.6 billion people across 70+ countries, and scheduling a meeting during a DST gap creates invalid calendar entries. The Nylas CLI detects DST transitions before event creation and warns when a requested time won't exist (spring forward) or occurs twice (fall back). This prevents the silent failures that plague calendar APIs when they silently shift or drop events during DST boundaries.

As defined in RFC 5545 (the iCalendar standard), recurring events that land on a nonexistent local time should be handled by the calendar client. The CLI catches this at creation time. Here's what happens when you try to schedule during a spring-forward gap.

$ nylas calendar events create --title "Early Sync" --start "2026-03-08T02:30:00"

DST Conflict Detected!

This time will not exist due to Daylight Saving Time (clocks spring forward)

Suggested alternatives:
  1. Schedule 1 hour earlier (before DST)
  2. Schedule at the requested time after DST
  3. Use a different date

Create anyway? [y/N]: n
Cancelled.

The CLI also warns about fall-back duplicates, where 1:00-2:00 AM occurs twice in a single night.

5. Working hours validation

The Nylas CLI validates proposed event times against configurable working hours defined in ~/.config/nylas/config.yaml. When you create an event outside your defined window, the CLI shows the exact overlap -- how many hours before or after your working day the event falls. A 2022 Reclaim.ai study found that 45% of meetings are scheduled outside preferred working hours, making this guardrail useful for protecting work-life boundaries from the terminal.

Working hours support per-day overrides, so you can set shorter hours on Fridays or disable weekends entirely. The warning is advisory -- you can confirm and create the event anyway.

# ~/.config/nylas/config.yaml
working_hours:
  default:
    enabled: true
    start: "09:00"
    end: "17:00"
  friday:
    enabled: true
    start: "09:00"
    end: "15:00"   # Short Fridays
  weekend:
    enabled: false  # No weekend meetings

When you attempt to create an event outside these configured hours, the CLI displays the exact delta. This example shows an event 1 hour past the 17:00 cutoff.

$ nylas calendar events create --title "Late Call" --start "2026-02-18 18:00"

Working Hours Warning

This event is scheduled outside your working hours:
  Your hours: 09:00 - 17:00
  Event time: 6:00 PM
  1 hour(s) after end

Create anyway? [y/N]:

6. Break time protection

Break time protection is a hard enforcement mechanism in the Nylas CLI -- unlike working hours warnings, which you can override, break blocks reject event creation entirely. This prevents accidental scheduling over lunch, coffee breaks, or focus time. According to Microsoft's 2022 Work Trend Index, back-to-back meetings without breaks increase stress markers by 2x, making enforced breaks a practical default for heavy meeting days.

Break blocks are defined inside each day's working hours configuration. Each break has a name, start/end time, and type. The CLI returns an error (not a warning) when an event overlaps a break.

# In config.yaml
working_hours:
  default:
    enabled: true
    start: "09:00"
    end: "17:00"
    breaks:
      - name: "Lunch"
        start: "12:00"
        end: "13:00"
        type: "lunch"
      - name: "Afternoon Coffee"
        start: "15:00"
        end: "15:15"
        type: "coffee"

When an event overlaps a break block, the CLI rejects the creation with an error -- no confirmation prompt, no override. This example shows a 12:30 PM event blocked by the noon lunch break.

$ nylas calendar events create --title "Quick Sync" --start "2026-02-18 12:30"

Break Time Conflict

Event cannot be scheduled during Lunch (12:00 - 13:00)
Error: event conflicts with break time

7. Timezone-aware event creation

The Nylas CLI handles timezone-aware event creation through ISO 8601 timestamps with explicit timezone offsets. When you create an event for an in-person meeting in a specific city, passing the timezone offset ensures the time displays correctly regardless of the viewer's location. The IANA Time Zone Database tracks 594 timezone identifiers, and the CLI resolves all of them through its offline timezone engine.

Use the --timezone flag on nylas calendar events list to convert displayed times to any zone. For event creation, specify the offset directly in the --start and --end values. The nylas timezone convert command helps calculate the right offset before creating the event.

# Create event with explicit timezone offset
nylas calendar events create \
  --title "NYC Office All-Hands" \
  --start "2026-02-20T09:00:00-05:00" \
  --end "2026-02-20T10:00:00-05:00" \
  --location "New York Office"

# View events in a different timezone
nylas calendar events list --timezone America/Los_Angeles --show-tz

# Convert time between zones before scheduling
nylas timezone convert --from EST --to PST --time "2026-02-20T09:00:00Z"

8. AI-powered natural language scheduling

The nylas calendar schedule ai command parses natural language descriptions -- participants, duration, time preferences -- and creates calendar events from a single sentence. It checks availability across all participants, handles DST transitions, and proposes ranked time slots scored out of 100. The AI backend is configured via nylas ai config, which supports Ollama (local, no data leaves your machine), OpenAI, and Anthropic.

Pass the meeting description as a quoted string. The command extracts participant emails, duration, and preferred time window, then queries each participant's free/busy data before suggesting slots. Use --yes to auto-confirm the top suggestion in scripts.

# Natural language scheduling
nylas calendar schedule ai "30-minute meeting with john@example.com next Tuesday afternoon"

# Auto-confirm the first suggestion (useful in scripts)
nylas calendar schedule ai --yes "lunch with Alice next Monday"

Example output

The AI scheduler ranks up to 3 time slots by a score out of 100, factoring in working hours, existing calendar density, and timezone overlap between participants. Higher scores indicate fewer conflicts and better alignment with each participant's preferred hours.

$ nylas calendar schedule ai "30-min sync with john@example.com next Tuesday"

AI Scheduling Assistant
Provider: Ollama (local)

Top 3 suggested times:

1. Tuesday, Feb 17, 2:00 PM PST (Score: 94/100)
   you@example.com:  2:00 PM - 2:30 PM PST
   john@example.com: 5:00 PM - 5:30 PM EST
   Both in working hours, no conflicts

2. Tuesday, Feb 17, 1:00 PM PST (Score: 82/100)
   Post-lunch slot, moderate energy

3. Tuesday, Feb 17, 3:00 PM PST (Score: 90/100)
   Near end of working hours for John

Create meeting with option #1? [y/N/2/3]: y
Event created successfully!

9. Availability checks

The Nylas CLI provides 3 commands for availability: nylas calendar availability check for free/busy queries, nylas calendar find-time for multi-participant slot finding, and nylas calendar ai conflicts for AI-powered conflict detection. These commands query free/busy data across Google Calendar, Outlook, Exchange, Yahoo, iCloud, and IMAP providers through a single interface -- no provider-specific API calls needed.

The find-time command accepts --participants as a comma-separated email list and --duration in minutes. It returns time slots where all participants are simultaneously free. The ai conflicts command scans upcoming events and flags hard conflicts (simultaneous events), soft conflicts (less than 15 minutes between meetings), and travel-time risks.

# Check your availability for a time window
nylas calendar availability check \
  --start "2026-02-20T08:00:00Z" \
  --end "2026-02-20T18:00:00Z" \
  --participants alice@company.com,bob@company.com

# Find time across participants (duration in minutes)
nylas calendar find-time \
  --participants alice@company.com,bob@company.com \
  --duration 30

# Detect scheduling conflicts for the next 7 days
nylas calendar ai conflicts --days 7

# AI-powered rescheduling of a specific event
nylas calendar ai reschedule --id event_abc123

10. Offline timezone utilities

The nylas timezone commands work 100% offline with no API key, no network connection, and no authentication required. They use the system's IANA Time Zone Database (which contains 594 zone identifiers as of the 2024a release) to convert times, check DST transitions, and find meeting windows across zones. These commands are useful for quick timezone math before scheduling cross-timezone meetings.

The convert command translates a specific time between two zones. The dst command shows upcoming DST transitions for any zone. The find-meeting command identifies overlapping working hours across multiple cities -- useful for distributed teams spanning 3 or more timezones.

# Convert time between zones
nylas timezone convert --from PST --to EST
nylas timezone convert --from UTC --to JST --time "2026-03-01T12:00:00Z"

# Check DST transitions for a zone
nylas timezone dst --zone America/New_York

# Find meeting times across multiple zones
nylas timezone find-meeting --zones "NYC,London,Tokyo"

# List all timezones (filterable by region)
nylas timezone list --filter America

11. Scripting examples

The Nylas CLI's --json flag makes calendar data scriptable with standard Unix tools. Piping event output through jq lets you count events, extract fields, or trigger alerts. A common pattern is a login script that shows today's schedule and warns when you have more than 8 events -- the threshold where, according to Clockwise's 2023 Workday Report, productivity drops by 40% compared to days with 4 or fewer meetings.

This shell script runs at login and prints today's events. If the count exceeds 8, it prints a warning so you can consider declining or rescheduling non-essential meetings.

#!/bin/bash
# morning-schedule.sh -- show today's events at shell login

echo "=== Today's Schedule ==="
nylas calendar events list --days 1

# Check for heavy meeting days
events=$(nylas calendar events list --days 1 --json | jq length)
if [ "$events" -gt 8 ]; then
  echo "WARNING: heavy meeting day ($events events)"
fi

Next steps