pp-cal-com

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/cal-com/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Cal.com — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `cal-com-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install cal-com --cli-only
   ```
2. Verify: `cal-com-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/cal-com/cmd/cal-com-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for cal-com-pp-cli whenever an agent needs to read or mutate a Cal.com calendar without burning context on the multi-call dance the API requires for booking and rescheduling. The local store makes 'what's on my calendar', 'when am I free', 'who is overloaded', and 'where are my conflicts' near-instant offline answers. The composed `book` and `reschedule next` commands are the right tools for transactional bookings; the endpoint-mirror coverage is there for everything else.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Composed booking flows
- **`book`** — Schedule an attendee onto one of your event types in a single composed call — slot check, optional reservation, create, optional confirm.

  _For the host scripting an attendee onto their calendar (admin onboarding, recruiter pre-fill, test fixtures). For the normal flow where the attendee picks their own time, share a URL from `link list` instead._

  ```bash
  cal-com-pp-cli book --event-type-id 96531 --start 2026-05-06T17:00:00Z --attendee-name Guest --attendee-email [email protected] --dry-run
  ```
- **`slots find`** — Find first available slots across multiple event-type IDs in one call, ranked by start time.

  _Use this when you don't know which event type fits — let the caller pick from a ranked merged list._

  ```bash
  cal-com-pp-cli slots find --event-type-ids 96531 --start tomorrow --end "tomorrow 23:59" --json
  ```
- **`reschedule next`** — Move an existing booking to the next available slot for the same event type, after a cutoff.

  _Use this for last-minute bumps — one command instead of three, with dry-run safety._

  ```bash
  cal-com-pp-cli reschedule next --uid <booking-uid> --after tomorrow --dry-run
  ```

### Local state that compounds
- **`agenda`** — Upcoming bookings in a window — today, this week, or any duration — read from the local store.

  _Use this whenever an agent needs 'what's on my calendar'; single command across any time window._

  ```bash
  cal-com-pp-cli agenda --window today --json --select id,start,title,attendees
  ```
- **`analytics no-show`** — No-show, cancellation, volume, and density metrics over a window. Sister subcommands under analytics: bookings (volume), cancellations, no-show, density. --by accepts event-type, attendee, or weekday on the rate commands; analytics density --unit hour adds hourly heatmaps.

  _Use this for capacity planning, no-show trend analysis, or attendee follow-up — answers no single API call provides._

  ```bash
  cal-com-pp-cli analytics no-show --window 90d --by attendee --json
  ```
- **`conflicts`** — Detects overlapping bookings within a time window — pairs whose time ranges intersect get reported. Reads the local store, no API call.

  _Run before sending confirmations or after a bulk reschedule — surfaces double-bookings the API silently allows._

  ```bash
  cal-com-pp-cli conflicts --window 7d --json
  ```
- **`gaps`** — Finds open windows in your schedule that are available but unbooked, filtered by minimum block size.

  _Use this for capacity planning — answers 'when can I take a meeting' rather than 'what's on my plate'._

  ```bash
  cal-com-pp-cli gaps --window 7d --min-minutes 60 --json
  ```
- **`workload`** — Booking distribution across team members over a window — surfaces overloaded vs underutilized hosts.

  _Use this for round-robin tuning or to spot host burnout before it shows up as no-shows._

  ```bash
  cal-com-pp-cli workload --team-id 42 --window 30d --json
  ```
- **`event-types stale`** — Event types with zero bookings in the last N days — candidates for removal.

  _Use this for quarterly cleanup — keeps your bookable surface from drifting._

  ```bash
  cal-com-pp-cli event-types stale --days 90 --json
  ```

### Host control surface
- **`link create`** — Create a new bookable link (event type) on your Cal.com account; prints the cal.com/<your-username>/<slug> URL ready to share.

  _The host's primary creative act. Bookable links are how attendees book time; this is the command to make one._

  ```bash
  cal-com-pp-cli link create --slug 30min --length 30 --title "30 Min Meeting"
  ```
- **`link list`** — List every bookable link you own with the full URL pre-rendered for copy-share.

  _Use this to see what links you have and grab their URLs without hand-composing cal.com/<user>/<slug>._

  ```bash
  cal-com-pp-cli link list --json
  ```
- **`ooo set`** — Mark yourself out-of-office for a date range so Cal.com excludes the period from slot search.

  _Going on vacation? Sick? Run this once and stop getting booked. Optional --redirect-to-user forwards bookings to a teammate (round-robin only)._

  ```bash
  cal-com-pp-cli ooo set --start 2026-05-12 --end 2026-05-18 --reason vacation --notes "Hawaii trip"
  ```
- **`ooo list`** — List your active and upcoming OOO entries.

  ```bash
  cal-com-pp-cli ooo list --json
  ```

### Agent-native plumbing
- **`webhooks coverage`** — Audits registered webhook triggers against the canonical set and reports lifecycle events with no subscriber.

  _Run this whenever you add a new automation — surfaces missed triggers like BOOKING_NO_SHOW_UPDATED before they bite._

  ```bash
  cal-com-pp-cli webhooks coverage --json
  ```

## Command Reference

**api-keys** — Manage api keys

- `cal-com-pp-cli api-keys` — Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization...

**bookings** — Manage bookings

- `cal-com-pp-cli bookings create` — POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies...
- `cal-com-pp-cli bookings get` — <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing...
- `cal-com-pp-cli bookings get-bookinguid` — `:bookingUid` can be 1. uid of a normal booking 2. uid of one of the recurring booking recurrences 3. uid of...
- `cal-com-pp-cli bookings get-by-seat-uid` — Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and...

**cal-com-auth** — Manage cal com auth

- `cal-com-pp-cli cal-com-auth` — RFC 6749-compliant token endpoint. Pass client_id in the request body (Section 2.3.1). Use grant_type...

**cal-com-auth-2** — Manage cal com auth 2

- `cal-com-pp-cli cal-com-auth-2 <clientId>` — Returns the OAuth2 client information for the given client ID

**calendars** — Manage calendars

- `cal-com-pp-cli calendars check-ics-feed