Installation

npm install -g @joargp/accli

Requirements: macOS only (uses JavaScript for Automation)

Overview

The accli tool provides command-line access to macOS Apple Calendar. It enables listing calendars, querying events, creating/updating/deleting events, and checking availability across calendars.

Quick Reference

DateTime Formats

• Timed events: YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss
• All-day events: YYYY-MM-DD

Global Options

• --json - Output as JSON (recommended for parsing)
• --help - Show help for any command

Commands

List Calendars

accli calendars [--json]

Lists all available calendars with names and persistent IDs. Run this first to discover available calendars and their IDs.

List Events

accli events  [options]

Options:

• --calendar-id - Persistent calendar ID (recommended over name)
• --from - Start of range (default: now)
• --to - End of range (default: from + 7 days)
• --max - Maximum events to return (default: 50)
• --query - Case-insensitive filter on summary/location/description
• --json - Output JSON

Examples:

# Events from Work calendar for this week
accli events Work --json
# Events in January
accli events Work --from 2025-01-01 --to 2025-01-31 --json
# Search for specific events
accli events Work --query "standup" --max 10 --json

Get Single Event

accli event   [--json]

Retrieves details for a specific event by its ID.

Create Event

accli create  --summary  --start  --end  [options]

Required Options:

• --summary - Event title
• --start - Start time
• --end - End time

Optional:

• --location - Event location
• --description - Event description
• --all-day - Create an all-day event
• --json - Output JSON

Examples:

# Create a timed meeting
accli create Work --summary "Team Standup" --start 2025-01-15T09:00 --end 2025-01-15T09:30 --json
# Create an all-day event
accli create Personal --summary "Vacation" --start 2025-07-01 --end 2025-07-05 --all-day --json
# Create with location and description
accli create Work --summary "Client Meeting" --start 2025-01-15T14:00 --end 2025-01-15T15:00 \
  --location "Conference Room A" --description "Q1 planning discussion" --json

Update Event

accli update   [options]

Options (all optional - only provide what to change):

• --summary - New title
• --start - New start time
• --end - New end time
• --location - New location
• --description - New description
• --all-day - Convert to all-day event
• --no-all-day - Convert to timed event
• --json - Output JSON

Example:

accli update Work event-id-123 --summary "Updated Meeting Title" --start 2025-01-15T15:00 --end 2025-01-15T16:00 --json

Delete Event

accli delete   [--json]

Permanently deletes an event. Confirm with user before executing.

Check Free/Busy

accli freebusy --calendar  --from  --to  [options]

Options:

• --calendar - Calendar name (can repeat for multiple calendars)
• --calendar-id - Persistent calendar ID (can repeat)
• --from - Start of range (required)
• --to - End of range (required)
• --json - Output JSON

Shows busy time slots, excluding cancelled, declined, and transparent events.

Examples:

# Check availability across calendars
accli freebusy --calendar Work --calendar Personal --from 2025-01-15 --to 2025-01-16 --json
# Check specific hours
accli freebusy --calendar Work --from 2025-01-15T09:00 --to 2025-01-15T18:00 --json

Configuration

# Set default calendar (interactive)
accli config set-default
# Set default by name
accli config set-default --calendar Work
# Show current config
accli config show
# Clear default
accli config clear

When a default calendar is set, commands automatically use it if no calendar is specified.

Workflow Guidelines

Before Creating Events

# 1. Check availability
accli freebusy --calendar Work --from 2025-01-15T09:00 --to 2025-01-15T18:00 --json
# 2. Create event in available slot
accli create Work --summary "Meeting" --start 2025-01-15T14:00 --end 2025-01-15T15:00 --json

accli events Work --from $(date +%Y-%m-%d) --to $(date -v+1d +%Y-%m-%d) --json