Deployments

A deployment activates a published release on a fork. The CLI uses a two-step lifecycle: apply stages the release as a candidate; activate promotes it to live traffic.

What happens when you deploy

Component	On activate
Runtime	Hot-reloads rules, events, and intent handlers
Query service	Loads new compiled SQL templates
Projection worker	Applies DDL for new/changed projections
Control plane	Records deployment status and active release

In-flight intents complete under the previous release. New intents use the activated release immediately.

Prerequisites

causet login
causet context use platform my-platform
causet context use app concert-app
 
# Published release must exist
causet release list

Standard deploy (apply + activate)

Stage the release on a fork — no traffic change yet:

causet deploy apply --tag 1.0.0 --fork staging

Promote the staged candidate to active:

causet deploy activate --tag 1.0.0 --fork staging --mode FULL

Mode	Behavior
`FULL`	All traffic uses the new ruleset
`CANARY`	Split traffic on `--streams` (see below)
`DRY_RUN`	Dual-execute active vs candidate; compare output without committing candidate mutations

Validate on staging with DRY_RUN before production:

causet deploy apply    --tag 1.1.0 --fork staging
causet deploy activate --tag 1.1.0 --fork staging --mode DRY_RUN
 
# Run integration tests, then promote to FULL
causet deploy activate --tag 1.1.0 --fork staging --mode FULL

Golden path — one command

causet deploy compiles, releases, applies, and activates in a single step:

causet deploy --fork main --runtime ./concert-app/ --full

Canary on specific streams:

causet deploy --fork canary --runtime ./concert-app/ --canary --streams order_stream,user_stream

Staging → production

Deploy the same tag to each fork after validation:

# Staging
causet deploy apply    --tag 1.1.0 --fork staging
causet deploy activate --tag 1.1.0 --fork staging --mode FULL
 
# Smoke test
causet intent FOLLOW_ARTIST \
  --fork staging \
  --stream user_stream \
  --entity user-1 \
  --payload '{"user_id":"user-1","artist_id":"artist-1"}'
 
# Production — same tag, different fork
causet deploy apply    --tag 1.1.0 --fork main
causet deploy activate --tag 1.1.0 --fork main --mode FULL

Because releases are immutable, the IR tested on staging is identical to what runs on main.

Fork management

# List forks
causet fork list
 
# Create a fork (activates empty ruleset shell)
causet fork create staging --parent main
 
# Compare entity state between forks (debugging)
causet fork diff staging main --stream user_stream --entity user-1
 
# Delete an ephemeral test fork
causet fork delete test-ci-42

See Forks for isolation and naming conventions.

CI/CD example

#!/usr/bin/env bash
set -euo pipefail
 
TAG="1.2.0-${GITHUB_SHA::7}"
FORK="test-${GITHUB_RUN_ID}"
 
causet build compile --runtime ./concert-app/ --out dist/
causet release create  --input dist/ --tag "$TAG"
causet release publish --tag "$TAG"
 
causet fork create "$FORK" --parent main || true
causet deploy apply    --tag "$TAG" --fork "$FORK"
causet deploy activate --tag "$TAG" --fork "$FORK" --mode FULL
 
# run tests with forkId=$FORK
npm run test:integration -- --fork "$FORK"
 
causet fork delete "$FORK"

Rollback

Re-apply and activate a known-good tag:

causet deploy apply    --tag 1.0.0 --fork main
causet deploy activate --tag 1.0.0 --fork main --mode FULL

Instant for rules and queries — no runtime restart. Projection DDL from the rolled-forward release may remain (additive only).

After deploy checklist

# Smoke intent
causet intent CHECK_IN_TO_SHOW \
  --fork main \
  --stream user_stream \
  --entity user-1 \
  --payload '{"user_id":"user-1","show_id":"show-1","venue_id":"venue-1"}'
 
# Named query
causet query my_concert_stats \
  --fork main \
  --param user_id=user-1
 
# Runtime health
causet doctor

Manual checks:

Projection worker lag and DLQ are clean
New projection tables exist if IR added projections
Rebuild projections if derive expressions changed — Replay

Deployment status

The control plane records each apply/activate as a deployment row: PENDING → DEPLOYING → ACTIVE or FAILED. Failed activations do not change the fork’s active release.

Deploy events can trigger webhooks (deployment.created, release.published) for external CI systems.

Next steps

Releases — release create and release publish
Forks — environments and forkId
Quickstart — first app end-to-end

Releases Overview