CLI Essentials

Breyta CLI essentials for the default draft/live workflow.

Quick Answer

Use this default path:

breyta flows push --file ./tmp/flows/<slug>.clj -> breyta flows configure <slug> --set <slot>.conn=conn-... (if required) -> breyta flows configure check <slug> -> breyta flows run <slug> --wait

Core Checks

Check	Why
Confirm API/workspace/token context	Avoids writing to the wrong workspace.
Reuse connections before creating new ones	Reduces duplicate connection sprawl.
Test connection health before wiring	Catches auth/base-url issues earlier, but it is not a substitute for a real flow run.
Search existing flows first	Reuse existing definitions before creating new slugs.
Configure required bindings/secrets/inputs before first run	Prevents avoidable runtime failures.
Validate before release	Prevents bad releases.

Commands

Command	Use
`breyta docs find "flows"`	Find docs quickly.
`breyta flows search <query>`	Search approved flow catalog definitions. Global search works without a selected workspace; `--catalog-scope workspace` still requires one.
`breyta connections list [--type ...]`	Reuse an existing connection first.
`breyta connections usages --only-connected`	Inspect where connections are already wired (`draft`/`live`/`installation`).
`breyta connections test --all`	Verify workspace connection health before wiring. This is a health/config check, not end-to-end runtime proof.
`breyta secrets usages --only-connected`	Inspect where secret refs are already wired (`draft`/`live`/`installation`).
`breyta flows push --file ./tmp/flows/<slug>.clj`	Update working copy.
`breyta help flows update`	Show mutable flow metadata flags, including grouped-flow ordering flags like `--group-order`.
`breyta flows configure suggest <slug>`	Suggest `--set` values from existing connections.
`breyta flows configure check <slug>`	Check missing bindings/inputs before running.
`breyta flows validate <slug>`	Optional read-only validation (CI/troubleshooting/explicit checks).
`breyta flows diff <slug>`	Inspect draft-vs-live source changes before release.
`breyta docs show guide-flow-configuration`	Open configuration guide when flow requires bindings/secrets/inputs.
`breyta flows run <slug> --wait`	Verify runtime behavior.

Advanced rollout commands:

breyta flows release <slug> --release-note-file ./release-note.md (updates live installation for the selected workspace by default)
breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md
breyta flows promote <slug>

Functional Difference: Draft Vs Live

Target	Updated by	Typical use
`draft`	`flows push`	Day-to-day authoring and validation.
`live`	`flows release` or `flows promote`	Stable installed runtime target.

Run Targeting After Release

breyta flows run <slug> defaults to draft-target bindings/config. It still executes the active flow version unless --version is provided. Releasing does not automatically switch that default to a live installation target.

Need	Command
Run with draft-target bindings/config (default)	`breyta flows run <slug> --wait`
Run installed live target	`breyta flows run <slug> --target live --wait`
Run exact installation	`breyta flows run <slug> --installation-id <installation-id> --wait`
Skip end-user installation promotion on release (advanced)	`breyta flows release <slug> --skip-promote-installations`
Manually promote live installation	`breyta flows promote <slug>`

Brand-new flows with no active version will return no_active_version on flows run until you deploy or release a version.

If a brand-new flow has required slots, prepare the live target before the first release: