@stayblox/cli

Developer CLI for building and publishing Stayblox themes.

Install

npm install -g @stayblox/cli
# or, from this repo:
npm install && npm link

Requires Node 20+.

Authenticate

stayblox login                                        # production
stayblox login --api https://api.stayblox.local/api --insecure   # local development

Prompts for your platform email and password and stores an API token in ~/.config/stayblox/config.json. --insecure accepts self-signed TLS certificates and is remembered for subsequent commands.

Your user must belong to a verified partner account to use the theme commands. If you belong to several partner accounts, pass --account <id>.

Theme workflow

A theme directory must contain a theme.json manifest:

{
  "slug": "breeze",
  "name": "Breeze",
  "version": "1.0.0",
  "description": "A light, airy hotel theme."
}

From the theme directory:

stayblox theme init my-theme     # scaffold a minimal starter theme
stayblox theme validate          # server-side validation, nothing published
stayblox theme push              # publish a draft version (private until approved)
stayblox theme push --submit     # publish and submit for review in one go
stayblox theme list              # your themes
stayblox theme versions          # versions + review status for this theme
stayblox theme version 1.2.0     # one version's status, notes, and full report
stayblox theme delete 1.2.0      # delete a draft version (drafts only)
stayblox theme dev               # live development against one of your teams

Live development

stayblox theme dev syncs the theme directory to a private dev theme on one of your teams (pick with --team <slug>), prints a signed preview URL, and then watches for changes. Saving a file uploads just that file; the open preview tab reloads automatically within about a second. Dev themes are never visible to visitors and are pruned automatically after 30 days without changes — just run theme dev again to recreate one.

Only platform-supported file types are packaged (liquid, css, js, json, svg, html, txt, xml, graphql + woff/woff2/ttf/eot/png/jpg/jpeg/gif/ico/webp/mp4/webm); .git, node_modules and dotfiles are always excluded.

Releases are immutable: once a version is approved or rejected you must bump version in theme.json to push again. Draft versions can be re-pushed freely.

App workflow

App commands use an account PAT (personal access token) with the develop-apps ability, minted in the Account panel under "CLI access tokens":

stayblox login --token <account-pat>

An app directory must contain an app.toml config file. Run stayblox app init to scaffold a starter:

name = "My App"
type = "remote"
distribution = "private"
scopes = ["bookings:read", "contacts:read"]
capabilities = ["inbox"]
webhooks = ["booking.created", "booking.updated"]
webhook_url = "https://my-app.example.com/webhooks/stayblox"

# Optional: OAuth redirect URIs
[oauth]
redirect_uris = ["https://my-app.example.com/auth/callback"]

# Optional: panel injection points
[[injections]]
target = "booking_detail"

# Optional: per-install settings your app can read at runtime
[[settings_schema]]
key = "api_key"
type = "string"
label = "API key"

For public apps, set a developer-chosen slug in app.toml. For private apps, omit slug; the platform generates one on first push and the CLI writes it back to app.toml automatically.

Listing, pricing, and icon are managed in the Account panel Dashboard (public apps only) and are not part of app.toml.

Account-scoped commands

These commands operate on the account identified by the PAT and do not require --team:

stayblox app init [dir]          # scaffold a starter app.toml in dir (defaults to .)
stayblox app validate            # validate app.toml server-side, nothing published
stayblox app push                # snapshot an immutable version and release it
stayblox app push --no-release   # snapshot without releasing (stage first, release separately)
stayblox app release             # promote the latest pushed version to live
stayblox app release 3           # re-release version 3 (rollback)
stayblox app versions            # list all versions and their review status
stayblox app list                # list all apps on this account
stayblox app teams               # list teams this account can install apps on
stayblox app show                # show full details for this app

Team-scoped commands

These commands operate on a specific team install. Pass --team <slug> to identify the team:

stayblox app install --team <slug>                          # install; prints runtime token + webhook secret once
stayblox app uninstall --team <slug>                        # uninstall from the team
stayblox app installs                                       # list all team installs for this app
stayblox app token --team <slug>                            # rotate the install runtime token (printed once)
stayblox app dev --team <slug> --to <host:port>             # dev install + forward webhook events to local server
stayblox app forward --team <slug> --to <host:port>         # forward webhook events to a local server
stayblox app logs --team <slug>                             # recent webhook delivery log
stayblox app replay <eventId> --team <slug> --to <host:port>  # replay a past event to a local server

Team and app are always identified by slug, never by a numeric id.

Two credentials

The account PAT is your authoring credential. It authorizes push, release, and all account-scoped calls. It never appears in your app's runtime code.

Running stayblox app install --team <slug> prints a per-install runtime token and a webhook secret, both shown once. Store them securely in your app's environment:

• Runtime token: sent as Authorization: Bearer <token> when calling the GraphQL API.
• Webhook secret: used to verify HMAC-SHA256 signatures on incoming webhook deliveries.

stayblox app token --team <slug> rotates the runtime token only. The webhook secret is issued once at app install and cannot be rotated independently; to replace it, run app uninstall then app install again.

Local webhook development

stayblox app dev --team <slug> --to <host:port> creates a dev install on the team (if one does not exist) and then forwards incoming webhook events to a local server. Dev installs behave exactly like production installs but are flagged separately in app installs.

stayblox app forward --team <slug> --to <host:port> forwards webhook events from an existing install without modifying the install.

stayblox app replay <eventId> --team <slug> --to <host:port> re-delivers a past event (visible in app logs) to a local server without waiting for the platform's retry schedule.

Each forwarded delivery is printed with its topic, event id, and the HTTP status your server returned.

Webhook events are delivered at most once per successful HTTP 2xx response. If your server returns any other status, the platform retries with exponential back-off; replay lets you force a re-delivery during development without waiting for the retry schedule.

Webhook signature verification

Every webhook delivery includes the following HTTP headers:

| Header | Description | |---|---| | X-Stayblox-Signature | HMAC-SHA256 hex digest of the payload | | X-Stayblox-Timestamp | Unix timestamp of the delivery (seconds) | | X-Stayblox-Event-Id | Unique event id; use this to deduplicate retries | | X-Stayblox-Topic | Event topic, for example booking.created | | X-Stayblox-App | App slug |

The signature covers ${timestamp}.${rawBody} and is computed with the install's webhook_secret (issued at stayblox app install --team). To verify a delivery:

1. Read X-Stayblox-Timestamp and X-Stayblox-Signature from the request headers.
2. Compute HMAC-SHA256(webhook_secret, "${timestamp}.${rawBody}") and hex-encode the result.
3. Compare your digest to X-Stayblox-Signature using a constant-time comparison.
4. Reject the request if the timestamp differs from the current time by more than 5 minutes.

Tests

npm test