Gcalcli

Overview

Gcalcli is an OpenClaw skill that wraps the gcalcli command line tool for Google Calendar. It provides a terminal friendly way to view calendars, search events, and manage events without opening the web UI. The skill is designed for users who want a scriptable interface to Google Calendar, including quick add parsing, agenda views, and basic CRUD operations. It also includes output modes like JSON and TSV so you can pipe results into other tools, which makes it useful for automation and reporting.

What This Skill Is Good For

This skill is a fit for daily scheduling workflows, automation in scripts or cron jobs, and integration tasks where you need calendar data in a structured format. It is often used for morning agenda checks, weekly planning, automated meeting creation, or report generation. Because gcalcli is a CLI, it is also useful in headless environments such as servers and containers where a browser UI is not available.

Requirements and Authentication

The skill relies on gcalcli, which is a Python based CLI. You can install it with tools like pip or uvx. The OpenClaw documentation provides two recommended approaches:

• Install with pip or uv and run gcalcli directly.
• Use uvx to run gcalcli without installing it globally.

Authentication is handled through Google OAuth. You must configure a Google API client, enable Google Calendar API access, and complete the OAuth flow. Once authenticated, gcalcli stores a token for future runs. That token is used for all subsequent API calls, so keep it secure and avoid sharing it in logs.

Core Commands

The gcalcli CLI is organized around several high level command groups. The OpenClaw skill mirrors these commands. Below is a structured overview with typical usage patterns.

Agenda and Views

• agenda: Lists upcoming events between a start and end date. This is the standard command for daily or weekly review. It supports date range arguments and can show event details.
• calw: Displays a week view calendar in the terminal.
• calm: Displays a month view calendar in the terminal.

These commands are designed for quick scanning rather than deep detail. They are often combined with a follow up search or event view when more detail is required.

Search and Inspection

• search: Finds events by keyword. This is useful for locating recurring meetings or events with a specific topic.
• list: Lists calendars available to the authenticated user, which helps when you need to specify a calendar by name.

Search output can be customized to include more detail, and it can be emitted in structured output formats that make automation easier.

Event Creation and Editing

• quick: Uses the Google Calendar quick add style parsing to create events from a natural language string. This is the fastest way to add events.
• add: Creates an event using explicit fields like title, start time, end time, and optional metadata such as location or description.
• edit: Updates existing events. This is useful when a time or title changes.
• delete: Removes events from a calendar.
• import: Imports events from a file, which is useful for bulk additions.

These commands allow full event lifecycle management from a CLI. Quick add is ideal for speed, while add is better when precision matters.

Reminders and Notifications

Gcalcli supports reminder commands for listing and showing reminders. This can be helpful when you want to see notifications or review upcoming reminders for a set of events.

Output Formats and Data Export

Gcalcli supports multiple output formats. The OpenClaw skill documentation highlights JSON and TSV output, which are important for downstream scripts. JSON output is useful for programmatic parsing, while TSV output is helpful for spreadsheet imports or quick filtering in shell pipelines. The custom fork referenced in the documentation adds the ability to include attachments in these outputs, which is useful for meeting notes or recording links when they are stored as attachments.

Example Workflows

A common daily workflow is to run agenda for today and tomorrow, scan the results, then search for a specific meeting if more context is required. If you need to add a meeting quickly, use quick with a natural language sentence. If you need to ensure accuracy, use add and explicitly set the event fields.

For weekly planning, use calw or calm to see the week or month layout, then add or edit events as needed. For reporting, run agenda or search with JSON output and pipe that data into a script that creates a summary. This makes it easy to integrate calendar data into dashboards or team updates.

If you run recurring automation, prefer explicit command flags so the output is predictable. For example, when exporting, choose JSON and specify a consistent time range so the resulting data is stable and easy to parse.

Data Handling and Safety

The skill uses OAuth tokens and has access to your Google Calendar data. Treat tokens as sensitive, store them securely, and avoid checking them into repositories. Because event deletion is supported, take care to confirm the target event before running delete in a script. In automation, consider logging the event ID and details before making changes.

When running in shared environments, validate that the token is tied to the correct account and calendar set. Misconfigured tokens can cause changes on unintended calendars.

Reliability and Limits

The Google Calendar API enforces quota and rate limits. If you are performing bulk operations, throttle requests and prefer batch or imported workflows. For large exports, use JSON or TSV output to reduce manual work and ensure data integrity.

Troubleshooting Tips

• If authentication fails, redo the OAuth flow and confirm API access is enabled.
• If a calendar is missing, list calendars to verify names and IDs.
• If quick add results are unexpected, use add with explicit fields.
• If output is empty, verify date ranges and check that you are reading the correct calendar.

Summary

Gcalcli provides a full CLI interface for Google Calendar through the gcalcli tool. It supports agenda views, search, event creation, editing, deletion, and import workflows. With structured outputs like JSON and TSV, it also fits well into automated pipelines. When configured with OAuth and used with careful command selection, it is a reliable way to manage and inspect calendar data from the terminal.