caldav-cli

A CalDAV CLI client. Manages multiple accounts with secure OS keychain storage. Supports iCloud, Google (OAuth2), Yandex, Fastmail, Nextcloud, Baikal, and any custom CalDAV server.

Installation

Requires Node.js >= 18.

npm install -g caldav-cli

After installation the caldav-cli command is available globally.

Quick Start

caldav-cli account add          # Interactive wizard: pick provider, enter credentials
caldav-cli events list          # Show events for the next 7 days
caldav-cli events create        # Interactive wizard: create a new event

Account Management

Add account (interactive wizard — prompts for provider, credentials, tests connection):

caldav-cli account add

List configured accounts:

caldav-cli account list

Remove an account:

caldav-cli account remove <name>

View Events

caldav-cli events list                           # Next 7 days (default)
caldav-cli events list --from 2026-02-10 --to 2026-02-20
caldav-cli events list -a work                   # Specific account
caldav-cli events list -c "Team Calendar"        # Filter by calendar name
caldav-cli events list -a work -c Personal --from 2026-03-01 --to 2026-03-31

JSON output (for scripting):

caldav-cli events list --json
caldav-cli events list --json --from 2026-02-10 --to 2026-02-20

Create Events

Interactive wizard (prompts for all fields):

caldav-cli events create

Non-interactive (all options via flags):

caldav-cli events create \
  --title "Team standup" \
  --start "2026-02-10T10:00" \
  --end "2026-02-10T10:30" \
  --account work \
  --calendar "Team Calendar" \
  --description "Daily sync" \
  --location "Room 42"

Partial flags (wizard prompts for the rest):

caldav-cli events create --title "Lunch" --account work

JSON output after creation:

caldav-cli events create --json --title "Event" --start "2026-02-10T10:00" --end "2026-02-10T11:00"

Supported Providers

Google Calendar Setup

Google requires OAuth2. Before running caldav-cli account add:

1. Go to https://console.cloud.google.com/
2. Create a project, enable CalDAV API
3. Create OAuth client ID (Desktop app type)
4. Note the Client ID and Client Secret

The wizard will ask for these, then open a browser for authorization. The refresh token is stored securely in the OS keychain.

Data Storage

• Passwords and OAuth2 refresh tokens: OS keychain (macOS Keychain, Linux libsecret, Windows Credential Vault) via @napi-rs/keyring. Never written to disk in plaintext.
• Account metadata (name, provider ID, username, server URL): ~/.config/caldav-cli/config.json
• OAuth2 client credentials (Client ID, Client Secret, Token URL): also stored in ~/.config/caldav-cli/config.json in plaintext. These are per-user credentials that the user creates themselves in Google Cloud Console. They are not bearer tokens and cannot access data without the refresh token (which is in the keychain).

Protect ~/.config/caldav-cli/config.json with appropriate file permissions if you store OAuth2 client credentials.

Flag Reference

events list

events create

All events create flags are optional. Omitted values trigger interactive prompts.