CLI Essentials
Breyta CLI essentials for the default draft/live workflow.
This page is for terminal, CI, local operator, and agent workflows that use the
CLI. If you are connecting an agent through MCP, see
Workspace MCP and
Connect Breyta MCP To Agentic Coding Tools.
Both the CLI and MCP are valid agent paths; use the surface that matches the
host and task.
Quick Answer
Use this default path for a new flow:
breyta flows init <slug> -> edit with flows steps ... / flows compose -> breyta flows lint --file ./flows/<slug>.clj -> optional breyta flows steps run <slug> <step-id> --params '<json>' -> breyta flows push --file ./flows/<slug>.clj -> breyta flows configure <slug> --set <slot>.conn=conn-... (if required) -> breyta flows configure check <slug> -> breyta flows run <slug> --wait
For an existing remote flow, start with breyta flows pull <slug> --out ./tmp/flows/<slug>.clj. Local edits do not write a draft until flows push
(or an explicit command-level --push) is used.
Core Checks
| Check | Why |
|---|---|
| Confirm API/workspace/token context | Avoids writing to the wrong workspace. |
| Search workspace patterns and approved templates before writing source | Reuses proven structure instead of spending context on blank-page design. |
| Search resources before rebuilding data ingestion | Existing run outputs, reports, uploads, and table resources may already contain the data shape you need. |
| 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 workspace flows first | Reuse nearby workspace patterns 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" --limit 5 --format json | Find docs quickly in a parseable agent-friendly shape. |
breyta flows search "<query>" --limit 5 | Search actual workspace flows by metadata, step type, provider, connection, or tool name. |
breyta flows grep "<pattern>" --surface definition,tools --limit 5 | Search actual workspace flow source/config literals. Use repeatable --or for spelling variations and --surface to narrow noisy matches. |
breyta flows templates search "<query>" --limit 5 | Search approved reusable templates by metadata. Default cards are compact; use --full only for template source previews. |
breyta flows templates grep "<pattern>" --surface steps,tools --limit 5 | Search approved reusable template source/config literals. |
breyta resources search "<query>" --limit 5 | Search existing workspace resources, uploads, and prior run outputs before creating new ingestion. |
breyta resources read <resource-uri> --limit 5 | Read a compact preview of one selected resource. Use --full only when the complete payload is required. |
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 items <connection-id> [--item-type <type>] | Inspect cached item types and rows for connection-backed dropdowns. |
breyta connections test <connection-id> | Test the specific connection you plan to bind or debug. Avoid --all unless the task is a workspace-wide connection audit. |
breyta secrets usages --only-connected | Inspect where secret refs are already wired (draft/live/installation). |
breyta flows init <slug> --name "My flow" [--input 'site-url:text:required:Site URL'] | Create the canonical local source and empty :schedules. Repeat --input name:type[:required\|optional[:label]] to seed manual invocation inputs. Local only unless --push is explicit. |
breyta flows steps create <slug> <step-id> --step-file ./step.edn | Add one packaged step to the local top-level :steps vector. |
breyta flows steps update/remove <slug> <step-id> ... | Replace or remove one local packaged step without rewriting the orchestration body. Removal is rejected while the local :flow still references that qualified step. |
breyta flows schedules add <slug> <schedule-id> --cron "0 9 * * MON" --timezone UTC | Add one schedule to the local top-level :schedules vector. |
breyta flows schedules update/remove <slug> <schedule-id> ... | Replace a complete schedule map or remove one local schedule without rewriting the flow body. |
breyta flows compose <slug> --body-file ./body.clj | Replace only the quoted top-level :flow form. |
breyta flows steps run <slug> <step-id> --params '<json>' | Execute a packaged step from the complete local literal without persisting a draft. --timeout defaults to 15 minutes and is also available on the --run modes of flows init and flows steps create/update. |
breyta flows run-step <slug> <step-id> --target draft --input '<json>' --wait | Canonical authoring-time probe for a named inline function/code step or an LLM step using draft-bound connection slots. Pass the flow invocation's root input object. flows steps run is only for qualified top-level packaged :steps; steps run --flow is a lower-level primitive/config probe. |
breyta flows lint --file ./tmp/flows/<slug>.clj | Fast local-first candidate source checks before mutating draft, including missing qualified packaged-step references. Add --server for canonical non-mutating API lint; server lint is bounded by --timeout (default 30s). |
breyta flows push --file ./tmp/flows/<slug>.clj [--timeout 2m] | Persist and validate the workspace draft. The timeout defaults to two minutes per API request and applies separately to saving and validation, so the whole command can run longer than two minutes. After a timeout, inspect with breyta flows show <slug> or breyta flows validate <slug> before retrying because the draft may already be saved. |
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 connection slots, secret slots, and activation 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 --section "Required bindings" | Open focused configuration guidance when flow requires bindings/secrets/inputs. Use --full only for the full page. |
breyta flows run <slug> --wait | Verify runtime behavior. The single manual interface is inferred; use --interface-id <id> only when selecting that declared manual interface explicitly. For manual file/blob-ref inputs, use --upload field=path. |
breyta incidents list --status open | Inspect active flow-health incidents in the current workspace. |
breyta incidents list --status open --mine | Limit incident inspection to flows you created in the current workspace. |
breyta incidents show <incident-id> | Inspect one incident with failure rows and drill-down links. |
breyta digests list --kind scheduled --cadence monthly | Inspect scheduled digest artifacts on the current cadence. |
breyta digests cadence | Show the current scheduled digest cadence and settings deep link. |
breyta digests cadence set monthly | Change the scheduled digest cadence for the current workspace/user. |
Configure bindings and activation inputs use the same flows configure
surface: --set <slot>.conn=<connection-id> binds a declared slot, an ordinary
--set <slot>.secret=<value> stores <value> as new plaintext under the
declared :secret-ref, and --set activation.<input>=<value> saves a setup
input. The documented :generate sentinel requests server-side generation.
Never pass a secret ID as <value> to reuse it. Omit the secret field only to
preserve an already-bound target value; omission does not bind an unconfigured
draft target. Use flows doctor or flows readiness when checking target
readiness, then run a provider-specific, read-only smoke test to verify the
credential itself.
Search/read defaults are rg-like: bounded hits include a stable ref, matched
field or surface, short snippet or preview, and a nextCommand for the
smallest focused inspection. Escalate to --full, --raw-definition, or full
resource reads only when the preview cannot answer the decision.
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.mdbreyta flows promote <slug>
Flow Health Email Cadence
- Flow-health incident/digest commands are currently available to workspace
creators/admins. breyta digests cadencechanges only your own delivery settings in the
current workspace.- In-app flow-health updates are on by default for your account.
- Email flow-health updates are opt-in for your account.
- Scheduled incident digests summarize surfaced incident changes from the
selecteddaily,weekly, ormonthlywindow. - If there are no surfaced incident changes in that window, no scheduled digest
is sent. - Urgent incident updates are emailed as soon as possible when your email
delivery mode includes urgent issues. - Urgent emails are not held until the next scheduled digest window.
- Use
breyta digests cadenceorbreyta digests cadence set daily|weekly|monthlyto
inspect or change the scheduled cadence from the CLI.
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:
breyta flows configure <slug> --target live --version latest --set <slot>.conn=<connection-id>breyta flows configure check <slug> --target live --version latest