Start Here

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

Quick Answer

Use this sequence:

# Optional for agent sessions; also follow any CLI missing/stale skill warning:
breyta skills status --provider all
breyta docs find "flows" --limit 5 --format json
breyta flows search "<workspace pattern or integration>" --limit 5
breyta flows templates search "<problem keyword>" --limit 5
breyta resources search "<existing report, upload, or run output>" --limit 5
# 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 lint --file ./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
# Open the run Output page returned by the CLI and confirm the final artifact is readable.

If you need the full command catalog or a broader docs map instead of the default lifecycle, jump to CLI Commands or Reference Index.
For task-oriented agent work, start with Author Flows, then open only the exact reference needed.

Use Breyta Docs With AI Coding Agents

Use the agent-readable docs index when working in Cursor, Claude Code, Codex,
or another coding agent:

• Breyta Flows docs index: https://flows.breyta.ai/llms.txt
• Complete Breyta Flows docs: https://flows.breyta.ai/llms-full.txt
• Markdown page form: append .md to any docs URL, for example https://flows.breyta.ai/docs/start-here.md
• Context7 claim file: https://flows.breyta.ai/docs/context7.json
• Context7 source: submit https://flows.breyta.ai/llms.txt or crawl https://flows.breyta.ai/docs

Recommended agent rule: when creating or editing Breyta flows, read the Breyta
Flows docs first and prefer the referenced playbooks and step references over
stale examples.

Flow Definition Mental Model

A Breyta flow file is a DSL with Clojure/EDN syntax, not a normal Clojure
program. Think of it as an orchestration definition: declare setup contracts,
run inputs, interfaces, reusable templates/functions/steps/agents, then compose
bounded flow/step calls in :flow. Put side effects and large data at step
boundaries, keep orchestration deterministic, persist large results as resource
refs, and use small map-oriented functions for transforms.

Draft Vs Live

draft is the staging/current workspace authoring state. Use it for edits,
configure checks, and safe smoke tests. live is the released/runtime state. A
flow is unreleased until a version is released or activated and the live path is
verified. Say draft verified when only draft was exercised; reserve
released, end-user ready, and public ready for live/install-shaped proof.

Configure Before First Run (When Required)

breyta flows search "<query>" --limit 5 searches actual workspace flow
metadata. Use breyta flows grep "<literal>" --limit 5 for workspace
source/config search, such as tool names or upload fields. Approved reusable
templates live under
breyta flows templates search "<problem keyword>" --limit 5 and
breyta flows templates grep "<literal>". Add --surface definition or
--surface tools when a literal appears in too many places.

Treat search like rg: read the compact hit ref, matched surface/field,
snippet or preview, and nextCommand; open only the one focused docs page,
flow, template, or resource that the hit points to.

If the new flow should build on existing reports, uploads, table resources, or
prior run output, search resources before creating a new ingestion path:

• breyta resources search "<query>" --limit 5
• breyta resources read <resource-uri> --limit 5

If your flow declares :requires slots or setup form fields, configure those
values before the first run. Values that should be entered on each run belong in
:invocations and are supplied with breyta flows run --input ....

New flows should expose manual runs through :interfaces :manual over an
:invocations contract. breyta flows run <slug> --input ... --wait can use
the enabled manual interface automatically. Declare at most one manual
interface; when authors need multiple entry modes, model that choice as an
invocation input such as mode or use another interface family. Use
--interface-id <id> only when you need to select the declared manual interface
explicitly. New flow source also needs an explicit :concurrency policy.

Use Flow Configuration for the exact configuration workflow.

How Requires, Configure, And Connections Fit Together

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

Draft Vs Live (Target Split)

If CLI works but UI fails, first check whether the CLI tested draft while the
web setup page, run form fields, installed flow, or public/end-user run used an
old live version. flows push updates draft only; the UI install path follows
the released live/install target.

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

Shape The Final Output

The value returned by :flow is the run output. Treat that final return value
as a product surface, not just an automation payload. For most human-facing
flows, return a Markdown viewer envelope; when the report needs real Breyta
tables, charts, files, images, videos, or JSON resources, embed them with
breyta-resource fences.

Use Output Artifacts before releasing any
flow where a person will inspect the result.

Next Playbooks And References

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.