Modes
Every paid or external action runs in `smoke_test`, `dry_run`, or `live`.
A mode is the execution semantic for a workflow run, column run, or provider tool call. Three values.
The three modes
| Mode | Validates inputs | Reads real data | Calls paid providers | Writes externally |
|---|---|---|---|---|
smoke_test | Yes | No | No | No |
dry_run | Yes | Yes | No | No |
live | Yes | Yes | Yes | Yes |
Only live can consume credits or touch the outside world. Live work that spends credits or writes externally requires explicit scope and a credit ceiling.
When to use each
| Mode | Use for |
|---|---|
smoke_test | Authoring a workflow or template; validates shape without touching anything |
dry_run | Confirming what would happen against real rows before paying for it |
live | Real execution |
Setting mode
CLI flag on any runnable command:
oxygen workflows call <id> --input-json '{...}' --mode dry_run --json
oxygen workflows call <id> --input-json '{...}' --mode live --json
oxygen tools run <tool-id> --input-json '{...}' --mode dry_run --json
oxygen tools run <tool-id> --input-json '{...}' --mode live --jsonMCP exposes both explicit names:
oxygen_tools_run_dry
oxygen_tools_run_liveMode + approval
| Mode | Approval required |
|---|---|
smoke_test | No |
dry_run | No |
live (touches paid providers or external systems) | Yes |
live (read-only) | No |
A live run that doesn't consume credits and doesn't write externally — e.g. a workflow that only reads from tenant tables — bypasses the approval gate.
Spend caps on live
Live table, enrichment, company enrichment, and workflow-template runs against paid providers require a credit ceiling such as --max-credits 50. If the run reaches the ceiling, it pauses or stops before exceeding the approved scope. See Spend caps.
Related
- Approvals — the gate before
live. - Spend caps — the per-run credit limit.
- Runs — the resulting record.