---
title: Publish, Versioning & Preview
description: Compile metadata, publish it to a Cloud environment, and activate or roll back revisions.
---

# Publish, Versioning & Preview

ObjectStack treats compiled metadata as an immutable environment artifact. The
local loop is:

```text
objectstack.config.ts -> os compile -> dist/objectstack.json -> os publish -> Cloud environment revision
```

The framework CLI owns compile/publish/rollback commands. The Cloud control
plane that stores revisions and serves them to runtime nodes lives outside this
framework repo.

---

## 1. Compile

```bash
os compile
# -> dist/objectstack.json
```

The 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

```bash
OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os publish
```

Common inputs:

| Input | Env var | Purpose |
|:---|:---|:---|
| `--server`, `-s` | `OS_CLOUD_URL` | Cloud control-plane URL |
| `--environment`, `-e` | `OS_ENVIRONMENT_ID` | Target environment id |
| `--token`, `-t` | `OS_CLOUD_API_KEY` | Bearer token when required |
| `--timeout` | `OS_CLOUD_TIMEOUT_MS` | Request timeout |

The CLI posts the compiled JSON to:

```text
POST /api/v1/cloud/environments/:environment/metadata
```

The response includes the environment id, commit id, and checksum for the newly
published revision.

---

## 3. Activate or roll back

To activate a previous commit:

```bash
OS_CLOUD_URL=https://cloud.example.com \
OS_ENVIRONMENT_ID=env_prod \
os rollback --commit 9ce1bd48dd7022b8
```

The CLI calls:

```text
POST /api/v1/cloud/environments/:environment/revisions/:commit/activate
```

Runtime hosts can then refresh the environment kernel using the active
commit/checksum.

---

## 4. Package publish

Packages are separate from environment revisions:

```bash
os package publish --env env_prod
```

Package publish targets the Cloud package registry endpoints, while
`os publish` targets an environment revision.

---

## 5. Preview patterns

Use one of these shapes:

| Pattern | Command |
|:---|:---|
| Local artifact preview | `os serve --artifact ./dist/objectstack.json --dev --ui` |
| Production artifact host | `OS_ARTIFACT_PATH=./dist/objectstack.json os start` |
| Cloud environment preview | Publish to a preview environment id, then route clients to that environment via `/api/v1/environments/:environmentId/...` or `X-Environment-Id`. |

---

## Related

- [Deployment Modes](./cloud-deployment)
- [Environment-Scoped Routing](./project-scoping)
- [Cloud Environment Artifact API](../concepts/cloud-artifact-api)
