culvii deploy
Deploy agents, workflows, and surfaces 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 (0 total, active v1: 0 executions)
- old-classifier: deletes all 1 version; active is v1
Changing an agent's id in code is a delete-and-recreate, not a rename. The old slug shows as DELETE and the new one as CREATED - a new UUID, execution history not carried over. Use culvii rename to rename an agent while preserving its UUID and execution history.
Version activation
Applying a deploy creates a new immutable version in the target workspace and activates it, while deactivating the previous active version. For workflows with already-active poll or webhook triggers, the platform automatically transfers those active triggers to the new version when the trigger step ID is preserved.
Limits
- Per-resource limit: Each individual agent, workflow, or surface definition must be under
5 MiB. - Total payload limit: The combined deploy plan payload must be under
20 MiB. - Compression: Payloads over
512 KiBare automatically gzip-compressed.
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 |
| Surface validation issues | "Deploy failed: surface <slug> has validation issues." | 1 |
| Workflow tool on secondary agent | "Deploy failed: workflow tool cannot be used on secondary agent." | 1 |
| Workflow tool target depth | "Deploy failed: workflow tool target cannot exceed 3-node depth when containing core.agent." | 1 |
| Unpinned local surface missing | "Deploy failed: unpinned local surface missing." | 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 |
| Single resource definition over 5 MiB | "Deploy failed: <type> '<slug>' definition is <size>, which exceeds the 5.00 MiB per-resource limit." | 1 |
| Deploy plan payload too large (413) | "Error: Failed to plan deploy. <reason> — Payload size: <size> across <N> definition(s) (largest: ...)." | 1 |