# Share your calendar with your agent

Source: https://developer.nylas.com/docs/v3/getting-started/agent-calendar/

Give your agent full access to the calendar you already use — a personal Google Calendar, a work Outlook calendar, or any Exchange/iCloud calendar. Events the agent creates appear on your calendar, and invites come to your address. The Nylas CLI handles provider auth and returns structured JSON so your agent can drive every operation from shell commands.

If you'd rather the agent have its own dedicated calendar (for events it hosts or manages on its own), see [Give your agent its own calendar](/docs/v3/getting-started/agent-own-calendar/).

## Prerequisites

Make sure the CLI is installed and authenticated against the account whose calendar you want to share. If not, follow the [AI agents quickstart](/docs/v3/getting-started/cli-for-agents/) first.

```bash
nylas auth whoami --json
```

## List upcoming events

See what's on the user's calendar. The `--days` flag controls the lookahead window.

```bash
nylas calendar events list --days 7 --json
```

View details for a specific event:

```bash
nylas calendar events show <EVENT_ID> --json
```

## Create an event

Schedule a meeting with participants. The CLI handles timezone conversion and sends invitations automatically.

```bash
nylas calendar events create \
  --title "Project kickoff" \
  --start "2026-04-15T10:00:00" \
  --end "2026-04-15T11:00:00" \
  --participants "alice@example.com,bob@example.com" \
  --description "Review goals and assign workstreams"
```

Natural language scheduling:

```bash
nylas calendar schedule ai "30 minute sync with alice@example.com next Tuesday afternoon"
```

## Find available times

Before scheduling, check when participants are free. This queries across multiple users' calendars and returns open slots.

```bash
nylas calendar find-time \
  --participants "alice@example.com,bob@example.com" \
  --duration 30m \
  --json
```

### Update and cancel events

```bash
# Update an event
nylas calendar events update <EVENT_ID> \
  --title "Updated: Project kickoff" \
  --start "2026-04-15T14:00:00" \
  --end "2026-04-15T15:00:00"

# Delete an event
nylas calendar events delete <EVENT_ID> --yes
```

### List calendars

Each user can have multiple calendars. List them to find the right one for event operations.

```bash
nylas calendar list --json
```

### Example: scheduling assistant workflow

Here's a realistic pattern for an agent that handles meeting requests:

```bash
# 1. Check the user's schedule for next week
nylas calendar events list --days 7 --json

# 2. Find a time that works for all participants
nylas calendar find-time \
  --participants "alice@example.com,bob@example.com" \
  --duration 60m \
  --json

# 3. (Agent picks the best slot based on preferences)

# 4. Create the meeting
nylas calendar events create \
  --title "Q3 planning" \
  --start "2026-04-16T10:00:00" \
  --end "2026-04-16T11:00:00" \
  --participants "alice@example.com,bob@example.com" \
  --description "Quarterly planning session"

# 5. Confirm via email
nylas email send \
  --to "alice@example.com,bob@example.com" \
  --subject "Meeting scheduled: Q3 planning" \
  --body "I've scheduled Q3 planning for April 16 at 10am. Calendar invite sent." \
  --yes
```

### Using MCP instead

If your agent supports [Model Context Protocol](https://modelcontextprotocol.io/) (Claude Code, Cursor, Windsurf, VS Code, Codex CLI), register the CLI as an MCP server for typed calendar tools:

```bash
nylas mcp install --assistant claude-code
```

See the [MCP docs](/docs/dev-guide/mcp/) for details.

## What's next

- **[Give your agent its own calendar](/docs/v3/getting-started/agent-own-calendar/)** -- give the agent a dedicated calendar on a Nylas Agent Account, independent of yours
- **[Share your email with your agent](/docs/v3/getting-started/agent-email/)** -- read, send, and search email on your connected inbox
- **[Give your agent call recordings](/docs/v3/getting-started/agent-notetaker/)** -- record meetings and get transcripts
- **[AI agents quickstart](/docs/v3/getting-started/cli-for-agents/)** -- full CLI setup and command reference
- **[CLI guides](https://cli.nylas.com/guides)** -- 85+ step-by-step guides for email, calendar, and more