Modes

smoke_test and dry_run have the same execution boundary; the distinct mode label is retained in the run record. Both spend 0 credits, skip paid provider calls, and prevent external writes. OXYGEN internal reads still execute against current workspace data. One explicit exception to “no external calls” is the internal oxygen.http_json_request read tool, which may make a real outbound GET to the configured URL. Only live may spend credits, call paid providers, or write externally.

Workflow runs

--mode is required on workflows call and workflows events emit; all three values are accepted. Only workflows call --preview, which runs nothing, takes no mode. A live call additionally requires both --approved and --max-credits — unconditionally, whether or not the graph spends anything. Omitting them fails with approval_required (409) or spend_cap_required (400) and enqueues nothing.

Every successful call returns a safety receipt beside the run. It states the mode, maximum managed credits, provider/write posture, whether internal reads execute, and that an inspectable Workflow run record is created.

oxygen workflows call <id> --input-json '{...}' --mode smoke_test --json
oxygen workflows call <id> --input-json '{...}' --mode dry_run --json
oxygen workflows call <id> --input-json '{...}' --mode live --approved --max-credits 50 --json

Provider tool runs

tools run takes dry_run or live only — there is no smoke_test for a single tool call. Pass --mode explicitly: when it is omitted, most tools that write default to dry_run and other tools to live. The live gate depends on the tool. One that spends credits — a managed price, or the platform fee on your own key — requires --approved and --max-credits, and refuses with spend_cap_too_low when the ceiling is under the pre-call estimate. One that writes outside OXYGEN without spending requires --approved only. A free read runs live without either flag.

oxygen tools run <tool-id> --input-json '{...}' --mode dry_run --json
oxygen tools run <tool-id> --input-json '{...}' --mode live --approved --max-credits 20 --json

MCP splits the two into separate tools: oxygen_tools_run_dry and oxygen_tools_run_live.

A paid person, company, email, or phone lookup on OXYGEN's key that this workspace already ran with the exact same input in the last 30 days is answered from that result at no charge. The dry run's preview.cache says whether one exists (hit, reused_from). When it does, --mode live --approved --max-credits 0 returns it for 0 credits; if the cached result has expired by then, the call is refused and nothing is charged.

Column runs

columns run has no --mode. It takes a --dry-run flag — which returns the model tier, the credit estimate, and the prompt rendered against one real row — and paid runs then need --approved with --max-credits.

Related

• Approvals — the gate before live.
• Spend caps — the per-run credit limit.
• Runs — the resulting record.