Guide

Check Calendar Availability from Terminal

Run calendar availability checks from scripts, CI jobs, and agent workflows. Nylas CLI returns free/busy data as JSON so you can pick a time before you create an event.

Written by Qasim Muhammad Staff SRE

Reviewed by Qasim Muhammad

Verified — CLI 3.1.1 · Google Calendar, Outlook Calendar · last tested May 15, 2026

Why check availability before creating the event?

A calendar invite is easy to create and hard to unwind after it lands on five busy calendars. A quick calendar availability check lets you validate open time first, then create the event only when the window works.

This is useful for command-line scheduling, support handoffs, interview coordination, AI agents, and scripts that need to book time without opening a browser.

1. Run a free/busy check

nylas calendar availability check checks whether two participants are free in a one-hour window. Pass a grant ID when you want to run the check from a specific connected account.

nylas calendar availability check "$NYLAS_GRANT_ID" \
  --emails alice@example.com,bob@example.com \
  --start "2026-05-18T13:00:00Z" \
  --end "2026-05-18T14:00:00Z" \
  --json

Use ISO timestamps in UTC for scripts. That keeps CI, cron jobs, and local developer machines from disagreeing about timezone math.

2. Search a wider range

If you do not have a fixed start and end time, search a date range and pass the desired meeting duration. This is a better fit for agents that need to suggest several options to a user.

nylas calendar availability check "$NYLAS_GRANT_ID" \
  --emails alice@example.com,bob@example.com \
  --start "2026-05-18T13:00:00Z" \
  --end "2026-05-22T21:00:00Z" \
  --duration 30m \
  --json

3. Ask the CLI to rank meeting times

Availability tells you whether time is open. nylas calendar find-time goes one step further and scores possible times using participant timezones, working hours, weekdays, and holidays.

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --timezones America/Toronto,Europe/London \
  --duration 45m \
  --days 7 \
  --json

Use this when you want a ranked shortlist, then pass the selected time into nylas calendar events create.

4. Fail fast in a scheduling script

Calendar workflows often run inside a shell script. Keep the availability step separate from event creation so the script can exit before sending an invite.

set -euo pipefail

window=$(nylas calendar availability check "$NYLAS_GRANT_ID" \
  --emails "$ATTENDEES" \
  --start "$START_AT" \
  --end "$END_AT" \
  --json)

echo "$window" | jq .

# If the chosen window is not open, stop here and ask for another time.
# When it is open, continue with nylas calendar events create.

What does a calendar availability answer mean?

A calendar availability answer is a decision point, not just a list of busy blocks. Your script asks whether a proposed window can work for a set of people, calendars, or resources. The response lets the workflow either move forward, ask for another time, or produce a ranked set of options. That is why this command belongs before event creation, not after it.

Free/busy data is intentionally narrower than a full calendar event. It tells you that a calendar is occupied, but it should not expose private event titles, attendees, notes, or locations. This is useful for scheduling tools because the system can respect calendar privacy while still avoiding conflicts. If the workflow needs event details later, read those events through a separate, permissioned path.

Think of the availability result as a guardrail. A support escalation bot can check whether the on-call engineer has open time before suggesting a handoff. A sales tool can verify that an account executive and a buyer are both free before sending a meeting link. A CI job can confirm that a release window is open before creating a deployment hold.

How should scripts handle time zones?

Use UTC inside automation and convert to local time only at the display edge. UTC timestamps make shell scripts, GitHub Actions, cron jobs, and developer laptops agree on the same instant. If the command receives local wall-clock text from a user, normalize it before calling the availability check. This avoids the classic bug where a meeting is correct on one machine and one hour off on another.

Store the original user timezone alongside the selected slot. The scheduler may need to show the same meeting back to the user, send confirmation copy, or explain why a time is outside working hours. The availability command can tell you whether time is open, but your product still owns the presentation and user preference layer.

Daylight saving time is the reason to avoid hand-written offset math. A fixed `-0500` offset is not the same as `America/Toronto` across a full year. When you need ranked suggestions across regions, use `nylas calendar find-time` with timezones, then use the availability check to verify the final selected window.

How many participants should you check at once?

Check the calendars that can block the meeting. For a one-on-one call, that may be only the organizer and attendee. For an interview, it can include the candidate, recruiter, interviewer, and room calendar. For a customer onboarding call, it may include the customer, customer success manager, solutions engineer, and a shared support calendar.

Do not add observers who do not affect scheduling. Extra attendees increase the chance of a conflict and can turn a workable meeting into a false negative. If someone only needs the notes, add them after booking or send a follow-up email. Availability checks are most useful when the participant list represents people whose attendance is required.

For optional attendees, run a second check or label them separately in your scheduling logic. The first check can protect the required group. The second can report which optional people are free. That lets a human or agent decide whether to book now, include fewer optional attendees, or search for a better slot.

How do you turn availability into a booking workflow?

A reliable booking flow has three stages. First, find or receive a candidate slot. Second, run the availability check as close to booking time as possible. Third, create the event only if the selected window is still open. The order matters because calendars change between suggestion and confirmation.

For chat agents and support bots, keep the final check close to the user action. If the agent suggests three times in the morning and the user picks one in the afternoon, do not assume the earlier result still applies. Run the check again before creating the event. If the slot is gone, apologize with a new shortlist instead of sending a bad invite.

For scripts, return machine-readable outcomes. A shell script can exit `0` when the slot is available, `2` when the slot is busy, and `1` for command or auth errors. Your scheduler can then treat calendar conflicts differently from infrastructure failures. That distinction keeps retries from repeatedly booking against a known conflict.

What causes false availability results?

The most common cause is checking the wrong account. Confirm the grant ID belongs to the organizer or calendar owner you expect. If a developer has multiple grants configured, a script that relies on the default grant can read the wrong calendar. Pass the grant ID explicitly in CI and production automation.

Another cause is a mismatch between event visibility and calendar selection. Some providers expose primary calendars, shared calendars, and room calendars differently. If a room booking appears open but users know it is busy, verify that the room calendar is included in the check and that the connected grant has permission to read it.

Finally, watch for stale input. Availability checks use the start, end, duration, participants, and calendar context you pass at that moment. If a later step changes the attendee list, room, or duration, run the check again. Treat the result as tied to one exact request, not as a reusable permission slip for every version of the meeting.

How do room and resource calendars change the check?

Rooms, equipment, and shared calendars are participants in the scheduling decision even when no human reads their inbox. If a meeting needs a specific conference room, check that resource calendar before creating the event. Otherwise the people can be free while the room is already booked.

Resource calendars often have different permission rules from user calendars. A connected account may see free/busy state but not event details, or it may have access to some rooms and not others. Your script should fail clearly when a room calendar cannot be checked. A silent omission can produce a meeting that looks valid but has nowhere to happen.

Store the resource identifier next to the booking. If an event later moves rooms, the booking record should show both the original choice and the final calendar event state. That makes support easier when a user asks why a room changed or why a booking request failed.

How do you choose between multiple open slots?

Availability is a yes-or-no answer for a candidate slot, but scheduling products often need ranking. Rank slots by user preference, working hours, time zone fairness, meeting urgency, attendee seniority, and travel or room constraints. Then verify the selected slot again before booking.

For external meetings, avoid offering too many options. Three to five ranked times are easier to choose than a full calendar grid. For internal tools, a longer list can work if users need control. The availability command gives your app data; the product should decide how much choice is helpful.

Keep ranking rules explainable. If an AI agent suggests Tuesday at 10:00, the user should be able to understand why that time was selected. `Everyone is free, it is inside working hours, and it is the earliest slot this week` is a useful explanation. A black-box score is harder to trust.

When should you move from CLI scripts to API code?

The CLI is a strong starting point for local tools, CI jobs, prototypes, and agent workflows. Move the same logic into API code when scheduling becomes a core product path with user sessions, persistent records, retry queues, and deeper UI behavior. The command-line version still helps you validate the workflow before writing application code.

Keep the request shape consistent when you move. The script should already know the organizer, attendees, start, end, duration, and time zone context. The API implementation should accept the same fields and produce the same decision states. This makes the migration a change in transport, not a rewrite of scheduling rules.

Preserve the CLI as an operations tool. Even after a product uses API code, support and engineering teams can use the CLI to reproduce availability checks from a ticket. That shortens debugging because a human can test the same inputs without writing a one-off script.

How do you protect calendar privacy?

Availability checks should reveal only what the scheduler needs. A user can be busy without exposing the meeting title, attendee list, or notes. Design your logs and UI around that privacy boundary. Store the result as open or busy, not as a copied calendar event.

Be careful with screenshots and debug output. Calendar data can reveal travel, customer names, health appointments, interviews, or internal incidents. If a script prints raw provider output, route it only to secure logs. For routine operation, print a reduced summary.

Use least-privilege access where possible. If the workflow only needs free/busy state, do not request broader calendar access just because it is convenient. The smaller the permission surface, the easier it is to explain the integration to security reviewers and users.

What should happen after no time is available?

A no-availability result should lead to a useful fallback. The script can widen the date range, reduce optional attendees, ask for a shorter duration, or route the request to a human coordinator. Returning only `busy` gives the caller no path forward.

For customer-facing flows, explain the next step in plain language. Say that no shared time was available in the selected range and offer a new range or async follow-up. For internal automation, return a structured reason so the caller can retry with different inputs.

Track no-slot outcomes over time. If one team, room, or meeting type constantly has no availability, the scheduling policy may be too narrow. Those metrics can reveal staffing gaps, bad routing, or meeting durations that are longer than the calendar can support.

References for this workflow

Next steps