event

cmdhub adapter

GCal CLI
for cmdhub.

Calendars, events, freebusy, and slots from the terminal.

lock Auth: OAuth2

Quick Install cmdhub get gcal

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

catalog.json Markdown

Output

Use human output for normal reads, `--json` for scripting or complete structured fields, and `--jsonl` for upstream pipe inputs.

Auth

Google OAuth. Used for calendars, events, and availability.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `gcal schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

openidemailhttps://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/calendar.calendarlist.readonlyhttps://www.googleapis.com/auth/calendar.calendars.readonlyhttps://www.googleapis.com/auth/calendar.freebusy

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output

--jsonl bool Emit JSONL records for piping

--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl

--view string = summary View mode: summary|full

--profile string = default Config/auth profile

--config string Config path override

--quiet, -q bool Suppress non-essential diagnostics

--debug bool Enable debug diagnostics

--limit int = 50 Maximum items to emit

--page-size int = 50 Requested upstream page size

--cursor string Continuation cursor

--no-paginate bool Fetch only one page

--version, -v bool Print version information

gcal auth Manage Google Calendar authentication

#cmd-gcal-auth discovery safe

Manage the Google loopback OAuth grant used by gcal. Do not enter a normal Google account password, Google app password, API key, cookie, copied access token, OAuth client secret, or service-account key; gcal stores an OAuth access/refresh token in the shared cmdhub credential backend.

$ gcal auth --help

gcal auth login Authenticate with a Google loopback OAuth grant

#cmd-gcal-auth-login mutates state

Start Google Calendar loopback OAuth. The browser prompt must be approved with the Google account whose calendars this profile should use. Do not paste a normal Google account password, app password, API key, cookie, access token, client secret, or service-account key.

$ gcal auth login

$ gcal auth login --help

$ gcal auth status

gcal auth logout Remove the stored Google loopback OAuth grant

#cmd-gcal-auth-logout mutates state

Remove the stored Google loopback OAuth grant for the selected profile from the shared cmdhub credential backend.

$ gcal auth login

$ gcal auth logout

$ gcal auth logout --help

gcal auth refresh Refresh the stored Google loopback OAuth grant

#cmd-gcal-auth-refresh mutates state

Refresh the stored Google loopback OAuth access token using the saved refresh token.

$ gcal auth refresh

$ gcal auth refresh --help

$ gcal auth status

gcal auth status Show Google loopback OAuth grant status

#cmd-gcal-auth-status discovery safe

Show whether the selected profile has a stored Google loopback OAuth grant, whether the token is refresh-valid, and whether all required Calendar scopes are present.

$ gcal auth status

$ gcal auth status --help

$ gcal auth status --view full

gcal auth whoami Show the current Google Calendar identity

#cmd-gcal-auth-whoami discovery safe

Confirm the Google Calendar account selected by the stored Google loopback OAuth grant.

$ gcal auth whoami

$ gcal auth whoami --help

$ gcal auth whoami --json

gcal calendar Manage calendars

#cmd-gcal-calendar discovery safe

$ gcal calendar --help

gcal calendar get Get a calendar

#cmd-gcal-calendar-get discovery safe

$ gcal calendar get

$ gcal calendar get c1

$ gcal calendar get c1 c2

$ gcal calendar get primary --view full

$ gcal calendar list --jsonl | gcal calendar get

gcal calendar list List calendars

#cmd-gcal-calendar-list discovery safe

$ gcal calendar list

$ gcal calendar list --jsonl | gcal calendar get

$ gcal calendar list --view full

gcal calendar search Search calendars by summary

#cmd-gcal-calendar-search discovery safe

--query string Search text

$ gcal calendar search

$ gcal calendar search --query holidays

$ gcal calendar search --query work --view full

gcal capabilities Describe capabilities

#cmd-gcal-capabilities discovery safe

--section string Show one capability section: scopes, schemas, or commands

$ gcal capabilities --help

gcal config Inspect local configuration

#cmd-gcal-config discovery safe

$ gcal config --help

gcal config explain Explain resolved configuration

#cmd-gcal-config-explain discovery safe

$ gcal config explain --help

gcal doctor Run gcal diagnostics

#cmd-gcal-doctor discovery safe

$ gcal doctor

$ gcal doctor --help

$ gcal doctor --view full

gcal event Manage calendar events

#cmd-gcal-event discovery safe

$ gcal event --help

gcal event create Create an event

#cmd-gcal-event-create mutates state

--all-day bool All-day event

--attendee stringArray = [] Attendee email; repeatable

--calendar string = primary Calendar selector

--description string Description

--duration string Duration

--end string Event end

--location string Location

--optional-attendee stringArray = [] Optional attendee email; repeatable

--resource stringArray = [] Room/resource attendee email; repeatable

--send-updates string Guest notification policy: all, externalOnly, or none

--start string Event start

--title string Event title

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ gcal event create --calendar c1 --title "Planning" --start +1h --end +2h --location "Room 4"

$ gcal event create --help

$ gcal event create --title "Company holiday" --start 2026-05-01 --all-day

$ gcal event create --title "Project review" --start "tomorrow 14:00" --duration 45m

$ gcal event create --title "Review" --start "tomorrow 14:00" --duration 45m --attendee alex@example.com --send-updates none

gcal event delete Delete an event

#cmd-gcal-event-delete mutates state dry-run

--all bool Confirm batch event delete

--calendar string Optional calendar selector

--dry-run bool Preview event delete without deleting

--yes, -y bool Confirm destructive event delete

$ gcal event delete --all --yes e1 e2

$ gcal event delete --help

$ gcal event delete e1 --dry-run

$ gcal event delete e1 --yes

$ gcal event search --query cmdhub-human-audit --jsonl | gcal event delete --all --yes

gcal event get Get an event

#cmd-gcal-event-get discovery safe

--calendar string Optional calendar selector

$ gcal event get

$ gcal event get e1

$ gcal event get e1 --view full

$ gcal event get e1 e2

$ gcal event list --today --jsonl | gcal event get

gcal event list List events

#cmd-gcal-event-list discovery safe

List events in a time window. Relative –from and –to values such as +8h and +9h are both relative to now.

--calendar string = primary Calendar selector

--from string Start time

--to string End time

--today bool Today window

--tomorrow bool Tomorrow window

--week bool Week window

$ gcal event list

$ gcal event list --calendar c1 --from now --to +72h

$ gcal event list --from +8h --to +9h

$ gcal event list --today

$ gcal event list --week --view full

gcal event quick-add Create an event from natural text

#cmd-gcal-event-quick-add mutates state

--calendar string = primary Calendar selector

--send-updates string Guest notification policy: all, externalOnly, or none

--text string Quick-add text

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ gcal event quick-add --calendar c1 --text "Planning review today 3pm"

$ gcal event quick-add --help

$ gcal event quick-add --text "Lunch with Sam tomorrow 12pm"

gcal event search Search events

#cmd-gcal-event-search discovery safe

Search events in a time window. Relative –from and –to values such as +8h and +9h are both relative to now.

--calendar string = primary Calendar selector

--from string Start time

--query string Search query

--to string End time

$ gcal event search

$ gcal event search --query "project review" --from today --to tomorrow

$ gcal event search --query audit --jsonl | gcal event get

$ gcal event search --query dentist

$ gcal event search --query review --from +8h --to +9h

gcal event update Update an event

#cmd-gcal-event-update mutates state

--add-attendee stringArray = [] Add attendee email; repeatable

--all-day bool All-day event

--attendee stringArray = [] Compatibility alias for --add-attendee; repeatable

--calendar string Optional calendar selector

--description string Description

--duration string Duration

--end string Event end

--location string Location

--remove-attendee stringArray = [] Remove attendee email; repeatable

--send-updates string Guest notification policy: all, externalOnly, or none

--set-optional-attendee stringArray = [] Replace attendees with optional attendee email; repeatable

--set-required-attendee stringArray = [] Replace attendees with required attendee email; repeatable

--start string Event start

--title string Event title

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ gcal event search --query review --jsonl | gcal event update --location "Room 4"

$ gcal event update --help

$ gcal event update e1 --add-attendee alex@example.com --send-updates none

$ gcal event update e1 --start "tomorrow 15:00" --duration 30m

$ gcal event update e1 --title "Updated title"

gcal freebusy Inspect busy windows

#cmd-gcal-freebusy discovery safe

$ gcal freebusy --help

gcal freebusy get Get busy windows for calendars

#cmd-gcal-freebusy-get discovery safe

Get busy windows for calendars. Relative –from and –to values such as +8h and +9h are both relative to now.

--calendar stringSlice = [primary] Calendar selectors

--from string Start time

--to string End time

$ gcal freebusy get

$ gcal freebusy get --calendar c1 --from today --to tomorrow

$ gcal freebusy get --from "tomorrow 09:00" --to "tomorrow 17:00" --view full

$ gcal freebusy get --from +8h --to +9h

$ gcal freebusy get --from now --to +4h

gcal mcp Run the MCP server

#cmd-gcal-mcp discovery safe

Run a stdio Model Context Protocol server for this adapter.

The server exposes read-only resource commands by default. Mutating commands are listed only when explicitly allowed with –allow and remain gated by the command contract safety class.

--allow stringArray = [] Allow mutating command keys such as gmail.message.archive or gmail.message.label.*

--allow-dangerous bool Allow --allow wildcards to include destructive or sends_external commands

--concurrency int Maximum concurrent MCP subprocesses

--max-output int64 = 0 Maximum stdout/stderr bytes captured per MCP command

--print-config bool Print MCP tool configuration and exit

--timeout duration = 0s Per-command MCP subprocess timeout, for example 45s or 2m

$ mcp

$ mcp --print-config

gcal profile Manage provider profiles

#cmd-gcal-profile discovery safe

$ gcal profile --help

gcal profile create Create an unauthenticated provider profile

#cmd-gcal-profile-create mutates state

$ gcal profile create --help

gcal profile delete Delete a local provider profile

#cmd-gcal-profile-delete mutates state

$ gcal profile delete --help

gcal profile list List provider profiles

#cmd-gcal-profile-list discovery safe

$ gcal profile list --help

gcal profile rename Rename a local provider profile

#cmd-gcal-profile-rename discovery safe

$ gcal profile rename --help

gcal profile use Set the default provider profile

#cmd-gcal-profile-use mutates state

$ gcal profile use --help

gcal resolve Resolve a marker or short id

#cmd-gcal-resolve discovery safe

$ gcal resolve --help

$ gcal resolve c1

$ gcal resolve e1

$ gcal resolve u1

gcal schema Emit gcal schema hints

#cmd-gcal-schema discovery safe

--in bool Show input schema

--input bool Show input schema

--out bool Show output schema

$ gcal schema

$ gcal schema --help

$ gcal schema event.create

$ gcal schema event.create --input

gcal slot Find open slots

#cmd-gcal-slot discovery safe

$ gcal slot --help

gcal slot find Find open slots across calendars

#cmd-gcal-slot-find discovery safe

Find open slots across calendars. Relative –from and –to values such as +8h and +9h are both relative to now.

--calendar stringSlice = [primary] Calendar selectors

--duration string = 30m Minimum slot duration

--from string Start time

--to string End time

$ gcal slot find

$ gcal slot find --calendar c1 --from today --to tomorrow --duration 1h

$ gcal slot find --from "tomorrow 09:00" --to "tomorrow 17:00" --view full

$ gcal slot find --from +8h --to +9h --duration 30m

$ gcal slot find --from now --to +4h --duration 30m

gcal version Show gcal version information

#cmd-gcal-version discovery safe

$ gcal version --help

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check auth readiness Shows selected profile readiness and recovery guidance.

$ gcal auth status

Authenticated as kestrelphilip@gmail.com
Profile: cmdhub-ci

Next steps:
- Calendars:    gcal calendar list
- Events:       gcal event list --{day}
- Capabilities: gcal capabilities

Check current identity Returns the active calendar identity.

$ gcal auth whoami

Authenticated as kestrelphilip@gmail.com

Next steps:
- Calendars:    gcal calendar list
- Events:       gcal event list --{day}
- Capabilities: gcal capabilities

Run diagnostics Checks credential backend, auth, scopes, and provider reachability.

$ gcal doctor

gcal doctor: WARN
Account: kestrelphilip@gmail.com
Checks: credential_backend ok, credential_security warn, profiles ok, google_oauth ok, token ok, scopes ok, gcal_api ok, local_timezone ok
CHECK                STATUS  DETAIL
credential_backend   OK      using file
credential_security  WARN    credential backend stores local plaintext secrets
profiles             OK      active profile "cmdhub-ci"
google_oauth         OK      built-in Google loopback OAuth client is configured
token                OK      token expires at 2026-07-06T09:49:35Z
scopes               OK      stored Google loopback OAuth grant covers required Google Cal...
gcal_api             OK      calendar API reachable
local_timezone       OK      Local

Next steps:
- Status:       gcal auth whoami
- Capabilities: gcal capabilities

calendars

List calendars Lists visible calendars.

$ gcal calendar list --limit 5

Calendars (1 total)
REF  TITLE                    HANDLE   TIME_ZONE  STATUS             ROLE
c1   kestrelphilip@gmail.com  primary  UTC        primary, selected  owner

Next steps:
- Open:      gcal calendar get c1
- Search:    gcal calendar search --query "work"
- Calendars: gcal calendar list
- Events:    gcal event list --{day}

Inspect primary calendar Shows a single-calendar summary with refs and next steps.

$ gcal calendar get primary

c1  kestrelphilip@gmail.com
Field   Value
------  -----
Ref     c1
Type    calendar
Title   kestrelphilip@gmail.com
Status  primary, selected

Next steps:
- List:         gcal calendar list
- Events:       gcal event list --{day}
- Capabilities: gcal capabilities

events

List today's events Lists events happening today.

$ gcal event list --today --limit 5

Empty state

No event found.

Next steps:
- Search:    gcal event search --query "planning"
- Create help:    gcal event create --help
- Status:    gcal auth status
- Calendars: gcal calendar list

List events through an alias Shows canonical-command disclosure for a common list alias.

$ gcal event ls --today --limit 5

Alias: gcal event ls --{day} --limit 5 -> canonical command: gcal event list --{day} --limit 5
No event found.

Next steps:
- Search:    gcal event search --query "planning"
- Create help:    gcal event create --help
- Status:    gcal auth status
- Calendars: gcal calendar list

Search events Searches events by text.

$ gcal event search --query eval --limit 5

Empty state

No event found.

Next steps:
- List:      gcal event list
- Create help:    gcal event create --help
- Status:    gcal auth status
- Calendars: gcal calendar list

Inspect quick-add creation help Shows natural-language event creation flags including --yes compatibility.

$ gcal event quick-add --help

Create an event from natural text

Usage:
  gcal event quick-add [flags]

Examples:
gcal event quick-add --calendar c1 --text "Planning review {day} 3pm"
gcal event quick-add --help
gcal event quick-add --text "Lunch with Sam {day} 12pm"

Flags:
      --calendar string       Calendar selector (default "primary")
  -h, --help                  help for quick-add
      --send-updates string   Guest notification policy: all, externalOnly, or none
      --text string           Quick-add text
  -y, --yes                   Accepted for compatibility; this command is already non-interactive

Global Flags:
      --config string    Config path override
      --cursor string    Continuation cursor
      --debug            Enable debug diagnostics
      --json             Emit JSON machine output
      --jsonl            Emit JSONL records for piping
      --limit int        Maximum items to emit (default 50)
      --no-paginate      Fetch only one page
  -o, --output string    Compatibility output mode: json|jsonl. Prefer --json or --jsonl
      --page-size int    Requested upstream page size (default 50)
      --profile string   Config/auth profile (default "default")
  -q, --quiet            Suppress non-essential diagnostics
  -v, --version          Print version information
      --view string      View mode: summary|full (default "summary")

Inspect update JSONL help Shows event update fields and JSONL self-pipe guidance.

$ gcal event update --help

Update an event

Usage:
  gcal event update [event] [flags]

Examples:
gcal event search --query review --jsonl | gcal event update --location "Room 4"
gcal event update --help
gcal event update e1 --add-attendee alex@example.com --send-updates none
gcal event update e1 --start "{day} 15:00" --duration 30m
gcal event update e1 --title "Updated title"

Flags:
      --add-attendee stringArray            Add attendee email; repeatable
      --all-day                             All-day event
      --attendee stringArray                Compatibility alias for --add-attendee; repeatable
      --calendar string                     Optional calendar selector
      --description string                  Description
      --duration string                     Duration
      --end string                          Event end
  -h, --help                                help for update
      --location string                     Location
      --remove-attendee stringArray         Remove attendee email; repeatable
      --send-updates string                 Guest notification policy: all, externalOnly, or none
      --set-optional-attendee stringArray   Replace attendees with optional attendee email; repeatable
      --set-required-attendee stringArray   Replace attendees with required attendee email; repeatable
      --start string                        Event start
      --title string                        Event title
  -y, --yes                                 Accepted for compatibility; this command is already non-interactive

Global Flags:
      --config string    Config path override
      --cursor string    Continuation cursor
      --debug            Enable debug diagnostics
      --json             Emit JSON machine output
      --jsonl            Emit JSONL records for piping
      --limit int        Maximum items to emit (default 50)
      --no-paginate      Fetch only one page
  -o, --output string    Compatibility output mode: json|jsonl. Prefer --json or --jsonl
      --page-size int    Requested upstream page size (default 50)
      --profile string   Config/auth profile (default "default")
  -q, --quiet            Suppress non-essential diagnostics
  -v, --version          Print version information
      --view string      View mode: summary|full (default "summary")

freebusy

Inspect busy windows Shows busy windows on the primary calendar.

$ gcal freebusy get --calendar primary --from 'today 09:00' --to 'today 17:00'

description: Time zone: Local
resource: freebusy
status: free
title: Busy windows
type: freebusy
when: Mon 06 Jul 09:00-17:00 SAST (UTC+02:00) (UTC 07:00-15:00)

Next steps:
- Calendars:    gcal calendar list
- Events:       gcal event list --{day}
- Capabilities: gcal capabilities
- Check:         gcal freebusy get --calendar primary --from now --to +4h

Find open slots Finds concrete open windows from free/busy data.

$ gcal slot find --calendar primary --from 'today 09:00' --to 'today 17:00' --duration 30m

Slots (1 total)
WHEN                                                       DURATION_MINS  CALENDAR
Mon 06 Jul 09:00-17:00 SAST (UTC+02:00) (UTC 07:00-15:00)  480            primary

Next steps:
- Calendars:    gcal calendar list
- Events:       gcal event list --{day}
- Capabilities: gcal capabilities
- Find:         gcal slot find --calendar primary --from now --to +4h --duration 30m

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

# Turn a transformed email into a calendar event
gmail message list --label INBOX --limit 1 --jsonl \
  | agent adapt --to "gcal event create"

GCal CLIfor cmdhub.

data_object Agent Contract

Output

Auth

Refs

Schemas

Auth scopes

terminal Command Reference

Global Flags

play_circle Live Examples

auth

calendars

events

freebusy

alt_route Composition Patterns

GCal CLI
for cmdhub.