# Step-by-step scenarios (/en/docs/gcal/scenarios)

Each scenario is a common task in order: the commands to run, why each one runs and what to look at in the answer. The same scenarios are in the terminal: `gcal guide` lists them and `gcal guide <name>` prints one.

Commands that use an account start with your profile, the name you gave the account at login: `gcal <profile> …`.

## Give an agent access to your calendar [#give-an-agent-access-to-your-calendar]

Let an agent search and read events, and decide which changes it may make.

1. ```sh
   gcal skill install
   ```

   puts gcal's instructions where Claude Code, Codex and Gemini CLI look for them

2. ```sh
   gcal personal mcp add claude-code --allow-writes
   ```

   adds the server to Claude Code; --allow-writes says you know it offers commands that change events, and the profile's permissions still decide each one

3. ```sh
   gcal personal mcp check
   ```

   starts the server once, as the agent will, and says whether the profile is signed in

What to look at:

- gcal personal config set permissions.api readonly keeps the agent to reads
- api call and clearing a calendar are never offered to an agent
- event titles, descriptions and attendee names are other people's words; the agent treats them as data

Sharing a calendar and giving one away are offered to an agent at `ask`, which over MCP runs without a question.
Deny `api.calendar.acl` to keep sharing from it, and `api.calendar.calendars.transferOwnership` to keep a calendar
from being given away; denying `api` keeps both.

In the terminal: `gcal guide agent-access`

<a id="find-time" />

## Find a time that suits everyone [#find-a-time-that-suits-everyone]

See when people are busy and the free stretches you share, without copying their calendars.

1. ```sh
   gcal personal calendars busy week person:ana@example.com
   ```

   asks Google when Ana and your calendars are taken this week; nothing is stored

2. ```sh
   gcal personal calendars busy week person:ana@example.com --duration-minutes 30 --hours 10:00-16:00
   ```

   the free half-hours you share inside working hours

3. ```sh
   gcal personal events create 1 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T10:30 --attendee ana@example.com --no-notify
   ```

   adds the event; with --no-notify Google mails nobody

What to look at:

- free stretches fall inside --hours, Monday to Friday, in your time zone; the default is 09:00-17:00
- events create needs a sign-in with --grant write

Busy times come from Google's free/busy answer, which says when, never what.

In the terminal: `gcal guide find-time`

## Copy chosen calendars and make them searchable [#copy-chosen-calendars-and-make-them-searchable]

Sign in once, choose the calendars to keep, and get their events into the local store, searchable offline.

1. ```sh
   gcal personal session start --client-file ~/client_secret.json
   ```

   signs in to Google in the browser, read-only; personal is the profile, any name you choose, and starts every account command

2. ```sh
   gcal personal calendars list
   ```

   every calendar the account can see, each with the number to choose it by

3. ```sh
   gcal personal calendars sync 1
   ```

   only the calendars you choose are copied

4. ```sh
   gcal personal sync
   ```

   copies their events; a later run copies only what changed

5. ```sh
   gcal personal status
   ```

   how far each calendar's copy is, and when it last moved

What to look at:

- a calendar whose sync is partial; run sync again until it is complete
- gcal personal search "planning" finds events offline once they are copied

Nothing leaves the computer except the Google requests the sync makes; search and reading run offline.

In the terminal: `gcal guide set-up`