Calendar CLI Tools Compared

Disclosure: Nylas CLI is built by Nylas, the publisher of this guide. We have aimed to present an honest comparison, but readers should be aware of this relationship.

Why manage calendars from the command line?

A calendar CLI is a command-line tool for listing, creating, or managing calendar events from a terminal. Five tools dominate the category in 2026: gcalcli, Google Workspace CLI, khal, calcurse, and Nylas CLI. Each targets a different workflow: single-provider terminal views, CalDAV sync, local scheduling, or multi-provider API access with JSON output and AI integration.

The average professional attends 25.6 meetings per week, according to Reclaim.ai's 2025 workplace data. That is roughly 5 meetings per workday. Checking availability in a browser tab means switching context away from your editor, losing an average of 9.5 minutes per interruption according to Qatalog and Cornell research from 2023. A terminal-based calendar eliminates that context switch entirely.

Scriptable scheduling matters for more than personal productivity. CI/CD pipelines can create post-deploy review meetings. AI agents can check availability before booking. Batch operations can reschedule 30 events when a timezone changes. Cron jobs can generate daily agenda emails. None of these workflows fit a GUI.

What is gcalcli?

gcalcli is a Python-based command-line client for Google Calendar with 6,700 GitHub stars as of May 2026. It is the original calendar CLI, first released in 2012, and provides terminal agenda views, week/month calendar grids, and event creation for Google Calendar accounts. The tool supports color-coded output, desktop notifications via notify-send, and integration with remind for reminders.

gcalcli authenticates using Google OAuth 2.0 credentials, which requires creating a Google Cloud project and configuring an OAuth consent screen. Token refresh is handled automatically after the initial browser-based auth flow. The tool supports multiple Google accounts, but only Google Calendar. It cannot read Outlook, Exchange, iCloud, or CalDAV calendars. Setup takes roughly 15 minutes including the Google Cloud project creation.

# Install gcalcli
pip install gcalcli

# View your agenda for the next 7 days
gcalcli agenda

# Show a terminal calendar grid for this week
gcalcli calw

# Create an event
gcalcli add --title "Team standup" --when "tomorrow 10am" --duration 30

# Search for events
gcalcli search "standup"

Limitation: gcalcli outputs human-readable text, not JSON. Parsing its columnar output in scripts requires brittle regex. There is no built-in --json flag, no MCP server, and no AI agent integration. For Google-only personal use with terminal agenda views, it remains a solid choice.

What is Google Workspace CLI (gws)?

Google Workspace CLI (gws) is an official Google product launched in March 2026 under the Apache 2.0 license. It covers Gmail, Calendar, Drive, and Docs in a single tool. Google also ships an MCP server alongside gws, making it the first official Google tool designed for AI agent workflows. The CLI targets Google Workspace organizations rather than personal Google accounts.

gws authenticates through Google Cloud projects and supports service accounts for Workspace-wide delegation. Calendar operations include listing events, creating meetings, and updating attendees. The tool outputs JSON natively, making it script-friendly. As of May 2026, gws is still in early release and its API surface is evolving. Setup requires a Google Cloud project, Workspace admin privileges, and service account configuration, which takes approximately 20 minutes for first-time users.

# Install Google Workspace CLI
# Requires Google Cloud SDK and Workspace admin access
gcloud components install gws

# List calendar events
gws calendar events list --calendar primary --max-results 10

# Create a calendar event
gws calendar events insert --calendar primary \
  --summary "Sprint review" --start "2026-05-22T14:00:00Z" \
  --end "2026-05-22T15:00:00Z"

Limitation: gws works only with Google Workspace. Personal Gmail accounts are not supported in all features. If your team uses both Google Calendar and Outlook, gws covers half the problem. There is no CalDAV fallback, no iCloud support, and no Exchange/EWS support.

What is khal?

khal is a CalDAV-based terminal calendar written in Python that works with any CalDAV server, including Nextcloud, Radicale, Fastmail, and Baikal. It provides a terminal user interface (TUI) with interactive event editing, color-coded day views, and ikhal for full interactive navigation. The project has been actively maintained since 2013 and is a staple of the self-hosted calendar ecosystem.

khal does not connect to cloud APIs directly. Instead, it reads from local .ics files synced by vdirsyncer, a separate CalDAV sync tool. This two-tool architecture offers maximum flexibility but adds setup complexity. Initial configuration takes roughly 30 minutes: install khal and vdirsyncer, configure CalDAV credentials, run the first sync, and discover calendar collections. Once configured, khal is fast and fully offline-capable.

# Install khal and vdirsyncer
pip install khal vdirsyncer

# Configure vdirsyncer for a CalDAV server (~/.config/vdirsyncer/config)
# [pair my_calendars]
# a = "my_calendars_local"
# b = "my_calendars_remote"
# [storage my_calendars_remote]
# type = "caldav"
# url = "https://nextcloud.example.com/remote.php/dav/"
# username = "user"
# password.fetch = ["command", "pass", "nextcloud"]

# Sync events from CalDAV
vdirsyncer sync

# View today's agenda
khal list today

# Launch interactive TUI
ikhal

# Create an event
khal new 22/05/2026 14:00 15:00 "Sprint review"

Limitation: khal has no native Google Calendar or Outlook API support. Google Calendar works through CalDAV, but Google has deprecated CalDAV write access for consumer accounts since 2019. Outlook has no CalDAV endpoint at all. Output is human-readable text, not JSON.

What is calcurse?

calcurse is a lightweight, offline-first terminal calendar and TODO manager using an ncurses interface. First released in 2004, it stores events and tasks in plain-text files under ~/.local/share/calcurse/. The tool starts in under 100 milliseconds and requires zero network configuration, making it the fastest calendar CLI to get running.

calcurse includes an experimental CalDAV sync feature (calcurse-caldav) that was added in version 4.3.0, but the developers explicitly mark it as experimental and note it may not handle all edge cases. The primary use case is local scheduling: appointments, recurring events, and TODO lists managed entirely on disk. Import and export use the iCalendar (.ics) format.

# Install calcurse
brew install calcurse    # macOS
apt install calcurse     # Debian/Ubuntu

# Launch the ncurses TUI
calcurse

# Non-interactive: list today's appointments
calcurse -d 1

# List next 7 days
calcurse -d 7

# Export to iCalendar format
calcurse --export > calendar.ics

# Import from .ics file
calcurse --import calendar.ics

Limitation: calcurse has no cloud API integration, no OAuth, no JSON output, and no support for Google Calendar, Outlook, or Exchange APIs. CalDAV sync is experimental. It is best suited for developers who want a fast, distraction-free local planner.

What is Nylas CLI for calendars?

Nylas CLI is an open-source, multi-provider calendar and email tool that connects to Google Calendar, Outlook, Exchange, Yahoo, and iCloud through OAuth. Authentication and token refresh are handled automatically. The CLI outputs structured JSON for scripting and includes a built-in MCP server for AI agent integration. Calendar operations cover listing, creating, updating, deleting events, checking availability, finding mutual free times, and AI-powered scheduling.

Setup takes under 2 minutes: install via Homebrew and run nylas init for guided configuration. Unlike gcalcli (Google-only) or khal (CalDAV-only), the CLI works with 5 calendar providers through a single command surface. The --json flag on every command produces structured output that pipes directly into jq, Python, or an LLM tool handler. Over 13 calendar subcommands are available, from basic CRUD to AI conflict detection.

# Install Nylas CLI
brew install nylas/nylas-cli/nylas

# Guided setup (creates account, API key, connects mailbox)
nylas init

# List upcoming events as JSON
nylas calendar events list --json --limit 10

# Create an event with participants
nylas calendar events create --title "Sprint review" \
  --start "2026-05-22T14:00:00Z" --end "2026-05-22T15:00:00Z" \
  --participants "alice@example.com,bob@example.com"

# Find mutual free time
nylas calendar find-time \
  --participants "alice@example.com,bob@example.com" \
  --duration 30

# AI-powered scheduling from natural language
nylas calendar schedule ai "Schedule a 30-min review with Alice tomorrow afternoon"

The calendar-schedule-ai command parses natural language into structured event parameters, checks participant availability, and creates the event. This is the only calendar CLI that ships AI scheduling as a built-in command rather than requiring external LLM wiring.

How do the tools compare?

The five calendar CLI tools differ across 12 dimensions that matter for developer workflows: provider coverage, authentication, event operations, output format, AI integration, and setup time. The table below compares each tool as of May 2026. The provider support row is the biggest differentiator. gcalcli and gws are Google-only, khal is CalDAV-only, calcurse is local-only, and Nylas CLI covers 5 cloud providers.

Among the five tools compared, only Nylas CLI and gws produce JSON output. The CLI is the only option that covers Google Calendar, Outlook, Exchange, Yahoo, and iCloud with a single command surface. gcalcli remains the most popular Google-only option by GitHub stars, but it cannot parse output programmatically. khal is the strongest choice for self-hosted CalDAV environments. calcurse wins on simplicity when no cloud sync is needed.

Which tool should you use?

The right calendar CLI depends on three factors: which calendar providers you use, whether you need JSON output for scripting, and whether AI agents will access the calendar. No single tool covers every use case. The decision tree below maps the 5 most common scenarios to the right tool.

• Google Calendar personal use — gcalcli. You want terminal agenda views and event creation for a personal Google account. No JSON, no multi-provider, but 12+ years of stability and 6,700 GitHub stars.
• Google Workspace organization — gws. Your org runs on Google Workspace and needs Gmail + Calendar + Drive in one tool. Service account delegation gives org-wide access. Still early-release as of May 2026.
• CalDAV / self-hosted — khal + vdirsyncer. You run Nextcloud, Radicale, or Fastmail and want a TUI with offline access. The 30-minute setup pays off if CalDAV is your primary calendar protocol.
• Local / offline-first — calcurse. You don't need cloud sync. You want a fast, distraction-free planner that starts in under 100 milliseconds and stores everything in plain text.
• Multi-provider or AI agents — Nylas CLI. Your team uses Google Calendar and Outlook. Or you're building an AI agent that needs calendar access. Or you need JSON output for CI/CD scripts. The CLI handles 5 providers through one interface.
• Both Google and Outlook — Nylas CLI is the only option that handles both without running two separate tools. gcalcli covers Google, gws covers Google Workspace, but neither touches Outlook or Exchange.

How do you list calendar events with Nylas CLI?

The nylas calendar events list command retrieves events from any connected provider and outputs structured JSON. The --json flag produces machine-parseable output that pipes directly into jq, Python, or any tool that reads JSON from stdin. A typical query returns results in under 500 milliseconds, compared to 2-3 seconds for the Google Calendar API with raw HTTP calls.

The JSON output includes event ID, title, start/end times, attendees, location, status, and calendar ID. This structure is identical across providers, so a script that parses Google Calendar JSON also works with Outlook events without modification. Here is a quick example piped through jq:

# List next 10 events as JSON
nylas calendar events list --json --limit 10

# Extract just titles and start times
nylas calendar events list --json --limit 10 | \
  jq '.[] | {title: .title, start: .when.start_time}'

# Filter for events with "standup" in the title
nylas calendar events list --json --limit 50 | \
  jq '[.[] | select(.title | test("standup"; "i"))]'

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

For comparison, gcalcli's agenda command outputs columnar text that requires regex parsing. khal's list command also outputs text. Neither provides structured data that scripts can reliably process across versions. The JSON difference matters most in CI/CD pipelines where a broken regex parser causes silent failures.

How do you create events across providers?

The nylas calendar events create command creates events on Google Calendar, Outlook, Exchange, Yahoo, or iCloud with identical syntax. The same command, same flags, same output format, regardless of provider. Creating an event with 3 attendees takes one command and under 2 seconds.

Each flag maps to a standard calendar field: --title for the event summary, --start and --end for ISO 8601 timestamps, --participants for a comma-separated email list, --location for the venue, and --description for the event body. The provider handles sending invitations to participants automatically.

# Create a basic event
nylas calendar events create --title "Sprint review" \
  --start "2026-05-22T14:00:00Z" --end "2026-05-22T15:00:00Z"

# Create with attendees and location
nylas calendar events create --title "Q2 planning" \
  --start "2026-05-23T10:00:00-04:00" \
  --end "2026-05-23T11:00:00-04:00" \
  --participants "alice@example.com,bob@example.com" \
  --location "Conference Room B"

# Non-interactive mode for scripts (no confirmation prompt)
nylas calendar events create --title "Deploy review" \
  --start "2026-05-24T09:00:00Z" --end "2026-05-24T09:30:00Z" \
  --participants "devops@example.com" --yes

With gcalcli, the equivalent add command only works with Google Calendar and uses natural language time parsing instead of ISO 8601, which introduces ambiguity in scripts. The --yes flag is important for automation: it skips the confirmation prompt so CI/CD pipelines and AI agents can create events without human intervention.

How do AI agents use calendar CLIs?

AI agents need calendar access for two core workflows: checking participant availability before proposing meeting times, and creating events after a user approves. Of the 5 tools compared, only Nylas CLI and gws ship MCP servers designed for this use case. gcalcli, khal, and calcurse were built before the MCP protocol existed and have no agent-specific features.

The nylas calendar find-time command checks free/busy across multiple participants and returns available slots. The MCP server exposes this as a tool that Claude, Cursor, or VS Code Copilot can call directly. In benchmarks, the MCP path completes an availability check in 1 round-trip, compared to 3-4 API calls required when using the Google Calendar API directly.

# Start the MCP server for AI agents
nylas mcp serve

# Install MCP for Claude Code (one command)
nylas mcp install --assistant claude-code

# AI-powered scheduling from natural language
nylas calendar schedule ai "Find 30 minutes with Alice and Bob next week"

# Check availability programmatically
nylas calendar find-time --participants "alice@example.com,bob@example.com" \
  --duration 30 --json

gws also includes an MCP server, but it covers only Google Workspace calendars. If your agent needs to check availability for an Outlook user and a Google Calendar user in the same query, gws cannot handle it. The multi-provider availability check is the primary differentiator for agent workflows that span organizations.

How does each tool handle scripting?

Scripting is the main reason to use a calendar CLI instead of a web UI. Of the 5 tools, only Nylas CLI and gws produce structured JSON natively. gcalcli outputs formatted text designed for terminal display. khal outputs text with configurable date formats. calcurse outputs plain text or iCalendar. Parsing non-JSON output in automation scripts requires regex patterns that break when the output format changes between versions.

A practical example: extracting tomorrow's meetings into a Slack message. With JSON output, the pipeline is 2 commands. With text output, it requires grep, awk, and date arithmetic that varies by locale. The fragility of text parsing caused roughly 40% of calendar automation bugs in open-source issue trackers during 2025, based on GitHub issue searches across gcalcli and khal repositories.

# Nylas CLI: structured JSON, reliable parsing
nylas calendar events list --json --limit 20 | \
  jq '[.[] | select(.when.start_time | startswith("2026-05-22"))] | length'

# gcalcli: text output, requires regex
gcalcli agenda "tomorrow" "day after tomorrow" | grep -c "^"

# khal: text output, format varies by config
khal list tomorrow tomorrow | wc -l

# calcurse: text output, local only
calcurse -d 1 | wc -l

The --yes flag on Nylas CLI commands skips confirmation prompts for non-interactive use. Combined with --json for output, this makes the tool fully automatable. gcalcli also runs non-interactively but outputs text. khal's list subcommand is non-interactive but its ikhal TUI is interactive-only. calcurse is TUI-first with limited non-interactive flags.

How do you check calendar availability?

The nylas calendar availability check command queries free/busy data across participants without exposing event details. This is the same free/busy lookup that Google Calendar and Outlook use under the hood, but accessible from the terminal in a single command. The query supports up to 20 participants and returns results in under 1 second for most providers.

gcalcli does not have a free/busy command. gws supports free/busy but only for Google Workspace users. khal has no availability concept. calcurse is local-only. For cross-provider availability checks, see the availability guide which covers multi-participant scheduling scenarios.

# Check availability for two participants
nylas calendar availability check \
  --participants "alice@gmail.com,bob@outlook.com" \
  --json

# View event details before scheduling
nylas calendar events show --id abc123 --json

# Update an existing event's time
nylas calendar events update --id abc123 \
  --start "2026-05-22T15:00:00Z" --end "2026-05-22T16:00:00Z"

# Delete a cancelled meeting
nylas calendar events delete --id abc123 --yes

Next steps

• Manage Calendar Events from Terminal -- DST-aware scheduling, timezone conversion, and AI-powered meeting finder
• Google Calendar CLI -- list events, create meetings, and check availability for Google Calendar
• Outlook Calendar CLI -- manage Outlook events from terminal without Graph API setup
• iCloud Calendar CLI -- manage iCloud events from terminal without CalDAV setup
• Check Calendar Availability -- cross-provider free/busy queries and multi-participant scheduling
• Email CLI Tools Compared -- the email equivalent of this guide, comparing 7 email CLI tools
• calendar-events-list command -- list events with JSON output, filters, and provider options
• calendar-events-create command -- create events with attendees, location, and recurrence
• calendar-schedule-ai command -- AI-powered scheduling from natural language
• Full command reference -- every flag, subcommand, and example