Command-line interface

Deploy and manage Waystones Cloud projects from the terminal or CI with the waystones-cloud CLI.

The waystones-cloud CLI deploys and manages projects from a terminal or a CI pipeline. It needs Node.js 18 or later.

Install and authenticate

npm install -g waystones-cloud

Create a key under API → Keys and export it:

export WAYSTONES_API_KEY=wsk_...

Deploy

The CLI deploys a GeoPackage or a PostGIS database together with a Waystones model file (model.json). Export the model from the Waystones designer, or download it from an existing project with waystones-cloud model download <project-id>.

# GeoPackage with OGC API Features
waystones-cloud deploy mydata.gpkg --model model.json

# Add WMS
waystones-cloud deploy mydata.gpkg --model model.json --services oapif,qgis

# From PostGIS
waystones-cloud deploy --postgis "postgres://user:pass@host:5432/db" --name "My DB" --model model.json

The command uploads the data, creates the project, starts the deployment and streams the pipeline log until the service is ready.

Update data

waystones-cloud replace <project-id> updated.gpkg

Replaces the data and redeploys. The URL and settings stay the same.

Command reference

Command	Does
`deploy <file.gpkg> --model model.json`	Create a project and deploy it
`replace <project-id> <file.gpkg>`	Replace data and redeploy
`projects list` / `projects delete <id>`	List or delete projects
`deployments list \| stop \| start \| delete \| retry <id>`	Manage deployments
`deployments remove-service <id> --service qgis`	Remove a service
`model download <project-id>`	Download the project's `model.json`
`model update-metadata <project-id> --file meta.json`	Update service details
`api-keys create <project-id> --label "CI"`	Create a key for a private project
`api-keys list \| revoke <project-id> [key-id]`	List or revoke keys
`tiles generate <project-id> --max-zoom 14`	Generate vector tiles
`tiles status \| delete <project-id>`	Manage vector tiles
`stac generate <project-id> --partition-strategy none`	Generate a STAC catalog
`stac status \| delete <project-id>`	Manage STAC catalogs
`logs <deployment-id> [--follow]`	Stream deployment logs

Run any command with --help for all options.

In CI

Set WAYSTONES_API_KEY as a secret and run replace after your data pipeline, so the API always serves the latest build:

- run: npm install -g waystones-cloud
- run: waystones-cloud replace ${{ vars.WAYSTONES_PROJECT_ID }} out/data.gpkg
  env:
    WAYSTONES_API_KEY: ${{ secrets.WAYSTONES_API_KEY }}