Metadata

name: caldav-cli
description: Manage CalDAV calendars (iCloud, Google, Yandex) from the command line. Supports OAuth2 and Basic auth, multi-account, table/JSON output.
metadata: {"clawdbot":{"emoji":"📅","os":["linux","macos"],"requires":{"bins":["caldav-cli","node"],"configs":["~/.config/caldav-cli/config.json"],"keychain":true},"install":[{"id":"npm","kind":"shell","command":"npm install -g caldav-cli","bins":["caldav-cli"],"label":"Install caldav-cli via npm"}],"source":"https://github.com/cyberash-dev/caldav-cli"}}

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:

Go to https://console.cloud.google.com/
Create a project, enable CalDAV API
Create OAuth client ID (Desktop app type)
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.

Caldav Cli

安装技能