Hreyfill CLI + MCP

Command-line access to Frogne Taxi Hreyfill (com.frogne.infinity.hreyfill 3.8.3 / 83), not the newer is.hreyfill.app. This project is not affiliated with Hreyfill. Coverage and unfinished flows are recorded in docs/COVERAGE.md.

Install

With Bun 1.3.13 or newer:

bun add -g github:axelpaul/Hreyfill-cli
hreyfill --version
hreyfill --help

Single-file Linux, macOS and Windows binaries will be published by the release workflow when a matching version tag is pushed. There is no release yet. The CLI command is hreyfill; --version, help, doctor and MCP all use the version in package.json.

Related MCP server: MCP Google Maps

Authentication

Hreyfill uses a phone number and SMS code. Fresh SMS/Firebase onboarding and automatic refresh are not yet implemented end-to-end in this CLI. Authenticate normally in the Frogne Hreyfill app, then import your existing session privately:

hreyfill auth import --file <session.json>
hreyfill auth status
hreyfill doctor
hreyfill orders upcoming

auth import also accepts stdin. Session JSON contains accessToken and, for quotes/bookings, the associated phoneId; firebaseToken is optional context for operations that require it. Never share these values. The service expects the access token verbatim in Authorization, without adding Bearer.

doctor and auth status check local storage, not network authentication; an orders/profile read verifies service access. auth logout deletes the local session, not the server session or inherited environment variables. Login, SMS, signup, session import and logout are CLI-only, never MCP tools. Raw login/SMS adapters remain available for valid existing device/Firebase context, with --yes --allow-auth; they are not a promise of standalone login. No rejected session automatically sends an SMS or retries a write.

Public contact information and transport options need no account. Quotes, bookings and personal trip details use the imported account session.

CLI usage

JSON output is default; --json is accepted. <...> denotes a placeholder to replace, never a real identifier or location in this documentation.

hreyfill orders upcoming
hreyfill orders history --params '{"max":10}'
hreyfill orders get --params '<order-json>'
hreyfill profile get
hreyfill contacts
hreyfill transport-options
hreyfill schema get-quote
hreyfill quote --data @quote.json
hreyfill nearby --params '<coordinates-json>' --timeout 3
hreyfill live --params '<order-json>' --timeout 10
hreyfill receipt --params '<order-json>' --output receipt.pdf
hreyfill schema

<order-json> contains numeric orderId. <coordinates-json> contains numeric latitude and longitude. Google address/directions tools need your own Google Maps key and may incur charges; they never receive your Frogne session token.

Quote JSON uses quoteType: "fixedPrice", pickupTime as a UTC ISO timestamp, numPassengers, and addresses.pickup/destination. Addresses contain coord: [latitude, longitude] and appropriate street/houseNum/city/zipCode/country fields. Optional via addresses use the same coordinate order. phoneId is filled from the saved session when omitted. A quote calculates a price, does not book a taxi, and does not establish an arrival time. Addresses are not geocoded implicitly.

Writes

CLI write commands preview by default and send nothing:

hreyfill orders create --data @booking.json
hreyfill orders cancel --params '<order-json>'

Only add --yes after reviewing and explicitly authorizing that exact action. A preview is not server-side validation. Booking can have a pickup without a destination. If a write times out or returns an unexpected response, its outcome may be unknown: check current state before retrying. Requests never retry implicitly.

Four write request bodies are marked partial-model: update-attributes, delete-user, update-phone-settings, modify-payment. Their exact schemas are not fully recovered, so they accept raw JSON; do not guess fields for these workflows. Some nested references also have incomplete schema coverage. Payment enrollment still needs the provider/browser handoff, which this CLI does not implement. No real booking, cancellation or payment change was used to test this client.

Binary downloads require --output; files are private (0600) and existing files are never overwritten. WebSockets are bounded to 1–30 seconds, 100 frames and 1 MiB; they never reconnect automatically. HTTP responses are bounded to 10 MiB, redirects are refused, and errors omit private response bodies.

MCP server

{
  "mcpServers": {
    "hreyfill": {
      "command": "/absolute/path/to/hreyfill",
      "args": ["serve"]
    }
  }
}

hreyfill serve runs a stdio server. stdout contains protocol only. Read tools are enabled by default. Set HREYFILL_MCP_ENABLE_WRITES=1 to expose write tools; login/SMS remain CLI-only. Every write call must include boolean confirm: false previews, true permits execution. Missing, string or numeric confirmation is rejected. This applies to booking, cancellation, card operations and all other writes. Arguments use params and body according to hreyfill schema.

The table below mirrors a real writes-enabled tools/list. An automated test compares its names and read/write classification with mcp-catalog.json.

Configuration

Session directory: $XDG_CONFIG_HOME/hreyfill-cli/, default ~/.config/hreyfill-cli/. Directory permissions are 0700 and auth.json is 0600. HREYFILL_CONFIG_DIR overrides that location. Older local prototypes used ~/.config/hreyfill; import that session or set the override to continue using it. Neither credentials nor captured service responses belong in this repository.

• HREYFILL_CONFIG_DIR — Override the session directory (default $XDG_CONFIG_HOME/hreyfill-cli or ~/.config/hreyfill-cli)

• HREYFILL_ACCESS_TOKEN — Use an existing Frogne session token instead of the stored session

• HREYFILL_PHONE_ID — Device identity for the imported session; needed for quote and booking requests

• HREYFILL_FIREBASE_TOKEN — Existing Firebase context for requests that require it; no automatic refresh

• HREYFILL_GOOGLE_API_KEY — Your own Google Maps key for optional address and directions tools; may incur charges

• HREYFILL_MCP_ENABLE_WRITES — Set to 1 to expose MCP write tools; each call still requires explicit confirmation. Login stays CLI-only.

• XDG_CONFIG_HOME — Base configuration directory (default ~/.config)

Development

git clone https://github.com/axelpaul/Hreyfill-cli.git
cd Hreyfill-cli
bun install --frozen-lockfile
bun run check
bun run build
bun run verify:mcp

check runs TypeScript plus offline tests, including a real stdio tools/list comparison and validation against the vendored site schema (draft 2020-12). No Hreyfill account or live booking/payment request is used by the test suite. All fixtures are synthetic placeholders, not captured customer data.

bun run verify:source-install tests a real GitHub global install in temporary isolated Bun directories, checks the installed version and MCP tool list, then uninstalls it without touching your existing global installation.

The release and site-notification workflows are copied from the site templates. A version tag must match package.json. The optional SITE_DISPATCH_TOKEN secret enables immediate catalogue notification; without it, hourly discovery uses the mcp-axelpaul repository topic. No tag is created by check or build.

License: MIT, Axel Paul Gunnarsson.