Start Here

Breyta quickstart for the default flow lifecycle: draft working copy -> configure -> run.

Quick Answer

Use this sequence:

breyta docs find "flows"
breyta flows search "<problem keyword>"
# Reuse/create/test connections up front (recommended when flow uses external systems):
# breyta connections list
# breyta connections create ...
# breyta connections test <connection-id>   # health/config check only; still do a real flow run
breyta flows pull <slug> --out ./tmp/flows/<slug>.clj
breyta flows push --file ./tmp/flows/<slug>.clj
# Configure/check before first run when the flow has :requires slots.
# Example:
# breyta flows configure <slug> --set api.conn=conn-...
breyta flows configure check <slug>
# Optional read-only verification (useful for CI/troubleshooting):
breyta flows validate <slug>
breyta flows run <slug> --input '{"name":"Ada"}' --wait

Configure Before First Run (When Required)

breyta flows search "<problem keyword>" searches the global approved flow catalog by default, so it works even when no default workspace is selected. Use --catalog-scope workspace only when you want workspace-local search and already have workspace context.

If your flow declares :requires slots or required runtime inputs, configure those values before the first run.

Use Flow Configuration for the exact configuration workflow.

How Requires, Configure, And Connections Fit Together

Stage	What it controls	Canonical command
Declare contract	`:requires` in the flow file defines required slots/inputs.	`breyta flows pull/push ...`
Bind values	Profile bindings map each required slot to a real connection/secret/input value for a target.	`breyta flows configure <slug> --set <slot>.conn=<connection-id>`
Verify readiness	Checks missing/invalid bindings and required inputs before runtime. For live, prefer version-pinned checks.	`breyta flows configure check <slug>` or `breyta flows configure check <slug> --target live --version latest`
Run	Runtime resolves the selected target profile bindings and executes.	`breyta flows run <slug> ...`
Maintain wiring	Usage reports show where bindings reference a connection/secret.	`breyta connections usages ...` / `breyta secrets usages ...`

Connection/secret delete guards are binding-based.
Even if a flow definition changed, delete remains blocked while any draft/live/installation profile still references that id.

Draft Vs Live (Target Split)

Target	What it means	Commands
`draft` (default)	Your draft bindings/config target (latest `flows push` + `flows configure`). Fast iteration lane for authoring and validation. `flows run` still executes the active version unless `--version` overrides it.	`breyta flows run/show/pull/validate <slug>`
`live`	Installed released target for stable/runtime consumption. Changed by `release`/`promote`, not by `push`.	`breyta flows run <slug> --target live`

Run Target After Release

breyta flows release <slug> --release-note-file ./release-note.md creates a release, attaches a markdown release note, and updates the live installation target for the selected workspace by default.

breyta flows run <slug> still uses draft-target bindings/config unless you explicitly target live/install target.

Brand-new flows with no active version are not runnable through flows run until you deploy or release a version.

If the new flow has :requires slots, prepare the live target before the first release:

breyta flows configure <slug> --target live --version latest --set <slot>.conn=<connection-id>
breyta flows configure check <slug> --target live --version latest

To run the installed live target, use one of:

breyta flows run <slug> --target live --wait
breyta flows run <slug> --installation-id <installation-id> --wait

If you intentionally skipped end-user installation promotion (--skip-promote-installations), promote them later with:

breyta flows promote <slug>
breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md if you need to edit the release note later

Before releasing, inspect draft-vs-live changes with:

breyta flows diff <slug>

What You Get

Outcome	Why it matters
Config target checked	Catches missing bindings/secrets/inputs before first run.
Optional explicit validation	Gives a read-only checkpoint for CI/troubleshooting.
Required config applied	Prevents first-run failures from missing bindings/secrets/inputs.
Runnable immediately after push	Keeps iteration fast in the same workspace.
Verified run output	Confirms end-to-end behavior quickly.

Next Guides

Need	Guide
Full lifecycle details	CLI Workflow
Setup reusable connections first	Connections First
Installation scopes (advanced)	Installations
Requires/bindings/secrets	Flow Configuration
Failures and triage	Troubleshooting

Notes

Canonical default surface is flows pull, flows push, flows configure, flows configure check, and flows run.
flows diff shows draft-vs-live or version-vs-version source changes on demand.
flows release (auto live install for selected workspace) and flows promote are rollout/governance operations.
flows push updates draft only; it does not change live.
connections test confirms health/config state, not end-to-end step execution.
Activation inputs are preserved across flows release/flows promote; update them explicitly via flows configure or flows installations configure.
Legacy command aliases still execute for compatibility but are intentionally hidden from default help.