ObjectStackPublish, Versioning & Preview
Compile metadata into an artifact, publish it as a versioned package to your Cloud catalog, optionally install it into an environment, and preview locally.
Publish, Versioning & Preview
ObjectStack treats compiled metadata as an immutable artifact. The local loop is:
objectstack.config.ts -> os compile -> dist/objectstack.json -> os package publish -> Cloud package version (optionally installed into an environment)The framework CLI owns compile and package publish. The Cloud control plane
that stores package versions, installs them into environments, and serves them to
runtime nodes lives outside this framework repo.
The legacy direct-to-environment os publish / os rollback commands (which wrote
sys_environment_revision) were removed (#2237). Publishing now goes through the
package catalog: os package publish uploads a versioned package, and an
environment is updated by installing a version into it. Revision-style rollback
is no longer a framework CLI command — version and environment management are a
Cloud control-plane concern.
1. Compile
os compile
# -> dist/objectstack.jsonThe artifact contains metadata, manifest requirements, and packaged function code. Deployment config stays outside the artifact: database URLs, secrets, runtime credentials, and environment identity are host inputs.
2. Publish a package version
# upload dist/objectstack.json as a new version in your org catalog
os package publish
# explicit artifact + install into an environment in one step
os package publish ./dist/objectstack.json --env env_prod --installThe CLI:
POST /api/v1/cloud/packages— ensure asys_packagerow exists (id derived fromartifact.manifest.id, or--manifest-id).POST /api/v1/cloud/packages/:id/versions— snapshotdist/objectstack.jsonintosys_package_version.manifest_json(statuspublished).- (optional) install the new version into
--env.
Common flags:
| Flag | Env var | Purpose |
|---|---|---|
artifact (positional) | — | Path to the compiled artifact (default dist/objectstack.json) |
--server, -s | OS_CLOUD_URL | Cloud control-plane URL |
--token, -t | OS_CLOUD_API_KEY | Bearer token (service mode) |
--version, -v | — | Semver version (default: artifact.manifest.version) |
--visibility | — | org (default) · private · marketplace |
--org | OS_ORG_ID | Owner org id (service mode) |
--env | OS_ENVIRONMENT_ID | Environment to install the new version into |
--install | — | Auto-install the new version into --env after publishing |
In user mode the package is owned by your active organization; in service mode
(bearer key) pass --org. See Packages for the package model.
3. Install / update an environment
An environment is updated by installing a package version into it — either at
publish time with --env --install, or separately via the Cloud control plane /
Marketplace. To "roll back," install the prior version; there is no
revision-activate CLI command anymore.
4. Preview patterns
Use one of these shapes:
| Pattern | Command |
|---|---|
| Local artifact preview | os dev --artifact ./dist/objectstack.json --ui |
| Production artifact host | OS_ARTIFACT_PATH=./dist/objectstack.json os start |
| Cloud environment preview | Install to a preview environment, then route clients to it via /api/v1/environments/:environmentId/... or X-Environment-Id. |