Minimal Google Calendar CLI for listing calendars, managing events, and checking availability.
npm install -g @mariozechner/gccliBefore adding an account, you need OAuth2 credentials from Google Cloud Console:
- Create a new project (or select existing)
- Enable the Google Calendar API
- Set app name in OAuth branding
- Add test users (all Gmail addresses you want to use with gccli)
- Create OAuth client:
- Click "Create Client"
- Application type: "Desktop app"
- Download the JSON file
Then:
gccli accounts credentials ~/path/to/credentials.json
gccli accounts add you@gmail.comgccli accounts <action> Account management
gccli <email> <command> [options] Calendar operations
gccli accounts credentials <file.json> # Set OAuth credentials (once)
gccli accounts list # List configured accounts
gccli accounts add <email> # Add account (opens browser)
gccli accounts add <email> --manual # Add account (browserless, paste redirect URL)
gccli accounts remove <email> # Remove accountList all calendars for an account.
gccli <email> calendarsReturns: ID, name, access role.
List events from a calendar.
gccli <email> events <calendarId> [options]Options:
--from <datetime>- Start time (ISO 8601, default: now)--to <datetime>- End time (ISO 8601, default: 1 week from now)--max <n>- Max results (default: 10)--page <token>- Page token for pagination--query <q>- Free text search
Examples:
gccli you@gmail.com events primary
gccli you@gmail.com events primary --from 2024-01-01T00:00:00Z --max 50
gccli you@gmail.com events primary --query "meeting"Get details for a specific event.
gccli <email> event <calendarId> <eventId>Create a new event.
gccli <email> create <calendarId> --summary <s> --start <dt> --end <dt> [options]Options:
--summary <s>- Event title (required)--start <datetime>- Start time (required, ISO 8601)--end <datetime>- End time (required, ISO 8601)--description <d>- Event description--location <l>- Event location--attendees <emails>- Attendees (comma-separated)--all-day- Create all-day event (use YYYY-MM-DD for start/end)
Examples:
gccli you@gmail.com create primary --summary "Meeting" --start 2024-01-15T10:00:00 --end 2024-01-15T11:00:00
gccli you@gmail.com create primary --summary "Vacation" --start 2024-01-20 --end 2024-01-25 --all-day
gccli you@gmail.com create primary --summary "Team Sync" --start 2024-01-15T14:00:00 --end 2024-01-15T15:00:00 --attendees a@x.com,b@x.comUpdate an existing event.
gccli <email> update <calendarId> <eventId> [options]Options: same as create (all optional).
Example:
gccli you@gmail.com update primary abc123 --summary "Updated Meeting" --location "Room 2"Delete an event.
gccli <email> delete <calendarId> <eventId>Check free/busy status for calendars.
gccli <email> freebusy <calendarIds> --from <dt> --to <dt>Calendar IDs are comma-separated.
Example:
gccli you@gmail.com freebusy primary,work@group.calendar.google.com --from 2024-01-15T00:00:00Z --to 2024-01-16T00:00:00ZList access control rules for a calendar.
gccli <email> acl <calendarId>Returns: scope type, scope value, role.
Example:
gccli you@gmail.com acl primaryAll data is stored in ~/.gccli/:
credentials.json- OAuth client credentialsaccounts.json- Account tokens
npm install
npm run build
npm run check# Update version in package.json and CHANGELOG.md
npm run build
npm publish --access public
git tag v<version>
git push --tagsMIT