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 reading, `--json` for one object, and `--jsonl` for pipes.

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

openidemailprofilehttps://www.googleapis.com/auth/calendar

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

gcal auth logout Remove stored credentials

#cmd-gcal-auth-logout mutates state

$ gcal auth login

$ gcal auth logout

$ gcal auth logout --help

gcal auth refresh Refresh stored token

#cmd-gcal-auth-refresh mutates state

$ gcal auth refresh

$ gcal auth refresh --help

$ gcal auth status

gcal auth status Show auth status

#cmd-gcal-auth-status discovery safe

$ gcal auth status

$ gcal auth status --help

$ gcal auth status --view full

gcal auth whoami Show current calendar identity

#cmd-gcal-auth-whoami discovery safe

$ gcal auth whoami

$ gcal auth whoami --help

$ gcal auth whoami --json

gcal calendar Manage calendars

#cmd-gcal-calendar discovery safe

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

$ gcal capabilities --help

gcal config Inspect local configuration

#cmd-gcal-config discovery safe

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 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

--all bool Confirm batch event delete

--calendar string Optional calendar selector

--yes, -y bool Confirm destructive event delete

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

$ gcal event delete --help

$ 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 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 logout Remove stored credentials

#cmd-gcal-logout mutates state

$ gcal auth login

$ gcal logout

gcal profile Manage provider profiles

#cmd-gcal-profile discovery safe

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 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 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

calendars

List calendars Lists visible calendars.

$ gcal calendar list --limit 5

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}

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

Search events Searches events by text.

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

REF  TITLE                                                        STATUS     WHEN                                                       CALENDAR  LOCATION
e1   All Day Target eval-gcal-allday-minute-straight-sorry        confirmed  2026-06-02 to 2026-06-03 (all day)                         primary   
e2   All Day Target eval-gcal-allday-someone-chinese-space        confirmed  2026-06-02 to 2026-06-03 (all day)                         primary   
e3   All Day Target eval-gcal-allday-situation-included-june      confirmed  2026-06-02 to 2026-06-03 (all day)                         primary   
e4   Location Timezone Target eval-gcal-loc-touch-change-service  confirmed  Tue 02 Jun 10:00-10:30 SAST (UTC+02:00) (UTC 08:00-08:30)  primary   Room ervice
e5   Location Timezone Target eval-gcal-loc-street-husband-woman  confirmed  Tue 02 Jun 10:00-10:30 SAST (UTC+02:00) (UTC 08:00-08:30)  primary   Room -woman

Next steps:
- Open:      gcal event get e1
- List:      gcal event list
- Calendars: gcal calendar list
- Events:    gcal event list --{day}

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: Sat 30 May 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

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.