This command is planned for a future release.
culvii deploy
Promote a workbook or agent definition to the target environment.
Synopsis
culvii deploy [--env <environment>] [--workspace <slug>]
Description
Promotes a workbook or agent definition to the target environment. This is a definition promotion operation — it is entirely separate from culvii run, which triggers an execution. Do not confuse the two.
Environment is read from the active context by default and overridden with --env. Workspace is read from the workbook/agent definition file by default. Overriding workspace with the --workspace flag prints a loud warning and requires explicit confirmation.
When targeting prod, the CLI always prints the active context and prompts for [y/N] confirmation before executing.
Accepts either an OAuth session or an API key with developer scope minimum.
Flags
| Flag | Type | Description |
|---|---|---|
--env | string | Target environment: dev, sandbox, or prod. Overrides active context for this invocation only. |
--workspace | string | Workspace slug to deploy into. Overrides the workspace declared in the definition file. Prints a warning. |
Precedence
- Explicit
--env/--workspaceflags (highest priority) - Value declared in the workbook/agent definition file (workspace only)
- Active context (environment only)
- Error if neither is available
Examples
# Deploy to sandbox using workspace from definition file
culvii deploy --env sandbox
# Deploy to prod (confirmation required)
culvii deploy --env prod
# → Tenant: acme Workspace: payments Env: prod
# → Authenticated as alice@acme.com (session expires in 7h)
# → Deploying 3 actors, 1 workflow...
# → Continue? [y/N]
# Override workspace (warning shown)
culvii deploy --env sandbox --workspace payments-test
# → ⚠ Workspace override: file says 'payments', flag says 'payments-test'.
# → Continue? [y/N]
Error behaviour
| Condition | Message | Exit |
|---|---|---|
| No environment resolvable | "No environment set. Use --env or run culvii config use-context." | 1 |
| No workspace resolvable | "No workspace found. Declare it in your definition file or use --workspace." | 1 |
| Insufficient key scope | "Deploy requires a key with developer scope or higher." | 1 |
| User cancels confirmation | (exit without message) | 1 |
Related commands
culvii run, culvii dev, culvii workspace promote