Guide

How to Manage Calendar Events from the Command Line

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.

Why manage your calendar from the terminal?

If you spend your day in the terminal -- writing code, managing servers, running scripts -- switching to a browser tab to check your schedule creates unnecessary friction. A CLI-based calendar lets you:

  • 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

brew install nylas-cli/tap/nylas
nylas auth login
nylas calendar list  # verify

2. List upcoming events

# 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

$ 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

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

# All-day event
nylas calendar events create \
  --title "Team Offsite" \
  --start "2026-03-01" \
  --all-day

# With participants
nylas calendar events create \
  --title "Design Review" \
  --start "2026-02-21 14:00" \
  --end "2026-02-21 15:00" \
  --participant alice@company.com \
  --participant bob@company.com

4. DST-aware scheduling

A subtle but real problem: scheduling a meeting at 2:30 AM on the day clocks spring forward. That time does not exist. The CLI catches this before you create a broken event:

$ nylas calendar events create --title "Early Sync" --start "Mar 8, 2026 2:30 AM"

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.

It also warns about fall-back duplicates, where 1:00-2:00 AM occurs twice. Use --ignore-dst-warning to skip the check if you know what you are doing.

5. Working hours validation

Configure your working hours and the CLI warns you before you schedule meetings outside them:

# ~/.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
$ 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

Unlike working hours (which you can override), break blocks are hard enforced -- you cannot accidentally schedule over lunch:

# 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"
$ 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 locking

When you create an event for an in-person meeting in a specific city, you want the time to stay in that city's timezone even if someone views it from a different location:

# Lock to your current timezone
nylas calendar events create \
  --title "NYC Office All-Hands" \
  --start "2026-02-20 09:00" \
  --location "New York Office" \
  --lock-timezone

# The event shows a lock indicator
# When: Fri, Feb 20, 2026, 9:00 AM EST (locked)
# (Your local: 6:00 AM PST)

# Unlock later
nylas calendar events update event_123 --unlock-timezone

8. AI-powered natural language scheduling

Describe what you want in plain English and the CLI finds the best times. Works with local LLMs (Ollama) for privacy or cloud providers for speed:

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

# Privacy mode (local LLM, no data leaves your machine)
nylas calendar schedule ai --privacy "sensitive planning session next week"

# Use a specific provider
nylas calendar schedule ai --provider claude "team retrospective on Friday"

# Auto-confirm the first suggestion
nylas calendar schedule ai --yes "lunch with Alice next Monday"

Example output

$ 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

# Check your availability
nylas calendar availability check

# Find time across participants
nylas calendar find-time \
  --participants alice@company.com,bob@company.com \
  --duration 1h

# Detect conflicts in the next 7 days
nylas calendar ai conflicts --days 7

# AI-powered rescheduling
nylas calendar ai reschedule event_123 --reason "Conflict detected"

10. Offline timezone utilities

These commands work 100% offline -- no API key required. Useful for quick timezone math:

# 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
nylas timezone dst --zone PST --year 2026

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

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

11. Scripting examples

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

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

# Check for conflicts
conflicts=$(nylas calendar ai conflicts --days 1 --json | jq length)
if [ "$conflicts" -gt 0 ]; then
  echo "WARNING: $conflicts scheduling conflicts detected"
fi

Next steps