culvii deploy
Deploy agents and workflows to sandbox or prod.
Synopsis
culvii deploy --env <env> --workspace-slug <slug>
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-slug 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-slug | ✓ | Workspace slug shown in Culvii Console. |
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)
Changing an agent's id in code is a delete-and-recreate, not a rename. The old slug shows as DELETE CANDIDATE and the new one as CREATED - a new UUID, execution history not carried over.
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-slug payments-sandbox
# Deploy to prod with destructive changes
culvii deploy --env prod --workspace-slug payments
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-slug not provided | "--workspace-slug <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 |
| Network drops between plan and apply, or mid-request | "Error: Network or unexpected error: <message>." Since plan and apply are separate calls, a drop here doesn't leave a partial deploy - rerun culvii deploy, which recomputes a fresh plan against current state. If enough time passed that the plan token expired, apply is rejected outright and you just get a new plan on retry. | 1 |