calendar.vim: a Vim calendar with Google Calendar sync that now requires your own API key

Calendar navigation without leaving the editor

calendar.vim targets Vim users who do not want to switch to a browser or a separate application to check a date, browse a week or look at upcoming events. Opening inside a Vim buffer, it uses familiar Vim keys: E for the event list, T for the task list, ? for quick help, and < and > to move between views. Alignment with Vim's default key mappings is one of the design goals the README names, so the interaction model stays consistent with the rest of the editor.

Written in Vim Script, the plugin lives under 4 top-level directories: autoload/, doc/, plugin/ and syntax/. No documentation describes a minimum Vim version or specifies whether it works with Neovim. Starting with ? after first opening the plugin is the path the README points to for learning the keybindings.

The :Calendar command flags for view and layout

All interaction starts with the `:Calendar` command. Without arguments it opens the default view. Passing a year, month and day jumps directly to that date:

:Calendar 2000 1 1

The `-view` flag switches the display mode. `-view=year` shows the entire year on screen. `-view=clock` switches to a clock display. The `-first_day=monday` flag changes the start day of each week row.

Layout is controlled with split flags. Vertical and horizontal splits are both supported:

:Calendar -view=year -split=vertical -width=27
:Calendar -view=year -split=horizontal -position=below -height=12

If the frame rendering looks broken (the README shows a screenshot of the problem), adding `let g:calendar_frame = 'default'` to vimrc fixes it. The README does not list every available value for `-view` or document which combinations of split flags conflict.

wget or curl is required for Google sync, and no plugin manager command is documented

For the Google integration, 2 external tools are named as hard requirements: wget or curl must be available on the PATH. Without either, the plugin opens a local calendar view but all Google API calls will fail. The README gives no guidance on which to prefer or how to install them.

Install instructions consist of one sentence: "Install with your favorite plugin manager." No specific command is given, no Vim version floor is stated, and no list of tested plugin managers appears. Repository structure follows the standard Vim plugin layout (autoload/, plugin/, syntax/, doc/), so any GitHub-aware plugin manager should handle it.

No GitHub releases exist and the last push was on 2026-07-01, so plugin managers resolving to the master branch HEAD will pick up any change the author pushes with no version to pin.

Google Calendar now requires your own GCP project and OAuth credentials

Google Calendar and Google Tasks integration is enabled with 2 vimrc settings:

let g:calendar_google_calendar = 1
let g:calendar_google_task = 1

The README's Important Notice section states that the default client key is no longer provided and that enabling these settings without a custom key produces an Authorization Error. Every user must create their own credentials.

The setup covers several steps: create a GCP project, enable the Google Calendar API and Tasks API, configure an OAuth consent screen (choose External, add the calendar and tasks scopes), and create an OAuth client ID under Desktop application type. This produces 3 values: an API key, a client ID ending in .apps.googleusercontent.com, and a client secret. All 3 must be stored in a credentials file before Vim will authenticate.

Storing credentials in ~/.cache/calendar.vim and the vimrc source line

The README gives exact commands to create and secure the credentials file:

mkdir -p ~/.cache/calendar.vim/ && touch ~/.cache/calendar.vim/credentials.vim
chmod 700 ~/.cache/calendar.vim && chmod 600 ~/.cache/calendar.vim/credentials.vim

The 3 credential values go into that file as vimrc-style let statements:

let g:calendar_google_api_key = '...'
let g:calendar_google_client_id = '....apps.googleusercontent.com'
let g:calendar_google_client_secret = '...'

Finally, the file must be sourced from vimrc with `source ~/.cache/calendar.vim/credentials.vim`. The README's note says to keep this file securely, and the Terms of Use section warns specifically against sharing the cache directory with any cloud storage software, because the directory also holds downloaded event and task data. A synced cache could expose Google Calendar events to anyone with access to the sync target.

Why the README says DO NOT use this plugin for important events

calendar.vim's Terms of Use section contains an explicit warning easy to miss on a first read: "DO NOT use this software with important events and tasks." That sentence is the developer's own, not a boilerplate disclaimer. Below it, 3 specific failure scenarios are named: leakage of trade secrets through cache files, loss of important events and tasks due to bugs, and absence from important meetings due to software failures.

Upload behavior gets its own warning too. Events and tasks are uploaded to Google APIs over HTTPS, but the terms note that if wget or curl are replaced with malicious software, events could be sent to other servers. No integrity check on those binaries is mentioned.

For casual date-checking with non-sensitive calendar data, the disclaimer is background context. For anyone managing work deadlines or meetings where absence has consequences, the terms are a direct instruction not to rely on this plugin for that purpose.

What calendar.vim does not handle compared to a dedicated app

calendar.vim opens a view inside Vim and does not run in the background. Features central to scheduling are absent from the documentation: no notifications, no reminders, no documented recurring event support, and no conflict detection. Checking a date or browsing the current week while editing files covers the use case; relying on it for anything with consequences does not.

Google Calendar integration requires an active OAuth session and wget or curl on the PATH. Any machine lacking those tools, or any session where tokens expire and are not refreshed, will lose access to calendar data without a helpful error message documented in the README.

A standalone terminal calendar that runs outside any editor is the natural alternative for users who want the same no-browser experience. That approach keeps the calendar available without a Vim session open, avoids OAuth setup for local date browsing, and does not depend on wget or curl. calendar.vim ties the calendar directly to the editor lifecycle, so closing Vim means losing calendar access, whereas a standalone tool does not have that constraint.

Editorial conclusion

calendar.vim works for Vim users who want to browse dates and Google Calendar events without leaving the editor, and who are willing to set up their own GCP OAuth credentials. Skip it if you need a reliable calendar for important meetings: the developer's own Terms of Use section says the plugin should not be used with important events and tasks, and warns about bugs causing absence from important meetings. Before installing, confirm that your plugin manager resolves the repository to the master branch, and check whether wget or curl are on your PATH before enabling the Google integration.

Frequently asked questions

Official sources

1. Issues
2. itchyny/calendar.vim on GitHub
3. License: MIT
4. README