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:

breyta flows lint --file ./tmp/flows/<slug>.clj -> 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.
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 lint --file ./tmp/flows/<slug>.clj`	Fast local-first candidate source checks before mutating draft. Add `--server` for canonical non-mutating API lint; server lint is bounded by `--timeout` (default 30s).
`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 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, --set <slot>.secret=<value> stores a required secret, and --set activation.<input>=<value> saves a setup input. Use flows doctor or flows readiness when checking target readiness.

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.md
breyta flows promote <slug>

Flow Health Email Cadence

Flow-health incident/digest commands are currently available to workspace
creators/admins.
breyta digests cadence changes 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
selected daily, weekly, or monthly window.
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 cadence or breyta digests cadence set daily|weekly|monthly to
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