Versions and test hosts

Ship through versions

Every push is a numbered, immutable version on a branch; nothing changes what is live until you say so. Push, then look at what changed before you promote:

substrio push -m "add discount field"
substrio diff            # against the current live version

See versioning for branches, tags, merges and the full verb list.

Try on a sandbox or test host

A sandbox is a copy of your app's data that runs a version you choose, without touching what is live. Bind a host of your own to a new sandbox running the version you pushed, and try it end to end before you promote. Over MCP, call these tools in order:

[
  {"name": "substrio_env_host_set", "arguments": {"host": "my-app-v2.substrio.com", "environment": "dev", "version": 2}},
  {"name": "substrio_live_set", "arguments": {"from": "my-app-v2.substrio.com"}},
  {"name": "substrio_env_host_remove", "arguments": {"host": "my-app-v2.substrio.com"}}
]

The first call makes the sandbox dev running version 2 and binds the host to it: https://my-app-v2.substrio.com now runs version 2 on the sandbox's data, while my-app.substrio.com keeps serving the live version. See test-hosts for every host operation.

Promote

Once the test host looks right, the second call makes what it runs live, straight from the host you tested on; the third frees the host. Promote a version number instead with the CLI, or version.live.set with version in place of from:

substrio promote 2

Every promote backs your app's data up first, unless you pass --no-backup.

Roll back

substrio rollback (version.live.set with version: "previous") makes the version that was live before the last promote live again. It changes code only, not data. To put the data back as well, run substrio restore (version.restore): it restores the backup the promote took and makes the version that was live then live again. Keep each promote small, so a rollback undoes one change.

Branches and tags

Push to a named branch (substrio push --branch feature/x) to try a change apart from main; merge it in with substrio merge FROM --into NAME once it is ready. Tag a version that ships to customers (substrio tag v1.4.0) so you can always find exactly what ran, independent of later pushes to the same branch.