w2m: When2Meet from the command line

Create a When2Meet poll from the command line and get the link immediately.

Table of contents

• Poll creation
• Install and set up
• Usage
• Agent skill
• Documentation
• When2Meet request format
• Development
• Contributing
• License
• Authors

Poll creation

w2m creates a shareable When2Meet poll through When2Meet's regular event form. Poll setup covers the title, selected dates or an inclusive date range, whole-hour time boundaries, and an optional IANA time zone. Participants add their availability on When2Meet.

Install and set up

w2m requires Python 3.11 or newer. Start with the official uv installation guide. Then clone the repository and install the command as an isolated uv tool:

git clone https://github.com/sdhutchins/when2meet-cli.git
cd when2meet-cli
uv tool install .
w2m --help

Use an editable installation while developing the project:

uv tool install --editable . --force

Usage

Important: Running w2m new immediately creates a public When2Meet poll.

Create a poll with selected or nonconsecutive dates:

w2m new "Committee Meeting" \
  --dates 2026-09-28,2026-09-29,2026-10-01 \
  --time 9am-5pm

Example output follows. Each poll receives a unique URL.

✓ Poll created
https://www.when2meet.com/?12345678-abcde

Use an inclusive range when every date between two endpoints should be in the poll:

w2m new "Committee Meeting" \
  --date-range 2026-09-28 2026-10-01 \
  --time 9am-5pm

Choose one date option for each poll. --dates uses the listed dates, while --date-range includes both endpoints, weekdays, and weekends.

On an interactive terminal, w2m prints a compact success message and the new poll URL. Redirected or piped output contains the raw URL.

w2m uses the local IANA time zone by default. Override it when needed:

w2m new "Remote Meeting" \
  --dates 09/28/2026,"October 1 2026" \
  --time 09:00-17:00 \
  --timezone America/New_York

When2Meet's creation form supports whole-hour boundaries. w2m rejects minute-level times before sending the request.

Agent skill

The Agent Skill teaches compatible coding agents how to create polls with w2m, choose between selected dates and date ranges, and list weekdays explicitly when a schedule skips weekends.

Install it into Codex from a repository checkout:

uv run --group docs great-docs skill install --agent codex

Documentation

Build the documentation site locally with Great Docs:

uv run --group docs great-docs build

Preview it locally:

uv run --group docs great-docs preview

When2Meet request format

The When2Meet home page uses a regular HTML form, so poll creation can be reproduced with a direct HTTP request.

1. Endpoint: https://www.when2meet.com/SaveNewEvent.php
2. Method: POST with application/x-www-form-urlencoded data
3. Fields: NewEventName, DateTypes, PossibleDates, NoEarlierThan, NoLaterThan, and TimeZone
4. Dates: ISO dates joined by |, for example 2026-09-28|2026-09-29|2026-10-01
5. Times: Start and end hours encoded as 24-hour integers, so 9 AM to 5 PM is sent as 9 and 17
6. Result URL: The HTTP 200 response contains a JavaScript assignment such as window.location='./?12345678-abcde'; the path is resolved against https://www.when2meet.com/

This request format comes from the current When2Meet form. A future site change may require an update to the fields or response parser.

Development

Run the test suite and build the package with uv:

uv run pytest
uv build --no-sources

Contributing

See the contribution guide for the development setup, validation commands, and pull-request process.

License

w2m is available under the MIT License.

Authors

Shaurita D. Hutchins · 📧