CLI Workflow

Quick Answer

Default flow lifecycle:

1. Edit working copy (pull/push/validate)
2. Verify runtime (run)
3. Use release/promote/installations only when you need explicit rollout governance

Default Reporting Step

If work is blocked by missing capability or unclear failures, report it before ending the task:

breyta feedback send \
  --type issue \
  --title "Short summary" \
  --description "What failed, expected behavior, and workaround tried" \
  --flow <slug> --workflow-id <id> --run-id <id> --agent

Use --type feature_request for missing product capability.

Canonical Commands

Authoring Loop (Working Copy)

1. breyta flows pull <slug> --out ./tmp/flows/<slug>.clj
2. Edit file
3. breyta flows push --file ./tmp/flows/<slug>.clj
4. If the flow has required slots/inputs: breyta flows configure <slug> ...
5. breyta flows configure check <slug>

For large local source files, breyta flows push also expands explicit local include forms before upload:

:functions [#flow/include "flow-assets/functions/normalize-config.edn"]
:templates [#flow/include "flow-assets/templates/security-reviewer.edn"]

The include path is resolved relative to the flow file you push. Expansion happens only in the uploaded payload; your local source file keeps the include form.

connections test is a health/config check. It does not replace a real flow run against the target system.

If you are updating live after a slot change, use version-pinned live checks/applies:

• breyta flows configure check <slug> --target live --version <n|latest>
• breyta flows configure <slug> --target live --version <n|latest> --set ...

For a brand-new flow with required slots, use --version latest on the live target before the first release. Otherwise flows release <slug> can fail with live_config_incomplete.

Optional checks:

• breyta flows validate <slug>
• breyta flows show <slug>
• breyta flows diff <slug>

Public discover notes:

• Public discover is stored metadata, not just a UI interpretation of the flow file.
• Marketplace visibility is stored metadata. You can author :marketplace {:visible true} in source or change it explicitly with breyta flows marketplace update <slug> --visible=true. Ask for explicit flow-author approval and prove installable readiness before enabling it.
• Paid app monetization can be saved from the flow Publish page or authored in
  source with :marketplace {:app {... :monetization {:plans [...]}}} and
  persisted on push. Legacy flow-level :marketplace {:monetization {...}}
  remains supported for existing listings.
• Paid public-flow monetization supports :free, :one-time, :subscription,
  :usage, and :subscription-usage pricing metadata. Usage pricing records
  run allowances in metadata while run metering and Stripe usage invoicing are
  rolled out.
• Seat-based pricing is not implemented; use run quantities only for
  usage-priced plans.
• File-based authoring can set :discover {:public true} directly in the .clj flow source. Do not push source that contains :discover {:public true} or :marketplace {:visible true} until the flow author has approved broad public access and installable readiness is proven.
• File-based authoring can also set :publish-media directly in the .clj flow source.
• Use breyta flows discover list / breyta flows discover search <query> to inspect the public installable catalog that appears in the web app. These commands exclude flows owned by the current workspace by default because they show what this workspace can install.
• Use --include-own only when debugging whether your own public flow is indexed. Verify the buyer/install experience from another workspace.
• Use breyta flows discover update <slug> --public=true when you want to enable discover visibility explicitly after push. Ask for explicit flow-author approval and prove installable readiness before enabling it.
• Public discover requires explicit public visibility and an active released version
  with an installable interface.
• breyta flows templates search/grep is a different catalog: it returns approved reusable templates to inspect and copy from.

Public flow checklist for CLI/source work:

1. If the flow is a new paid app, author
   :marketplace {:app {... :monetization {:plans [...]}}} in source before
   push. Keep :marketplace {:monetization {...}} only for an existing legacy
   listing.
2. Add install-surface copy and discover card media when the public surface should be polished:
   • breyta flows update <slug> --publish-description-file ./publish-description.md
   • breyta flows update <slug> --publish-media-type image --publish-media-source-kind https-url --publish-media-source https://...
3. Choose one marketplace visibility path:
   • Source-first: add :marketplace {:visible true} to the flow definition before push only after explicit approval.
   • Explicit after push: push first, then run breyta flows marketplace update <slug> --visible=true only after explicit approval.
4. Choose one discover visibility path:
   • Source-first: add :discover {:public true} to the flow definition before push only after explicit approval.
   • Explicit after push: push first, then run breyta flows discover update <slug> --public=true only after explicit approval.
5. Push the flow with breyta flows push --file ....
6. If you chose an explicit marketplace/discover path, run those update commands after push.
7. Release/promote it so there is an installable live version.
8. Verify the web Discover install path. For CLI indexing checks, use another
   workspace or add --include-own only while debugging the owner workspace.

For the app-first paid-flow path, seller onboarding, and the dedicated Publish
page, see Paid Public Flows.

If a flow is public in source but not visible in Discover, the first things to check are:

• breyta flows show <slug> --pretty includes discover.public
• the flow has an active released version that can be installed

Grouping notes:

• breyta help flows update shows the writable grouping fields and exact clear syntax.
• flows list exposes groupKey, groupName, groupDescription, and groupOrder when a flow is grouped.
• flows show also exposes groupFlows, which lists sibling flows in the same group.
• Set explicit order with breyta flows update <slug> --group-order <n> when grouped flows should render in execution order.
• Lower groupOrder values sort first. Use spaced values like 10, 20, 30.
• Clear only the order with breyta flows update <slug> --group-order "".
• Use the existing flow metadata update surface to maintain grouping metadata, then verify with flows show <slug>.
• Grouping metadata is mutable workspace metadata and does not round-trip through flows pull / flows push source files.
• For a focused grouped-flow guide with examples, see Flow Grouping.

Display icon notes:

• primaryDisplayConnectionSlot chooses which connection/provider icon is shown anywhere the flow icon renders today.
• In the UI this is labeled Display icon.
• Set it from the flow detail UI or with breyta flows update <slug> --primary-display-connection-slot <selector>.
• Clear it with breyta flows update <slug> --primary-display-connection-slot ''.
• Selectors come from declared :requires slots or normalized keys from :connections.
• If unset or unmatched, rendering falls back to the first explicit :connections icon, then the first inferred :requires icon.
• flows show --pretty JSON responses include primaryDisplayConnectionSlot plus _hints whenever the flow exposes connection metadata or a saved display selector.

Example:

{
  "ok": true,
  "data": {
    "flow": {
      "flowSlug": "customer-support",
      "primaryDisplayConnectionSlot": "crm"
    }
  },
  "_hints": [
    "Inspect `requires`, `connections`, and `primaryDisplayConnectionSlot` with `breyta flows show customer-support --pretty`.",
    "Set the rendered flow icon with `breyta flows update customer-support --primary-display-connection-slot <selector>`.",
    "Clear it with `breyta flows update customer-support --primary-display-connection-slot ''`.",
    "If unset or unmatched, the icon falls back to the first explicit `connections` icon, then the first inferred `requires` icon."
  ]
}

Discover card media notes:

• Use breyta flows update <slug> --publish-media-type ... when public cards should show a curated image or video preview
• Use --publish-media-source-kind https-url|flow-resource plus --publish-media-source <value> to set the hero asset
• Use --publish-media-poster-kind and --publish-media-poster only for video media
• Use --clear-publish-media to remove stored discover card media
• If you keep discover card media in source control, author it as :publish-media in the flow file and push it
• Use breyta help flows update for the exact flag surface

Advanced Release + Install Operations

Use flows release / flows promote / flows installations ... only when you need explicit scopes, promotion control, or installation-specific webhooks.

New end-user installations follow the latest released version by default.
Zero-setup installations can auto-enable immediately; installations with setup
requirements stay disabled while setup is incomplete, then start only after the
installer enables them.

Disabling an installation is a global pause. It blocks manual runs, interface
calls, and schedules for that installation, but keeps the saved setup,
per-interface settings, and per-schedule settings so they can resume when the
installation is enabled again.

Release Defaults

breyta flows release <slug> always promotes the live target for the selected workspace and, by default, also promotes track-latest end-user installations.

Attach a markdown release note whenever you know what changed. It becomes part of the version metadata returned by flows show / flows versions list.

If the flow has required slots and no active version yet, configure the live target first with --target live --version latest before running flows release.

Runtime Verification

• Canonical: breyta flows run <slug> --wait
• Advanced explicit target: breyta flows run <slug> --installation-id <installation-id> --wait
• Inspect run: breyta runs show <workflow-id>
• Filter runs: breyta runs list --query 'status:failed flow:<slug>'

Flow Health Delivery Timing

• Flow-health incident/digest commands are currently available to workspace
  creators/admins.
• breyta digests cadence updates only your own delivery settings in the
  current workspace.
• Scheduled 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 delivered as soon as possible when your email
  delivery mode includes urgent issues.
• Urgent emails are not delayed to the next scheduled digest.
• Use breyta digests cadence or breyta digests cadence set daily|weekly|monthly to
  inspect or change the scheduled cadence from the CLI.

flows run uses draft-target bindings/config by default, but the executed code version still comes from the active release unless you override it with --version.

runs list uses the same structured filter syntax as the web runs list. Use installation:<installation-id> for installation runs and version:<n> for the flow version active when the run started.

Post-Release Targeting

After breyta flows release <slug>, the live install is updated for the selected workspace by default. Track-latest end-user installations are also promoted unless you pass --skip-promote-installations. Default breyta flows run <slug> still uses draft-target bindings/config.

Use explicit flags when you want installation runtime behavior:

For new flows, declare per-run fields under :invocations, expose the author
run button through :interfaces :manual, and pass values with --input.

Older manual field shapes remain executable for compatibility, but new docs and
new source should use :invocations plus :interfaces :manual.

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

• breyta flows promote <slug>

Invocation Interfaces

Use :interfaces when a solution flow should be callable by a manual run form,
another program, HTTP client, webhook provider, or MCP/coding-agent tool. The
source contract normally lives in :invocations {:default ...}; :interfaces
only declares the call surface.

A flow should normally expose one public invocation for the solution, with at
most one manual adapter, one HTTP adapter, one webhook adapter, and one MCP
adapter. Use extra invocation ids only when an adapter needs a genuinely
different payload contract, not to turn one flow into several unrelated tools.

Author smoke loop:

breyta flows push --file ./flow.clj
breyta flows run <slug> --input '{"key":"value"}' --wait
breyta flows interfaces call <slug> <http-interface-id> --input '{"key":"value"}' --wait
breyta flows release <slug>
breyta flows interfaces list <slug> --target live
breyta flows interfaces show <slug> <http-interface-id> --target live
breyta flows interfaces curl <slug> <http-interface-id> --target live --input '{"key":"value"}'
breyta flows interfaces call <slug> <http-interface-id> --target live --input '{"key":"value"}' --wait
breyta flows metrics <slug> --source live

Consumer/installation loop:

breyta flows installations create <slug> --name "Client API"
breyta flows installations configure <installation-id> --input '{"setup":"value"}'
breyta flows installations enable <installation-id>
breyta flows installations interfaces <installation-id>
breyta flows interfaces call <slug> <http-interface-id> --installation-id <installation-id> --input '{"key":"value"}' --wait
breyta flows metrics <slug> --installation-id <installation-id>

Consumer composition recipe:

1. Discover or choose the public flow to reuse.
2. Create, configure, and enable an installation in the caller workspace.
3. Inspect breyta flows installations interfaces <installation-id>.
4. Use the installation-scoped HTTP or MCP interface from the wrapper flow,
   coding agent, or external client.

Use installation-scoped endpoints for consumer calls:

/api/flows/{flow-slug}/installations/{installation-id}/interfaces/{interface-id}
/api/workspaces/{workspace-id}/flows/{flow-slug}/installations/{installation-id}/interfaces/{interface-id}

For MCP, connect to the installed Streamable HTTP interface with bearer auth,
then call initialize, tools/list, and tools/call. Paid public flows can
return entitlement errors such as billing_trial_ended; handle those as billing
state rather than interface-shape failures.

flows interfaces curl prints Authorization: Bearer ${BREYTA_TOKEN} as a
placeholder. Interface calls still require normal workspace/API authentication in
the current CLI path.

For async or long-running interfaces, the HTTP response includes data.statusUrl
when the run has a workflowId. That endpoint is scoped to the same interface
surface and can be polled by API clients. The CLI --wait flag handles this
polling for author smoke tests.

Use flows metrics to inspect aggregate invocation health for invocation-backed
client surfaces. Metrics are redacted counters and timings only; they do not
include raw request bodies, response bodies, tokens, headers, secrets, or
binding values. Use --source draft or --source live for author-owned
interface calls, and --installation-id <id> for installed consumer calls. The
returned interfaceScope keeps draft, live, and installation traffic separate
even when they use the same interface id. Use runs show <workflow-id> when you
need an individual run.

MCP interfaces need the same explicit authorization boundary. A coding agent
should connect to Breyta with a scoped workspace API credential for the
installation/interface surface, and tool discovery should generally return one
MCP tool for the installed solution flow. It should not expose non-interfaced or
unauthorized invocations. Unlike normal HTTP interface calls, MCP tools/call
requests wait for the backing flow run to complete up to a bounded 180-second
timeout and return the flow result to the tool caller, with Breyta run metadata
under _breyta.

Run Targeting Matrix

Use this matrix for breyta flows run <slug>.

Docs Lookup

Compatibility Notes

Legacy command aliases remain executable for compatibility, but canonical
guidance uses only the commands in this page. New manual, HTTP, webhook, and MCP
ingress should be authored and inspected through interfaces.

Related

• Start Here
• Flow Grouping
• Connections First
• Flow Authoring
• Flow Definition
• CLI Commands
• Feedback And Reporting