Source: https://cli.nylas.com/guides/manage-virtual-calendars-cli

# Manage Virtual Calendars from the CLI

A conference room doesn't have a Gmail login, and a borrowed projector doesn't have an Outlook mailbox. Virtual calendars give those resources a bookable schedule with no connected account. This guide creates, lists, inspects, and deletes them, then books events against them from the terminal.

Written by [Aaron de Mello](https://cli.nylas.com/authors/aaron-de-mello) Senior Engineering Manager

Reviewed by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad)

Updated June 9, 2026

> **TL;DR:** Run `nylas calendar virtual create --email room-a@company.com` to mint a bookable resource that has no mailbox, then `virtual list`, `show`, and `delete` to manage it. The reason the returned grant ID matters — and where you feed it — is at the bottom.

## What is a virtual calendar?

A virtual calendar is a Nylas-hosted calendar that belongs to no third-party provider account. It carries no Google or Microsoft login and no synced mailbox, yet it accepts events and reports free/busy exactly like a real calendar. That makes it the right home for a conference room, a loaner laptop, or an external contractor who never connects an inbox.

Each virtual calendar is created as its own grant, so it gets a stable grant ID you address in later commands. The `--email` you pass is an identifier, not a real address — nothing is delivered to it. The Nylas v3 docs describe these as a way to schedule against resources without an underlying provider, which removes the need to provision a shared mailbox per room. One CLI call replaces an admin ticket that often takes a day to clear.

## How do I create a virtual calendar?

You create one with `nylas calendar virtual create` and a single required flag, `--email`. The value is just a label for the resource; it does not need to resolve or receive mail. The command returns a grant ID you reuse for every booking against that resource, so capture it on first run.

```bash
# Mint a bookable calendar for a meeting room
nylas calendar virtual create --email conference-room-a@company.com

# Equipment works the same way — the email is only an identifier
nylas calendar virtual create --email projector-1@company.com --json
```

Adding `--json` gives you machine-readable output to pipe into `jq` when you script the creation of dozens of rooms at once. Naming is the one decision worth making up front: use a stable convention like `room-{floor}-{name}@company.com` so a 40-room office stays readable in `virtual list` output instead of becoming 40 opaque identifiers.

## How do I list and inspect virtual calendars?

The `nylas calendar virtual list` command prints every virtual calendar grant in your Nylas application, and `virtual show <grant-id>` returns the detail for one. Together they answer the two questions you ask most often: which resources exist, and which grant ID maps to a given room.

```bash
# Every virtual calendar in the application
nylas calendar virtual list

# Detail for one resource, by grant ID
nylas calendar virtual show vcal-grant-123 --json
```

For automation, pipe the list through `--json` and resolve a friendly name to its grant ID instead of hardcoding IDs in scripts. The example below looks up the room created above and stores its grant ID in a shell variable, which keeps a booking script readable when your inventory grows past 10 or 20 resources. Resolving by label also survives a recreate, since a deleted-and-remade room keeps the same `--email` identifier even though its grant ID changes.

```bash
# Resolve "conference-room-a" to its grant ID
GRANT=$(nylas calendar virtual list --json \
  | jq -r '.[] | select(.email == "conference-room-a@company.com") | .id')
echo "$GRANT"
```

## How do I book events against a virtual calendar?

You book a virtual calendar exactly like any other: pass its grant ID as the positional argument to `nylas calendar events create`, then set a title, start, and end. The event lands on the resource's calendar and marks it busy, so the next availability check sees the room as taken for that window.

```bash
# Reserve room A for a 1-hour standup using its grant ID
nylas calendar events create "$GRANT" \
  --title "Sprint standup" \
  --start "2026-06-15 09:00" --end "2026-06-15 09:30" \
  --participant team@company.com

# Confirm the room reads as busy for that window
nylas calendar availability check --emails conference-room-a@company.com \
  --start "2026-06-15 09:00" --duration 8h --json
```

Events default to `--busy`, which is what you want for a resource: a booked room must block double-booking. Use `nylas calendar events list -c <calendar-id>` to read what's on a resource, and `events delete` to release a slot. Because the calendar has no inbox, no acceptance email is ever sent — the booking is a pure schedule write, which is why a create call typically returns in under 1 second.

## Why use a virtual calendar over a shared mailbox?

A virtual calendar avoids the licensing and provisioning cost of a shared mailbox. Google and Microsoft both bill resource calendars against directory objects and tie them to admin-console workflows; a virtual calendar is created in one API-backed CLI call and carries no per-seat cost, which matters when you track 30 rooms or 200 pieces of equipment.

The trade-off is integration scope. A virtual calendar lives inside your Nylas application and is not visible in an end user's native Google or Outlook calendar grid unless you surface it yourself. Microsoft deprecated Basic Auth for Exchange Online in October 2022 and now gates room mailboxes behind Graph application permissions and Azure AD app registration; a virtual calendar sidesteps that registration entirely. Choose virtual calendars when the resource is an internal booking target you control end to end, and choose a provider room mailbox when users must see the resource inside their own first-party calendar app.

## Next steps

- [Manage your calendar from the terminal](https://cli.nylas.com/guides/manage-calendar-from-terminal) — the hub guide for list, create, update, and delete events
- [Create calendar invites](https://cli.nylas.com/guides/create-calendar-invites-cli) — add participants and send real invites for booked events
- [Check calendar availability](https://cli.nylas.com/guides/check-calendar-availability-cli) — confirm a room or contractor is free before booking
- [Set calendar working hours](https://cli.nylas.com/guides/set-calendar-working-hours-cli) — constrain when a resource can be booked
- [Calendar AI assistant](https://cli.nylas.com/guides/calendar-ai-assistant-cli) — book rooms and resources with natural-language prompts
- [Command reference](https://cli.nylas.com/docs/commands) — every flag, subcommand, and example
- [Nylas: virtual calendars](https://developer.nylas.com/docs/v3/calendar/virtual-calendars/) — the v3 reference for provider-independent calendars
- [Google Calendar API: create events](https://developers.google.com/calendar/api/guides/create-events) — how resource calendars work on Google
- [Microsoft Graph: calendar resource](https://learn.microsoft.com/en-us/graph/api/resources/calendar) — the equivalent room-mailbox model on Microsoft 365