culvii deploy
Deploy agents and workbooks to sandbox or prod.
Synopsis
culvii deploy --env <env> --workspace <slug> [--allow-destroy]
Description
Evaluates all *.culvii.ts files in the current directory, computes a diff against what's currently deployed in the target workspace and environment, displays the plan, then applies it.
Both --env and --workspace are required — there is no implicit fallback to config. This is intentional: deploy is a consequential operation and the target must always be explicit.
Not for dev: use culvii dev for local iteration. culvii deploy --env dev is rejected.
Accepts an OAuth session. The plan is signed with a short-lived token; apply must follow within the token's expiry window.
Flags
| Flag | Required | Description |
|---|---|---|
--env | ✓ | Target environment: sandbox or prod. |
--workspace | ✓ | Workspace slug to deploy into. |
--allow-destroy | — | Allow destructive changes. Safety gate against accidental deletion of DELETE CANDIDATE items. |
Plan display
tenant: culvii-dev | workspace: payments-sandbox | env: sandbox
Plan for sandbox:
+ payment-processor CREATED
~ invoice-router VERSIONED (42 total, active v3: 5 executions)
- old-classifier DELETE CANDIDATE (0 total, active: 0 executions)
If a DESTROYED item looks like a rename, the CLI shows a hint:
⚠ Rename hint: culvii rename old-classifier new-classifier --resource-type agent
Draft promotion
If a draft row exists for a slug being created, deploy promotes it (flips is_draft=false on the same row) rather than inserting a new one. This preserves the UUID — execution history from your culvii dev session stays linked to the deployed agent.
Examples
# Deploy to sandbox
culvii deploy --env sandbox --workspace payments-sandbox
# Deploy to prod with destructive changes
culvii deploy --env prod --workspace payments --allow-destroy
Error behaviour
| Condition | Message | Exit |
|---|---|---|
--env dev | "Use culvii dev for local iteration" | 1 |
--env not sandbox or prod | "Environment must be sandbox or prod" | 1 |
--workspace not provided | "--workspace <slug> is required for deploy. Run culvii workspace list." | 1 |
| Workspace slug not found | "Workspace not found: <slug>" | 1 |
| Dangling secondary agent ref | "Deploy failed: agent <slug> references <ref> which is not defined." | 1 |
| Deploy lock held | "Deploy already in progress" | 1 |
| DESTROYED without --allow-destroy | "Deploy has destructive changes. Re-run with --allow-destroy to confirm." | 1 |
Related commands
culvii dev, culvii workspace list, culvii rename