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

Compatibility: breyta discover ... is a newer shortcut for the discover
surface. If your CLI does not show it in breyta help, use the released
breyta flows discover ... form shown below.

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.

CLI Manual Upload Smoke Tests

For invocation inputs typed :file, :blob, or :blob-ref, prefer flows run --upload field=path when you need the CLI to emulate a browser/manual upload. The CLI uploads the local file as a workspace file resource, then sends that input field as a canonical resource-ref for the run:

breyta flows run thesis-pdf-review-docx \
  --target draft \
  --interface-id run \
  --upload thesis=./thesis.pdf \
  --wait

Combine --upload with --input for the non-file fields:

breyta flows run thesis-pdf-review-docx \
  --target draft \
  --interface-id run \
  --input '{"reviewDepth":"smoke"}' \
  --upload thesis=./thesis.pdf \
  --wait

Do not put the same field in both --input and --upload; the CLI rejects that ambiguity. Repeat --upload for multi-file inputs.

When the flow should return a downloadable artifact, persist the generated file
as a blob and render it from the final Markdown output with a breyta-resource
:view :download fence. See
Persisted Results And Resources
for the complete upload-to-download recipe.

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.
• Use breyta flows public publish <slug> or breyta flows public delist <slug> when a flow should move onto or off all public surfaces together: marketplace visibility, Discover listing, and the public app page.
• Marketplace visibility is stored metadata. Use breyta flows marketplace update <slug> --visible=true|false only when you intentionally need to change that lower-level flag without changing Discover visibility.
• 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|false only when you intentionally need to change the lower-level Discover flag without changing marketplace visibility. 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 public visibility path:
   • Source-first: add both :marketplace {:visible true} and :discover {:public true} before push only after explicit approval.
   • Explicit after release: run breyta flows public publish <slug> after push and release, only after explicit approval.
4. Push the flow with breyta flows push --file ....
5. Release/promote it so there is an installable live version.
6. If you chose the explicit public path, run breyta flows public publish <slug> after release. Use breyta flows public delist <slug> to remove the flow from all public surfaces later.
7. 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
• Buyer Test Mode author run, after creating the Buyer Test source install: breyta flows run <slug> --buyer-test --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, and one webhook adapter. It may expose
multiple MCP tools when the same flow intentionally offers several agent-callable
operations, but use extra invocation ids only when a tool needs a genuinely
different payload contract, not to turn one flow into several unrelated apps.

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. For paid public apps, start from Discover or https://breyta.ai/apps/<flow-slug>
   when checkout, purchase, subscription, prepaid runs, or trial entry is
   required. Complete that web entitlement step first.
3. Create, configure, and enable an installation in the caller workspace.
4. Inspect breyta flows installations interfaces <installation-id>.
5. Inspect breyta flows installations get <installation-id> and check
   data.runReadiness before building wrappers around paid public apps.
6. Choose the call surface by caller: flow/call-flow with :installation-id
   inside authored Breyta flows, workspace MCP call_flow_tool with
   installation_id from MCP-capable agents, or the installation-scoped HTTP
   interface from external non-MCP clients.

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-capable agents, prefer the workspace MCP server path:
search_flow_tools, inspect_flow_tool, call_flow_tool, then
get_run_status. Pass installation_id when targeting a specific installed
app instance. A direct installed Streamable HTTP MCP endpoint is still available
when the caller deliberately wants per-flow isolation. Paid public flows can
return entitlement or checkout errors such as billing_trial_ended; handle
those as billing state rather than interface-shape failures. Complete the
returned checkout action in the web app, then retry the install or interface
call.

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>.

When a run starts and the flow has prior run history, the start response includes avgDurationMs (the historical average completed runtime, in milliseconds), and the CLI prints an estimate such as Runs of this flow usually finish in about 2 minutes. to stderr before polling. Use it to gauge how long a --wait run will take instead of waiting blindly. The estimate is omitted for flows with no completed run history.

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