Find, watch and book Booksy appointments from the terminal.
booksy earliest barba --near Valencia --when "mon-fri 16:00-close" --when sat --format prettyDAY TIME BUSINESS DIST SERVICE PRICE BUSINESS_ID VARIANT
Tue 27 Oct 16:00 Barbería Vanellie Capelli 415m Arreglo de barba Sencillo 12,00 €+ 64989 1121918
Tue 27 Oct 16:00 Barbershop Barberia Fabián Fe… 425m Recorte de la barba 10,00 €+ 168103 2360732
...
Recorte de la barba · 15 businesses checked, 2026-10-27 to 2026-11-09 · book with: booksy book BUSINESS_ID --service VARIANT --at DATETIME
- Search businesses around any place, and read their services, staff, hours and reviews.
- Open slots for a service, filtered by your real schedule:
--when "mon-fri 16:00-close" --when sat. - The earliest slot anywhere: the same kind of service compared across nearby businesses.
- Watch for cancellations: get a phone notification (ntfy, Discord, Slack, a script) when an earlier slot opens.
- Book, reschedule and cancel from your own account, always with a summary and a confirmation first.
- Made for scripts and AI agents: JSON output, stable exit codes, machine-readable errors,
--dry-run, and a usage guide built into the binary.
One static binary for Linux, macOS and Windows. No login is needed to search, check slots or watch.
curl -fsSL https://booksy.gimeno.dev/install.sh | sh
booksy doctorWindows: download the zip from releases. With Go: go install github.com/GodGMN/booksy-cli/cmd/booksy@latest. Update later with booksy update. More in the install guide.
# find a business and the variant id of the service you want
booksy search barberia --near "Madrid" --format pretty
booksy business services 3349 --format pretty
# when could you go?
booksy slots 3349 --service "corte de pelo" --when "mon-fri 17:00-close" --when sat --format pretty
# book it (after logging in, see the docs)
booksy book 3349 --service "corte de pelo" --first --when "mon-fri 17:00-close" --dry-run --format pretty
# or get told when something earlier opens up
booksy watch add slots 3349 --service "corte de pelo" --before 2026-11-15 --notify phone
booksy watch service installOutput is JSON by default (pipe it into jq); --format pretty is for people.
Full docs: https://booksy.gimeno.dev
| guide | |
|---|---|
| Install and update | installer, Windows, booksy update, uninstall, releasing |
| Log in | importing your booksy.com login, profiles, CI |
| Find businesses and slots | search, services and variants, --when schedules, earliest |
| Book, reschedule and cancel | the booking flow, prepayments and no-show protection |
| Watch for cancellations | watches, the timer, ntfy/webhook/script notifications |
| Configuration | config keys, files, environment variables, countries |
| Scripts and AI agents | JSON contract, error envelope, the built-in agent guide |
| Troubleshooting | exit codes and common problems |
| Specification | every command, flag, file and Booksy endpoint |
- Unofficial. booksy-cli uses Booksy's customer web API, the one booksy.com and its booking widget use. It is not made or endorsed by Booksy, and Booksy can change that API at any time; the CLI then exits with code 7 and links a prefilled issue.
- Your login stays local. It is imported from your browser's cookies, checked with Booksy, and stored in a file only you can read. Nothing is sent anywhere but Booksy.
- Card numbers are never handled. For Booksy's no-show protection,
bookguarantees the fee with the card already saved on your account, as booksy.com does. Prepayments still have to be paid on booksy.com or in the app;bookstops and tells you so instead of leaving a half-made booking. - Nothing happens by surprise. Booking, rescheduling and cancelling show a summary and ask first. Without a terminal they refuse unless you pass
--yes. - Not a secret. The
X-Api-Keyin the code is booksy.com's public web-client key that every browser receives. If Booksy changes it, the CLI picks up the new one from booksy.com by itself. - Be gentle. Watches check every 15 minutes by default (2 minutes at the fastest), and
earliestqueries a few businesses at a time.
Both stop before changing anything and say why (exit 2, reason card_required).
- Prepayments. Businesses that want money up front have to be booked on booksy.com or in the app.
- Rescheduling a booking with a cancellation fee.
appointment reschedulerefuses for businesses with no-show protection. Cancel and book again instead, or move it on booksy.com.
See CONTRIBUTING.md for setup, the code layout, tests, and pull requests. AGENTS.md has the project rules and CONTEXT.md the vocabulary.
MIT. The structure, output layer and scheduler integration follow wallapop-cli and vinted-cli by Microck (MIT).