caldav-cli

A CalDAV CLI client. Manages multiple accounts with secure OS keychain storage. Supports iCloud, Google (OAuth2), Yandex 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

Provider	Auth	Server URL
Apple iCloud	Basic (app-specific password)	https://caldav.icloud.com
Google Calendar	OAuth2 (Client ID + Secret)	https://apidata.googleusercontent.com/caldav/v2
Yandex Calendar	Basic (app password)	https://caldav.yandex.ru
Custom	Basic	User provides URL

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, OAuth2 refresh tokens, and OAuth2 client credentials (Client ID, Client Secret, Token URL): 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 (file permissions 0600).

No secrets are stored on disk. Existing installations that stored OAuth2 client credentials in config.json are automatically migrated to the keychain on first run.

Flag Reference

events list

Flag	Short	Description	Default
--account <name>	-a	Account name	default account
--from <date>		Start date (YYYY-MM-DD)	today
--to <date>		End date (YYYY-MM-DD)	today + 7 days
--calendar <name>	-c	Filter by calendar name	all calendars
--json		Output as JSON	false

events create

Flag	Short	Description
--title <title>	-t	Event title
--start <datetime>	-s	Start (YYYY-MM-DDTHH:mm)
--end <datetime>	-e	End (YYYY-MM-DDTHH:mm)
--account <name>	-a	Account name
--calendar <name>	-c	Calendar name
--description <text>	-d	Event description
--location <text>	-l	Event location
--json		Output as JSON

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