Calendar Analytics from the Terminal

You spend hours in meetings every week. How many hours exactly? Which day is heaviest? What share are standing syncs you could cancel? Those questions are hard to answer from a calendar UI, but straightforward from the terminal. Pipe your calendar data through jq and you have the numbers in seconds.

How do you connect your calendar for analytics?

Calendar analytics starts with a connected account. Nylas CLI stores credentials locally after a one-time nylas auth login flow that takes under 60 seconds and supports Google Calendar, Outlook, Exchange, Yahoo, iCloud, and IMAP providers through the same interface. Once connected, every analytics command reads from the same local credentials — no tokens to manage per run.

# Authenticate once — opens OAuth in your browser
nylas auth login

# Confirm the connection shows your calendar account
nylas calendar list

For CI or cron environments, skip the interactive flow and use environment variables instead: NYLAS_API_KEY, NYLAS_GRANT_ID, and NYLAS_DISABLE_KEYRING=1. See the getting started guide for headless setup.

How do you pull 28 days of events as JSON?

The nylas calendar events list command fetches upcoming events from all connected calendars. Pass --days 28 to cover a full 4-week window and --json to get structured output. A 28-day window typically returns 50–200 events for an active calendar, well within Nylas rate limits in a single request.

# Fetch 28 days and save to a file for repeated analysis
nylas calendar events list --days 28 --json > events.json

# Or pipe directly into jq
nylas calendar events list --days 28 --json | jq length

Saving to a file lets you run multiple jq queries against the same snapshot without hitting the API again. This is the right pattern for a weekly report script that runs several aggregations in sequence.

How do you count total meeting hours?

Total meeting hours is the sum of (end_time - start_time) across all events with valid timestamps, divided by 3600 to convert seconds to hours. The expression below filters out all-day events (which use when.date rather than Unix timestamps), guards against zero-duration entries, and rounds to one decimal place.

# Total meeting hours over the 28-day window
nylas calendar events list --days 28 --json | jq '
  [
    .[]
    | select(.when.start_time? and .when.end_time?)
    | select(.when.end_time > .when.start_time)
    | (.when.end_time - .when.start_time)
  ]
  | add // 0
  | . / 3600
  | . * 10
  | round
  | . / 10
'

A typical result for an active calendar is 20–40 hours over 28 days. If the number surprises you — in either direction — that's the point. The CLI reads from your actual calendar, not a self-reported estimate.

How do you count total meetings and average per day?

Event count and daily average are the two baseline metrics for calendar load. The count covers every event with valid timestamps — including short 15-minute check-ins. Dividing by 20 (working days in a 28-day window) gives the daily average. According to Microsoft's 2023 Work Trend Index, the average knowledge worker attends 25.6 meetings per week — roughly 5.1 per day. Compare your output against that baseline to calibrate.

# Count meetings and compute daily average
nylas calendar events list --days 28 --json | jq '
  [
    .[]
    | select(.when.start_time? and .when.end_time?)
    | select(.when.end_time > .when.start_time)
  ]
  | {
      total_meetings: length,
      avg_per_working_day: (length / 20 * 10 | round / 10)
    }
'

How do you split recurring vs one-off meetings?

Recurring meetings carry a non-null recurrence field in the event JSON — typically an RRULE string like FREQ=WEEKLY;BYDAY=MO. One-off meetings have a null or absent recurrence field. The split below counts both types in one pass and computes the recurring percentage, which tells you how much of your meeting time is committed overhead versus reactive scheduling.

# Recurring vs one-off breakdown
nylas calendar events list --days 28 --json | jq '
  [
    .[]
    | select(.when.start_time? and .when.end_time?)
    | select(.when.end_time > .when.start_time)
  ] as $events
  | {
      recurring: ($events | map(select(.recurrence != null)) | length),
      one_off:   ($events | map(select(.recurrence == null)) | length),
      total:     ($events | length),
      recurring_pct: (
        if ($events | length) > 0 then
          ($events | map(select(.recurrence != null)) | length) * 100
          / ($events | length)
          | . * 10 | round | . / 10
        else 0 end
      )
    }
'

A recurring-meeting ratio above 70% often signals calendar sprawl — standing syncs accumulated over months that preempt new work. Below 30% can indicate a reactive team that under-invests in structured coordination.

How do you find your busiest meeting day of the week?

The busiest day is the weekday with the highest total meeting minutes across the full 28-day window. Aggregating across 4 weeks smooths out anomalies: one unusually heavy Thursday doesn't mean Thursdays are always heavy, but 4 consecutive heavy Thursdays does. The jq expression converts each event's Unix start timestamp to a weekday name using todate | split("T")[0] | strptime("%Y-%m-%d") | strftime("%A"), then groups and sums minutes per day.

# Total meeting minutes per weekday, sorted descending
nylas calendar events list --days 28 --json | jq '
  [
    .[]
    | select(.when.start_time? and .when.end_time?)
    | select(.when.end_time > .when.start_time)
    | {
        day: (.when.start_time | todate | split("T")[0]
              | strptime("%Y-%m-%d") | strftime("%A")),
        minutes: ((.when.end_time - .when.start_time) / 60)
      }
  ]
  | group_by(.day)
  | map({
      day: .[0].day,
      total_minutes: (map(.minutes) | add | round)
    })
  | sort_by(-.total_minutes)
'

The output is a ranked list — Monday through Friday sorted by total minutes. Your heaviest day is the first entry. If it's more than 30 minutes heavier than the second-place day, that pattern is consistent enough to act on.

How do you combine all metrics into one report?

Running all four analytics queries from separate commands works fine for exploration, but a single script that produces a structured JSON report is more useful for weekly automation. The script below fetches events once, saves them locally, and runs all aggregations in one pass — total hours, meeting count, recurring split, and busiest day. It takes under 5 seconds on a 28-day window.

#!/usr/bin/env bash
# calendar-report.sh — weekly meeting analytics

set -euo pipefail
SNAPSHOT=$(nylas calendar events list --days 28 --json)

echo "$SNAPSHOT" | jq '
  [
    .[]
    | select(.when.start_time? and .when.end_time?)
    | select(.when.end_time > .when.start_time)
  ] as $ev
  | {
      window_days: 28,
      total_meetings: ($ev | length),
      avg_per_working_day: (($ev | length) / 20 * 10 | round | . / 10),
      total_hours: (
        [$ev[] | (.when.end_time - .when.start_time)]
        | add // 0 | . / 3600 * 10 | round | . / 10
      ),
      recurring_pct: (
        if ($ev | length) > 0 then
          ($ev | map(select(.recurrence != null)) | length) * 100
          / ($ev | length) | . * 10 | round | . / 10
        else 0 end
      ),
      busiest_day: (
        [$ev[]
          | {
              day: (.when.start_time | todate | split("T")[0]
                    | strptime("%Y-%m-%d") | strftime("%A")),
              mins: ((.when.end_time - .when.start_time) / 60)
            }
        ]
        | group_by(.day)
        | map({day: .[0].day, total: (map(.mins) | add | round)})
        | sort_by(-.total)
        | .[0].day
      )
    }
'

Run this as a cron job every Monday morning to get last week's report in your terminal. Store each output as a dated JSON file (~/.calendar-stats/$(date +%Y-%W).json) and you have a 52-week archive in roughly 50 KB of total storage.

Tested on Nylas CLI 3.1.16 with Google Calendar

These commands were verified against Nylas CLI 3.1.16 on macOS 15 (Sequoia) with a Google Calendar account on 2026-06-09. The jq expressions require jq 1.6 or later, which ships with macOS Homebrew (brew install jq) and all major Linux distributions. The strptime and strftime builtins are not available in jq 1.5.

Provider-side behavior for Outlook Calendar and Exchange is described from documented provider behavior, not from a verified end-to-end test on each backend — verify locally before deploying provider-specific analytics rules.

References

• Nylas Calendar and Events quickstart — calendar API concepts behind event list and analytics commands
• Microsoft 2023 Work Trend Index — 25.6 average meetings per week for knowledge workers, used in count baseline
• Google Calendar freeBusy API reference — provider-native event shape that maps to Nylas JSON fields

Next steps

• Manage calendar events from the terminal — event list, create, update, and timezone workflows
• Check calendar availability from the terminal — run free/busy checks before creating events
• Export calendar events from the CLI — save events to CSV or JSON for further analysis
• Extract email data with jq — the same jq patterns applied to email JSON
• Command reference — every calendar events list flag and subcommand