Google Calendar CLI Usage Guide

Use the gcallm CLI to add events to Google Calendar using natural language.

Quick Reference

Add Events

# Direct text input
gcallm "Meeting with Sarah tomorrow at 3pm"
gcallm "Lunch next Tuesday 12-1pm at Cafe Nero"
gcallm add "Team standup Mon-Fri 9:30am"

# Multiple events at once
gcallm "Team standup Mon-Fri 9:30am, Coffee with Alex Thursday 2pm"

From Files (Preferred for Automation)

# Pipe from file
cat /tmp/gcal/events.txt | gcallm
cat schedule.txt | gcallm

# Echo to stdin
echo "Doctor appointment Friday 10am" | gcallm

From Clipboard

# Uses clipboard if no stdin/args provided
gcallm

From Screenshots

# Parse latest screenshot on Desktop
gcallm -s "Add events from this screenshot"

# Parse multiple screenshots
gcallm --screenshots 2 "Add from last 2 screenshots"

Ask Questions

# General calendar questions
gcallm ask "What's on my calendar today?"
gcallm ask "When is my next meeting?"
gcallm ask "Am I free Thursday afternoon?"

List Calendars

gcallm calendars

Common Workflow

Recommended approach for scripts:

# 1. Write event details to a temp file
cat > /tmp/gcal/events.txt << 'EOF'
Meeting with Prof. Smith Monday 2pm
Coffee with Alex Tuesday 10am
Team standup Wed-Fri 9:30am
EOF

# 2. Pipe to gcallm
cat /tmp/gcal/events.txt | gcallm

Natural Language Examples

gcallm understands flexible date/time formats:

• "tomorrow at 3pm"
• "next Tuesday 12-1pm"
• "Monday through Friday at 9:30am"
• "December 15th 2pm for 2 hours"
• "Coffee with Alex 10am at Starbucks"
• "Team meeting every Monday 9am"

Configuration

# Configure model (default: claude-sonnet-4-20250514)
gcallm config --model claude-sonnet-4-20250514

# Configure custom prompt
gcallm config --prompt "Custom extraction prompt"

# Show current config
gcallm config --show

Config stored at: ~/.config/gcallm/config.json

Verification

# Verify setup
gcallm verify

Troubleshooting

"MCP server not configured" Error

Ensure the Google Calendar MCP is configured in Claude Code:

claude mcp add gcal npx @anthropic/mcp-google-calendar -s local

OAuth Issues

Re-run setup:

gcallm setup ~/path/to/oauth-keys.json

Related Commands

• /gcal:setup - Set up gcallm with OAuth credentials