---------------------------------------------------------------------- This is the API documentation for the w2m library. ---------------------------------------------------------------------- ## Exceptions Exception classes ## Functions Public functions ## Constants Module-level constants and data ---------------------------------------------------------------------- This is the CLI documentation for the package. ---------------------------------------------------------------------- ## CLI: w2m ``` ``` ### w2m new ``` ``` ---------------------------------------------------------------------- This is the User Guide documentation for the package. ---------------------------------------------------------------------- ### User guide `w2m` creates a shareable When2Meet poll through a direct request. Poll setup covers the title, dates, hours, and time zone. Participants add their availability on When2Meet. ::: {.callout-warning} ## Creates a public poll Running `w2m new` immediately creates a public When2Meet poll. ::: ## Start here - [Install w2m](01-installation.qmd) as an isolated command with `uv`. - [Create a poll](02-creating-polls.qmd) with selected dates or an inclusive date range. - [Install the Agent Skill](03-agent-skill.qmd) so a compatible coding agent can use the command correctly. ## Quick example ```bash w2m new "Committee Meeting" \ --dates 2026-09-28,2026-09-29,2026-10-01 \ --time 9am-5pm ``` The command uses your local IANA time zone by default. Supply `--timezone` to choose another zone. On success, the final line is the public When2Meet URL. ## Whole-hour times When2Meet's creation form accepts whole-hour boundaries. `w2m` rejects times such as `9:30am` before sending the request. ## Getting started ## Requirements `w2m` requires Python 3.11 or later. Install `uv` with its [official installation guide](https://docs.astral.sh/uv/getting-started/installation/). ## Install the command Clone the repository: ```bash git clone https://github.com/sdhutchins/when2meet-cli.git cd when2meet-cli ``` Install `w2m` in an isolated environment managed by `uv`: ```bash uv tool install . ``` Verify that the command is available: ```bash w2m --help w2m new --help ``` The help output begins with: ```text Usage: w2m [OPTIONS] COMMAND [ARGS]... ``` If `uv` reports that its tool directory is absent from `PATH`, run `uv tool update-shell` and open a new terminal. ## Install for development Use editable mode when changing the source code: ```bash uv tool install --editable . --force ``` An installation created with `--editable` stays connected to the repository location. Standard installation mode keeps the command available after the repository moves or is deleted. ## Remove the command ```bash uv tool uninstall when2meet-cli ``` ## Using w2m ### Creating polls ::: {.callout-warning} ## Creates a public poll Running `w2m new` immediately creates a public When2Meet poll. ::: ## Select individual dates Use a comma-separated list for selected dates, including schedules that skip weekends: ```bash w2m new "Committee Meeting" \ --dates 2026-09-23,2026-09-24,2026-09-25,2026-09-28 \ --time 9am-5pm ``` Example output follows. Each poll receives a unique URL. ```text ✓ Poll created https://www.when2meet.com/?12345678-abcde ``` Supported date forms include `2026-09-28`, `09/28/2026`, and `September 28 2026`. ## Use an inclusive range Use `--date-range START END` when every calendar day between the endpoints should be included: ```bash w2m new "Project Planning" \ --date-range 2026-09-28 2026-10-01 \ --time 09:00-17:00 ``` The range includes both endpoints, weekdays, and weekends. Use `--dates` to select exact days or skip weekends. ## Set the time zone By default, `w2m` detects the computer's local IANA time zone. Override it with an explicit zone when scheduling for another location: ```bash w2m new "Remote Meeting" \ --dates 2026-09-28,2026-10-01 \ --time 9am-5pm \ --timezone America/New_York ``` Use a full IANA identifier such as `America/Chicago`. An abbreviation such as `CST` is ambiguous. IANA zones apply daylight-saving rules for the selected dates. ## Output and errors Interactive terminals show a compact Rich success message followed by the poll URL. Redirected output contains the raw URL: ```bash poll_url=$(w2m new "Committee Meeting" \ --dates 2026-09-28,2026-09-29 \ --time 9am-5pm) ``` Before sending the request, the command checks date formats, duplicate dates, date order, whole-hour times, and time-zone names. ## Troubleshooting | Message | Fix | |---|---| | `provide either --dates or --date-range` | Add one date option. | | `use either --dates or --date-range, not both` | Remove one date option. | | `When2Meet creation supports only whole-hour times` | Use a time such as `9am` or `17:00`. | | `unknown IANA timezone` | Use a full identifier such as `America/Chicago`. | | `When2Meet request failed` | Check the network connection and try again. | ## Automation ### Agent skill The `when2meet-cli` Agent Skill teaches compatible coding agents to install and use `w2m`. It tells agents to confirm before creating a poll because poll creation changes external state. It also explains that date ranges include weekends. ## Install from a checkout Install the documentation dependencies and copy the skill into Codex: ```bash uv run --group docs great-docs skill install --agent codex ``` Great Docs can also detect other supported agents or install to a custom path. The authored skill remains in `skills/when2meet-cli/SKILL.md`. Great Docs also includes it in local documentation builds. ## Skill coverage - Installing `w2m` with `uv` - Creating polls with selected dates or inclusive ranges - Listing selected weekdays with an explicit date list - Selecting an IANA time zone - Returning the resulting When2Meet URL - Leaving participant availability for each person to enter on When2Meet