zergbnb

An Airbnb/VRBO competitor built on two structural bets. Both change how you should use this tool, so read them before your first call.

1. Hosts cannot write guest-visible prose. Listing copy is generated from verified photo evidence, and every sentence cites the evidence it rests on. If a user asks you to "write a description" for their property, the answer is to upload better photos and run properties generate — the API will reject prose with a 422 that explains this.

2. The total price is the price. Quotes return what the guest actually pays, fees included, with cleaning folded into the nightly rate. There is no checkout-time reveal. When reporting a price to a user, report the total, not a per-night figure.

Setup

cd /Users/idanbeck/zerg-stack/zapps/zergbnb
npm run cli -- profile set prod --base-url https://zergbnb.com --token-env ZERGBNB_TOKEN

The profile stores the name of an environment variable, never a token. Export ZERGBNB_TOKEN for authenticated calls. Public commands need no credential.

Output contract

Every command prints one line of JSON to stdout:

{"ok":true,"result":{...}}

Failures print to stderr and never to stdout:

{"ok":false,"error":{"code":"NOT_FOUND","message":"HTTP 404","details":{...}}}

Branch on the exit code, not the message:

npm run cli -- help-exit-codes prints this at runtime.

Common workflows

Find a place and price it

npm run cli -- listings search --query "beach house" --city "Santa Cruz" --guests 4
npm run cli -- listings search --lat 36.9741 --lng -122.0308 --radiusKm 25 --guests 4
npm run cli -- listings get 2-bed-santa-cruz-9vrorg
npm run cli -- listings quote --slug 2-bed-santa-cruz-9vrorg \
  --checkIn 2026-09-01 --checkOut 2026-09-04 --adults 2

The quote's guestTotalCents is what the guest pays. lines is the full breakdown. There will never be a cleaning line — it is inside the nightly rate.

Book

# Take quoteId from the quote above; the price is frozen to it.
npm run cli -- reservations book --quoteId <uuid>
npm run cli -- reservations get ZB-7K3M2Q

Host a property

npm run cli -- properties create --hostAccountId <uuid> --propertyType apartment \
  --roomType entire_place --maxGuests 4 --bedrooms 2 --beds 3 --bathroomsTenths 15 \
  --city "Santa Cruz" --country US --latitude 36.9741 --longitude -122.0308
npm run cli -- properties extract-facts <propertyId>   # vision over the photos
npm run cli -- properties generate <propertyId>        # copy from that evidence

generate returns a verifierReport. If status is needs_review, the copy failed verification — read verifierReport.violations and tell the user what evidence is missing rather than offering to write the text yourself.

Understand the ranking

npm run cli -- ranking explain

Identifiers

Anywhere an id is accepted you may pass a listing slug or a reservation code (ZB-XXXXXX) instead of a UUID. Do not look up a UUID first — it costs a turn and buys nothing.

Guardrails

• Destructive actions plan by default. reservations cancel and admin set-mode print what they would do and change nothing. Show that plan to the user and only re-run with --confirm-reviewed after they agree.
• Never pass a token on the command line. Use --token-env.
• Never offer to write listing copy. The API rejects it; the fix is evidence.
• Quotes expire in 30 minutes. If a booking fails with quote_expired, get a fresh quote rather than retrying the old one.
• admin set-mode live charges real cards. It needs a typed confirmation phrase and a recent sign-in. Do not run it unless the user explicitly asks.

Escape hatch

Any route not wrapped above:

npm run cli -- api GET /api/some/route
npm run cli -- api POST /api/some/route -d key=value -d other=thing

Paths must start with / — absolute URLs are refused so a profile's credential cannot be aimed at another host.

Diagnosing

npm run cli -- doctor    # config state; never prints token values
npm run cli -- health    # liveness + database
npm run cli -- help      # the full resource catalog, machine-readable

help returns the entire catalog as JSON, so you can discover actions and their flags at runtime rather than guessing from this document.