caldav-cli

---

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`:

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

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.