### Install via Install Script

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Installs ical by downloading and executing a script. This method installs the latest release binary to /usr/local/bin.

```bash
curl -fsSL https://ical.sidv.dev/install | bash
```

--------------------------------

### Install via Homebrew

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Installs ical using Homebrew by tapping the repository and then installing the package.

```bash
brew tap BRO3886/tap && brew install ical
```

--------------------------------

### Preview Ical Skill Installation

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Use the `--dry-run` flag to preview the files that will be written during the Ical skill installation process without actually installing them.

```bash
# Preview the files that would be written
ical skills install --dry-run
```

--------------------------------

### Install ical with Homebrew

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Recommended installation method using Homebrew. Update using `brew upgrade ical`.

```bash
brew tap BRO3886/tap
brew install ical
```

--------------------------------

### Manually Download and Install ical (Intel)

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Downloads the latest release binary for Intel Macs and installs it to `/usr/local/bin`.

```bash
curl -LO https://github.com/BRO3886/ical/releases/latest/download/ical-darwin-amd64.tar.gz
tar xzf ical-darwin-amd64.tar.gz
sudo mv ical /usr/local/bin/
```

--------------------------------

### Install AI Agent Skill (Dry Run)

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Preview the installation of the AI agent skill without writing any files to the agent's skill directory.

```bash
# Preview what would be installed (no files written)
ical skills install --dry-run
```

--------------------------------

### Install Ical Skills Interactively

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Install Ical agent skills interactively, which includes a picker for agents and a confirmation prompt before installation.

```bash
# Install (interactive picker + confirmation prompt)
ical skills install
```

--------------------------------

### Install AI Agent Skills for ical

Source: https://github.com/bro3886/ical/blob/main/README.md

Preview or install AI agent skills for various coding agents. Use `--dry-run` to preview without writing files. Interactive installation allows selecting specific agents.

```bash
# Preview what would be installed (no files written)
ical skills install --dry-run
```

```bash
# Install the skill (interactive — pick which agents, then confirm)
ical skills install
```

```bash
# Install for a specific agent
ical skills install --agent claude    # → ~/.claude/skills/ical-cli/
ical skills install --agent codex     # → ~/.codex/skills/ical-cli/
ical skills install --agent openclaw  # → ~/.openclaw/skills/ical-cli/
ical skills install --agent others    # → ~/.agents/skills/ical-cli/
ical skills install --agent all       # All agents
```

--------------------------------

### Create a calendar interactively

Source: https://github.com/bro3886/ical/blob/main/README.md

Creates a new calendar interactively, allowing you to pick the source from a dropdown menu. This is useful for guided setup.

```bash
# Create interactively (pick source from dropdown)
ical calendars create -i
```

--------------------------------

### Install for Apple Silicon Macs

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Installs ical for Apple Silicon Macs by downloading a pre-compiled binary archive and extracting it to /usr/local/bin.

```bash
curl -LO https://github.com/BRO3886/ical/releases/latest/download/ical-darwin-arm64.tar.gz
tar xzf ical-darwin-arm64.tar.gz
sudo mv ical /usr/local/bin/ical
```

--------------------------------

### Install AI Agent Skill (Interactive)

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Install the AI agent skill interactively. This command prompts the user to select target agents before confirming the installation paths.

```bash
# Interactive — pick which agents, then confirm
ical skills install
```

--------------------------------

### Manual Download and Install for Intel Macs

Source: https://github.com/bro3886/ical/blob/main/README.md

Manually downloads and installs the ical binary for Intel Macs. Requires moving the binary to a directory in your PATH.

```bash
curl -sSL https://github.com/BRO3886/ical/releases/latest/download/ical-darwin-amd64.tar.gz | tar xzf -
sudo mv ical /usr/local/bin/
```

--------------------------------

### Install from Source with Go

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Installs ical from source using the Go toolchain. This method requires Go 1.21+ and Xcode Command Line Tools for cgo compilation.

```bash
go install github.com/BRO3886/ical/cmd/ical@latest
```

--------------------------------

### Manual Download and Install for Apple Silicon

Source: https://github.com/bro3886/ical/blob/main/README.md

Manually downloads and installs the ical binary for Apple Silicon Macs. Requires moving the binary to a directory in your PATH.

```bash
curl -sSL https://github.com/BRO3886/ical/releases/latest/download/ical-darwin-arm64.tar.gz | tar xzf -
sudo mv ical /usr/local/bin/
```

--------------------------------

### Post-Install Prompt for Agent Skill

Source: https://github.com/bro3886/ical/blob/main/docs/prd/skills-and-update-prd.md

After binary installation, this script prompts the user to install an AI agent skill for Claude Code / Codex. It delegates to `ical skills install` if the user agrees.

```bash
# After binary installation succeeds:
echo ""
echo "ical can install an AI agent skill that teaches Claude Code / Codex how to use it."
printf "Install agent skill now? [Y/n] "
read -r answer
if [ "$answer" != "n" ] && [ "$answer" != "N" ]; then
    ical skills install
fi
```

--------------------------------

### Create an Event Interactively with Guided Form

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Launches a step-by-step guided form to create a new event, filling in details like title, calendar, and times.

```bash
# Create an event interactively
ical add -i
```

--------------------------------

### Install for Intel Macs

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Installs ical for Intel Macs by downloading a pre-compiled binary archive and extracting it to /usr/local/bin. Replace 'arm64' with 'amd64' in the URL for Intel.

```bash
curl -LO https://github.com/BRO3886/ical/releases/latest/download/ical-darwin-amd64.tar.gz
tar xzf ical-darwin-amd64.tar.gz
sudo mv ical /usr/local/bin/ical
```

--------------------------------

### Configure Recurrence Rules

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Examples of creating recurrence rules and setting termination conditions using the eventkit package.

```go
// RecurrenceRule (from eventkit package)
eventkit.Daily(1)                                    // Every day
eventkit.Weekly(2, eventkit.Monday, eventkit.Friday)  // Every 2 weeks on Mon/Fri
eventkit.Monthly(1, 15)                              // Monthly on 15th
eventkit.Yearly(1)                                   // Yearly
rule.Until(time.Date(2027, 3, 15, 0, 0, 0, 0, time.Local))  // End date
rule.Count(10)                                       // End after N occurrences
```

--------------------------------

### ICAL Skills Outdated Notice

Source: https://github.com/bro3886/ical/blob/main/docs/prd/skills-and-update-prd.md

If installed skills are outdated compared to the running binary, a notice is printed to stderr, suggesting to run `ical skills install`.

```bash
A new version of ical is available: v0.4.0 → v0.5.0
Update: curl -fsSL https://ical.sidv.dev/install | bash

Installed skills are outdated (v0.4.0). Run: ical skills install
```

--------------------------------

### Install AI Agent Skills

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Install the ical agent skill for supported AI coding agents. Use `--dry-run` to preview changes or specify an agent directly with the `--agent` flag. Without `--agent`, an interactive picker is shown.

```bash
ical skills install --dry-run         # Preview files without writing
```

```bash
ical skills install                   # Interactive — pick agents + confirm
```

```bash
ical skills install --agent claude    # Direct — Claude Code only
```

```bash
ical skills install --agent codex     # Direct — Codex CLI only
```

```bash
ical skills install --agent openclaw  # Direct — OpenClaw only
```

```bash
ical skills install --agent all       # All agents
```

--------------------------------

### Install AI Agent Skill for Specific Agents

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Directly install the AI agent skill for a specified agent. The skill will be placed in the agent's designated skills directory.

```bash
# Direct
ical skills install --agent claude    # → ~/.claude/skills/ical-cli/
```

```bash
ical skills install --agent codex     # → ~/.codex/skills/ical-cli/
```

```bash
ical skills install --agent openclaw  # → ~/.openclaw/skills/ical-cli/
```

```bash
ical skills install --agent others    # → ~/.agents/skills/ical-cli/
```

```bash
ical skills install --agent all       # All agents
```

--------------------------------

### Create an Event Interactively

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Launches a guided form to create a new event, prompting for each field.

```bash
# Create interactively with a guided form
ical add -i
```

--------------------------------

### Create calendar events

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Examples of creating various types of events including recurring, all-day, and interactive events.

```bash
ical add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work

# All-day event
ical add "Company Holiday" -s 2026-03-15 --all-day -c Work

# Recurring event
ical add "Weekly Sync" -s "next monday 10am" -e "next monday 11am" \
  --repeat weekly --repeat-days mon -c Work

# With location and alerts
ical add "Dinner" -s "friday 7pm" -e "friday 9pm" \
  -l "The Restaurant, 123 Main St" --alert 1h --alert 15m

# Interactive
ical add -i
```

--------------------------------

### Add a quick event

Source: https://github.com/bro3886/ical/blob/main/README.md

Creates a simple event with a title, start time, end time, and calendar. Suitable for quickly logging appointments.

```bash
# Quick event
ical add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work
```

--------------------------------

### Basic ical CLI Commands

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/SKILL.md

Examples of common user intents and their corresponding ical CLI commands for managing calendar events and information.

```Bash
ical today
```

```Bash
ical upcoming --days 7
```

```Bash
ical list --from X --to Y
```

```Bash
ical show <row-number>
```

```Bash
ical add "title" --start X --end Y --calendar C
```

```Bash
ical update <row-number> --start X --end Y
```

```Bash
ical update <row-number> --title "new"
```

```Bash
ical update <row-number> --notes "..." --location "..."
```

```Bash
ical delete <row-number> --force
```

```Bash
ical delete <n1> <n2> <n3> --force
```

```Bash
ical search "X" --from today --to "in 30 days"
```

```Bash
ical list --from today --to "in 14 days" --attendee <name>
```

```Bash
ical upcoming --days 7 --no-recurring
```

```Bash
ical add "title" --start X --calendar C --invite a@x.com --invite "Bob <b@y.com>"
```

```Bash
ical join
```

```Bash
ical join --print
```

```Bash
ical rsvp accepted\|declined\|tentative <row-number>
```

```Bash
ical free a@x.com --from X --to Y
```

```Bash
ical inbox
```

```Bash
ical add "title" --start X --travel 30m
```

```Bash
ical calendars [create\|update\|delete]
```

```Bash
ical export --format json --output-file backup.json
```

--------------------------------

### List all calendars

Source: https://github.com/bro3886/ical/blob/main/README.md

Lists all available calendars along with their sources, types, and colors. This command provides an overview of your calendar setup.

```bash
# List all calendars (see sources, types, colors)
ical calendars
```

--------------------------------

### Install Ical Skills for Specific Agents

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Target specific AI agents for Ical skill installation using the `--agent` flag. This allows for customized integration with agents like Claude, Codex, and others.

```bash
ical skills install --agent claude    # Claude Code, Copilot, Cursor, OpenCode, Augment
```

```bash
ical skills install --agent codex     # Codex CLI, Copilot, Windsurf, OpenCode, Augment
```

```bash
ical skills install --agent openclaw  # OpenClaw
```

```bash
ical skills install --agent all       # All agents
```

--------------------------------

### Update existing events

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Examples of updating event details, clearing fields, and using interactive mode.

```bash
ical update a1b2c3d4 --title "Updated Title"
ical update a1b2c3d4 -s "tomorrow 2pm" -e "tomorrow 3pm"
ical update a1b2c3d4 --location ""     # Clear location
ical update a1b2c3d4 --span future --title "New Series Name"
ical update a1b2c3d4 -i                # Interactive
```

--------------------------------

### Create an Event with Details

Source: https://github.com/bro3886/ical/blob/main/README.md

Adds a new calendar event with a specified title, start time, end time, and calendar.

```bash
ical add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work
```

--------------------------------

### Creating an Event with Relative Start and End Times

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/date-parsing.md

Use natural language for the `-s` (start) and `-e` (end) flags to create events with relative durations.

```bash
# Create event starting in 2 hours
ical add "Quick call" -s "in 2 hours" -e "in 3 hours"
```

--------------------------------

### Create a New Event

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Adds a new event with a specified title, start time, end time, and calendar.

```bash
# Create an event
ical add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work
```

--------------------------------

### Search events

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Examples of searching for events within specific date ranges and filtering by calendar.

```bash
ical search standup                # Search +-30 days
ical search "team meeting" -c Work
ical search dentist -f "6 months ago" -t "in 6 months"
```

--------------------------------

### Pick an Event and Update Interactively

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Combines the event picker with the guided form, allowing selection of an event to edit.

```bash
# Pick an event, then edit it in a form
ical update -i
```

--------------------------------

### Manage AI Agent Skills for ical

Source: https://github.com/bro3886/ical/blob/main/README.md

Check the installation status of AI agent skills or remove them. After updating ical, run `ical skills install` to update the skill files.

```bash
# Check installation status
ical skills status
```

```bash
# Remove the skill
ical skills uninstall
```

--------------------------------

### Batch Delete Example

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Demonstrates batch deletion of multiple events using row numbers after listing them. Always use '--force' for non-interactive operations.

```bash
ical list --from today --to "next friday"   # Shows #1, #2, #3...
ical delete 1 3 5 --force                   # Delete events #1, #3, #5
```

--------------------------------

### List Events in a Date Range

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Retrieves events within a specified start and end date.

```bash
# List events in a date range
ical list -f "next monday" -t "next friday"
```

--------------------------------

### Add Events with Natural Language Dates

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Demonstrates adding two events using natural language for start and end times. The output confirms event creation.

```bash
ical add "Deep work" --start "tomorrow 9am" --end "tomorrow 10am"
ical add "1:1 Priya" --start "tomorrow 3pm" --end "tomorrow 4pm"
```

--------------------------------

### Create All-Day Event

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Create an all-day event by using the '--all-day' flag along with start date and calendar. This is suitable for holidays or full-day activities.

```bash
# All-day event
icy add "Company Holiday" -s 2026-03-15 --all-day -c Work
```

--------------------------------

### Check AI Agent Skill Status

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Show the installation status and version compatibility of the ical agent skill across different AI coding agents.

```bash
ical skills status
```

--------------------------------

### Create New Calendar Event

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Create a new calendar event with specified details. Use interactive mode with `-i` for guided prompts. `--invite` and `--travel` are not available in interactive mode.

```bash
ical add "Team standup" --start "tomorrow at 9am" --end "tomorrow at 9:30am" --calendar Work
ical add --title "Lunch" --start "today at noon" --end "today at 1pm" --location "Cafe"
ical add "Flight" --start "mar 15 at 8am" --end "mar 15 at 11am" --alert 1h --alert 1d
ical add "Weekly sync" --start "next monday at 10am" --repeat weekly --repeat-days mon
ical add -i   # Interactive mode
```

--------------------------------

### List Events by Date Range

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

List events within a specified date range using natural language for start and end dates. Optionally filter by calendar.

```bash
ical list -f "next monday" -t "next friday"
ical list -f today -t "in 7 days" -c Work
```

--------------------------------

### Display ical Version

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Prints the current version, commit hash, and build date of the ical CLI. It also indicates if a newer version is available or if installed skills are outdated.

```bash
ical version
```

--------------------------------

### Get First Event of the Day with iCal CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/SKILL.md

Extracts the title and start time of the first event of the day using `ical today` and `jq`.

```bash
# First event of the day
ical today -o json | jq -r '.[0] | ".\(.title) at \(.start_date)"'
```

--------------------------------

### Build ical from Source

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Clones the repository, navigates into the directory, and builds the binary using `make`.

```bash
git clone https://github.com/BRO3886/ical.git
cd ical
make build
```

--------------------------------

### Interactive Event Creation and Editing with ical CLI

Source: https://github.com/bro3886/ical/blob/main/README.md

Use the -i flag to launch guided forms for adding or updating events. The interactive picker can be used for selection without arguments.

```bash
# Create event interactively (guided form)
ical add -i
```

```bash
# Update event interactively (pick event, then edit fields)
ical update -i
```

```bash
# Pick an event interactively (no argument triggers a searchable picker)
ical show
ical delete
```

--------------------------------

### Update Event Start and End Times

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Adjust the start and end times for an event. The command supports natural language for dates and times.

```bash
ical update 3 --start "tomorrow at 10am" --end "tomorrow at 11am"
```

--------------------------------

### Create GitHub Release

Source: https://github.com/bro3886/ical/blob/main/CLAUDE.md

Steps to create a GitHub release, including tagging the repository and uploading release binaries. Ensure all commits are pushed before tagging.

```bash
git tag vX.Y.Z
```

```bash
git push origin vX.Y.Z
```

```bash
gh release create vX.Y.Z bin/ical-darwin-arm64.tar.gz bin/ical-darwin-amd64.tar.gz
```

--------------------------------

### Build and Test Go Project

Source: https://github.com/bro3886/ical/blob/main/CLAUDE.md

Commands for building the ical project, running unit tests, and creating release artifacts. The main build compiles EventKit via cgo.

```bash
go build -o bin/ical ./cmd/ical    # Build (compiles EventKit via cgo)
```

```bash
go test ./...
```

```bash
make build                       # Via Makefile
```

```bash
make release                     # Build arm64+amd64 tarballs for GitHub upload
```

```bash
make completions                 # bash/zsh/fish
```

--------------------------------

### Pick an Event to View

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Opens a searchable picker to select an upcoming event and view its details.

```bash
# Pick an event to view
ical show
```

--------------------------------

### Pick an Event to Update

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Opens a searchable picker to select an event for subsequent interactive updating.

```bash
# Pick an event to update
ical update
```

--------------------------------

### Delete events

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Examples of deleting events with confirmation or force flags, and handling recurring event spans.

```bash
ical delete a1b2c3d4               # With confirmation
ical delete a1b2c3d4 -f            # Force delete
ical delete a1b2c3d4 --span future # Delete this + all future occurrences
```

--------------------------------

### Reschedule Event

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Update an event's start and end times using natural language for the new schedule.

```bash
ical update 3 -s "tomorrow 2pm" -e "tomorrow 3pm"
```

--------------------------------

### Initialize Calendar Client

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Initializes the calendar client and triggers a TCC access request.

```go
client, err := calendar.New()  // Requests TCC access
```

--------------------------------

### Embed Skills Directory

Source: https://github.com/bro3886/ical/blob/main/docs/prd/skills-and-update-prd.md

Embeds the entire skills directory into the binary at build time for runtime access.

```go
//go:embed skills/cal-cli
var embeddedSkills embed.FS
```

--------------------------------

### Update a calendar interactively

Source: https://github.com/bro3886/ical/blob/main/README.md

Updates calendar properties interactively. This provides a guided way to modify calendar settings.

```bash
# Update interactively
ical calendars update -i
```

--------------------------------

### Show Event Details

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Opens an interactive event picker to select and view event details.

```bash
# Show event details (interactive picker)
ical show
```

--------------------------------

### Update an Event Interactively

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Allows interactive selection of an event to update using a guided form for editing fields.

```bash
# Update an event interactively (pick event, then edit fields)
ical update -i
```

--------------------------------

### Display ical version

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Shows the current version and build information of the ical tool.

```bash
ical version
```

```bash
# ical v0.1.0 (built 2026-02-11)
```

--------------------------------

### Client Initialization

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Initializes the calendar client and requests TCC access.

```APIDOC
## Client Initialization

### Description
Initializes the calendar client. This call triggers a request for TCC (Transparency, Consent, and Control) access on macOS.

### Method
`calendar.New()`

### Response
- **client** (Object) - The initialized calendar client instance.
- **err** (Error) - Returns an error if initialization fails (e.g., TCC denied).
```

--------------------------------

### Project Structure Overview

Source: https://github.com/bro3886/ical/blob/main/CLAUDE.md

This outlines the directory structure of the ical CLI project, detailing the purpose of each major directory and key files within the command and internal packages.

```go
ical/
├── cmd/ical/
│   ├── main.go                  # Entry point (macOS check, version)
│   └── commands/                # Cobra CLI commands (one file per command)
│       ├── root.go              # Root cmd + global flags (--output, --no-color)
│       ├── calendars.go         # Calendar CRUD (list/create/update/delete subcommands)
│       ├── list.go              # List events (date range, filters)
│       ├── show.go              # Show single event detail
│       ├── add.go               # Create event (flags + interactive -i)
│       ├── update.go            # Update event (flags + interactive -i)
│       ├── delete.go            # Delete event (confirmation + pickEvent helper)
│       ├── today.go             # Shortcut: today's events
│       ├── upcoming.go          # Shortcut: next N days
│       ├── search.go            # Search events
│       ├── join.go              # Open conference link of current/next event
│       ├── rsvp.go              # Respond to an invitation (accept/decline/tentative)
│       ├── free.go              # Free/busy availability lookup
│       ├── inbox.go             # List pending invitations
│       ├── export.go            # Export events (JSON/CSV/ICS)
│       ├── import.go            # Import events (JSON/CSV)
│       └── skills.go            # AI agent skill management (install/uninstall/status)
├── internal/
│   ├── ui/                      # Output formatting (table/json/plain)
│   │   └── output.go
│   ├── export/                  # JSON/CSV/ICS import/export
│   │   ├── json.go
│   │   ├── csv.go
│   │   └── ics.go
│   ├── skills/                  # Agent skill install/uninstall logic
│   │   └── skills.go
│   └── update/                  # Background update check (cache + GitHub API)
│       └── check.go
├── skills/ical-cli/             # Embedded agent skill (go:embed into binary)
│   ├── SKILL.md
│   └── references/
├── skills.go                    # go:embed for skills directory
├── journals/                    # Engineering journals
├── docs/
│   └── prd/                     # Product requirements
├── Makefile
├── go.mod
└── README.md
```

--------------------------------

### Get Upcoming Events

Source: https://github.com/bro3886/ical/blob/main/README.md

Displays a list of upcoming calendar events. By default, it shows events for the next 7 days.

```bash
ical upcoming
```

--------------------------------

### Create a new calendar

Source: https://github.com/bro3886/ical/blob/main/README.md

Creates a new calendar with a specified title, source, and color. Use this to organize your events.

```bash
# Create a new calendar
ical calendars create "Projects" --source iCloud --color "#FF6961"
```

--------------------------------

### Get Upcoming Events with Filters

Source: https://github.com/bro3886/ical/blob/main/README.md

Fetches upcoming events within a specified date range and excludes specific calendars from the results.

```bash
ical upcoming -d 30 --exclude-calendar Birthdays --exclude-calendar "US Holidays"
```

--------------------------------

### Manage Calendars with iCal CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/SKILL.md

Commands for listing, creating, updating, and deleting calendars. Use `create` with `--source` to link to existing calendars.

```bash
ical calendars
ical calendars create "Projects" --source iCloud --color "#FF6961"
ical calendars update "Projects" --name "Side projects"
ical calendars delete "Projects" --force
```

--------------------------------

### Get JSON Output for Scripting

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Retrieves today's events in JSON format, suitable for use in scripts. Requires `jq` for parsing.

```bash
# JSON output for scripting
ical today -o json | jq '.[].title'
```

--------------------------------

### Run iCal for the First Time

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

The first time you run iCal, macOS will prompt for calendar access. Grant permission to allow the tool to manage your events.

```bash
ical today
```

--------------------------------

### Check Availability and Join Meetings

Source: https://github.com/bro3886/ical/blob/main/README.md

Use 'free' to look up free/busy times for specified attendees within a given time range. This feature requires an Exchange or Google Workspace account; iCloud does not support it. 'join' opens the conference link for the current or next meeting.

```bash
ical free alice@example.com bob@example.com --from "monday 9am" --to "monday 6pm"
```

```bash
ical join                     # opens it in the browser
```

```bash
ical join --print             # just the URL (pipe-friendly)
```

--------------------------------

### Check ICAL Skill Status

Source: https://github.com/bro3886/ical/blob/main/docs/prd/skills-and-update-prd.md

Use `ical skills status` to see where skills are installed and if they are up to date. It checks against a `.ical-version` file in the skill directory.

```bash
$ ical skills status
ical-cli skill (v0.5.0):
  ~/.claude/skills/ical-cli/  ✓ installed (v0.5.0)
  ~/.agents/skills/ical-cli/  ✗ not installed
```

--------------------------------

### Get Plain Text Output for Grepping

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/getting-started.md

Fetches today's events in plain text format, useful for filtering with tools like `grep`.

```bash
# Plain output for grep
ical today -o plain | grep "standup"
```

--------------------------------

### Configure Shell Completions for ical

Source: https://github.com/bro3886/ical/blob/main/README.md

Set up shell completions for ical in Bash, Zsh, or Fish environments. This improves command-line usability by providing auto-completion suggestions.

```bash
# Bash
ical completion bash > /usr/local/etc/bash_completion.d/ical
```

```bash
# Zsh
ical completion zsh > "${fpath[1]}/_ical"
```

```bash
# Fish
ical completion fish > ~/.config/fish/completions/ical.fish
```

--------------------------------

### Respond to Invitations and Manage Inbox

Source: https://github.com/bro3886/ical/blob/main/README.md

The 'rsvp' command allows accepting, declining, or setting an event to tentative. Use 'inbox' to list pending invitations. Event IDs are required for specific responses, or use interactive mode.

```bash
ical rsvp accepted 3          # accept the event at row 3
```

```bash
ical rsvp declined <id>       # decline by event ID
```

```bash
ical rsvp tentative           # no event arg → interactive picker
```

```bash
ical inbox
```

--------------------------------

### Interactive Event Update

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Launch an interactive mode for updating events, which provides a guided prompt for user input. Use the -i or --interactive flag.

```bash
ical update -i
```

--------------------------------

### Create ical Calendar

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Creates a new calendar with a specified title and source. The --source flag is required. Use interactive mode for guided prompts.

```bash
# Create with flags
ical calendars create "Projects" --source iCloud --color "#FF6961"

# Interactive mode
ical calendars create -i
```

--------------------------------

### Invite People to a New Meeting with iCal CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/SKILL.md

Creates a new meeting event, invites attendees via email, and specifies travel time. Invitations are sent upon saving.

```bash
# Invite people to a new meeting (sends invitations on save)
ical add "Design review" --start "tomorrow 3pm" --calendar Work \
  --invite alice@example.com --invite "Bob <bob@example.com>" --travel 30m
```

--------------------------------

### Add Events with Invitations and Travel Time

Source: https://github.com/bro3886/ical/blob/main/README.md

Use the 'add' command to create new events, optionally inviting attendees (which sends real invitation emails) or adding travel time before the event. The organizer is automatically added.

```bash
ical add "Design review" --start "tomorrow 3pm" --calendar Work \
  --invite alice@example.com --invite "Bob <bob@example.com>"
```

```bash
ical add "Client visit" --start "friday 2pm" --travel 45m
```

--------------------------------

### Render Hugo Documentation Template

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/_default/single.html

This template uses Hugo's Go template syntax to dynamically generate navigation menus and page content.

```go
{{ define "main" }}

#### Documentation

{{ $currentURL := .RelPermalink }} {{ range .Site.Menus.main }} {{ if ne .Name "GitHub" }} [{{ .Name }}]({{ .URL }}) {{ end }} {{ end }}

{{ .Title }}
============

{{ with .Description }}

{{ . }}

{{ end }}

{{ .Content }}

{{ with .NextInSection }} [Previous {{ .Title }}]({{ .Permalink }}) {{ end }} {{ with .PrevInSection }} [Next {{ .Title }}]({{ .Permalink }}) {{ end }}

{{ end }}
```

--------------------------------

### Uninstall AI Agent Skills

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Remove the ical agent skill. Similar to installation, you can use the `--agent` flag to target specific agents or omit it for an interactive selection.

```bash
ical skills uninstall
```

```bash
ical skills uninstall --agent claude
```

--------------------------------

### Export This Week's Events to JSON

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/date-parsing.md

Use this command to export events occurring within the current week to a JSON format. Ensure the ical tool is installed and configured.

```bash
ical export -f today -t "this week" --format json
```

--------------------------------

### Add an event with location and alerts

Source: https://github.com/bro3886/ical/blob/main/README.md

Creates an event with a specified location, start/end times, and custom alerts. Note that passing `--alert` overrides calendar defaults.

```bash
# With location and alerts
# Passing any --alert gives the event exactly those alerts — the calendar's
# default alerts are not merged in. Omit --alert to inherit the default,
# or pass --no-alert for zero alerts.
ical add "Dinner" -s "friday 7pm" -e "friday 9pm" \
  -l "The Restaurant, 123 Main St" --alert 1h --alert 15m
```

--------------------------------

### List Events in JSON Format

Source: https://github.com/bro3886/ical/blob/main/website/themes/cal-docs/layouts/index.html

Lists events from today for the next 5 days, outputting the results in JSON format for machine readability. The output provides a summary of the events found.

```bash
ical list --from today --to "in 5 days" --format json
```

--------------------------------

### Update Future Occurrences of Recurring Event

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Modify future instances of a recurring event, such as changing the start time for all future occurrences. The --span option specifies 'future'.

```bash
ical update 2 --span future --start "next monday at 9am"
```

--------------------------------

### ical Project Structure Overview

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/architecture.md

Provides a hierarchical view of the ical project's directories and key files. This structure organizes the CLI commands, internal logic, and embedded agent skills.

```text
ical/
├── cmd/ical/
│   ├── main.go                  # Entry point (macOS check, version injection)
│   └── commands/                # One file per Cobra command
│       ├── root.go              # Root command + global flags (--output, --no-color)
│       ├── calendars.go         # List calendars
│       ├── list.go              # List events (date range, filters)
│       ├── show.go              # Show single event detail
│       ├── add.go               # Create event (flags + interactive -i)
│       ├── update.go            # Update event (flags + interactive -i)
│       ├── delete.go            # Delete event + pickEvent() helper
│       ├── helpers.go           # Shared helpers
│       ├── today.go             # Shortcut: today's events
│       ├── upcoming.go          # Next N days
│       ├── search.go            # Search events
│       ├── export.go            # Export events (JSON/CSV/ICS)
│       ├── import.go            # Import events (JSON/CSV)
│       └── skills.go            # AI agent skill management
├── internal/
│   ├── ui/                      # Output formatting (table/json/plain)
│   │   └── output.go
│   ├── export/                  # Import/export logic
│   │   ├── json.go
│   │   ├── csv.go
│   │   └── ics.go
│   ├── skills/                  # Agent skill install/uninstall logic
│   │   └── skills.go
│   └── update/                  # Background update check
│       └── check.go
├── skills/ical-cli/             # Embedded agent skill (baked into binary)
│   ├── SKILL.md
│   └── references/
├── skills.go                    # go:embed for skills directory
├── Makefile
└── go.mod
```

--------------------------------

### Create a New Calendar with ical CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Creates a new calendar. The title can be provided as a positional argument or using the --title flag. Use interactive mode with '-i' for guided prompts.

```bash
ical calendars create "Projects" --source iCloud --color "#FF6961"
icycal calendars create -i
```

--------------------------------

### List Calendars with ical CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Lists all available calendars. Use the '-o json' flag to output the list in JSON format.

```bash
ical calendars
ical cals
ical calendars -o json
```

--------------------------------

### Search Events with Filters

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Refine event searches using flags like `--calendar`, `--from`, and `--to` to filter by calendar, start date, and end date. Supports natural language for dates.

```bash
ical search "meeting" -c Work -f "1 month ago" -t "in 1 month"
```

--------------------------------

### List and Select Events with ical CLI

Source: https://github.com/bro3886/ical/blob/main/README.md

List events to see row numbers and event details. Select events by row number or full/partial event ID for further actions.

```bash
# List events (shows row numbers)
ical ls
#  #  TIME             TITLE          CALENDAR
#  1  10:00 - 11:00    Standup        Work
#  2  14:00 - 15:00    1:1 with Bob   Work
```

```bash
# Then reference by number
ical show 2
ical update 2 -i
ical delete 1
```

```bash
# JSON output (-o json) always includes the full event ID for scripting
```

--------------------------------

### ical completion

Source: https://github.com/bro3886/ical/blob/main/docs/prd/cal-cli-prd.md

Generates shell completion scripts for bash, zsh, and fish.

```APIDOC
## ical completion

### Description
Generates shell completion scripts.
```

--------------------------------

### Create Calendar Event with Flags

Source: https://github.com/bro3886/ical/blob/main/website/content/docs/commands.md

Use the 'ical add' command with flags to specify event details like title, start time, end time, and calendar. This is useful for scripting or quick event creation.

```bash
# With flags
icy add "Team Standup" -s "tomorrow 9am" -e "tomorrow 9:30am" -c Work

# Interactive guided form
icy add -i
```

--------------------------------

### Join Meetings with ical CLI

Source: https://github.com/bro3886/ical/blob/main/skills/ical-cli/references/commands.md

Use the 'ical join' command to open the video-conference link for the current or next meeting. It can also print the URL or join a specific event.

```bash
ical join                 # open the current/next meeting link in the browser
```

```bash
ical join --print         # print just the URL (pipe-friendly, opens nothing)
```

```bash
ical join 3               # join the event at row 3 of the last listing
```

```bash
ical join -d 1            # only look 1 day ahead
```

```bash
ical join -o json         # full event JSON instead of opening
```