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>

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.
• File-based authoring can set :discover {:public true} 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.
• Use breyta flows discover update <slug> --public=true|false when you want to inspect or change discover visibility explicitly after push.
• Public discover requires both an active released version and the end-user tag.
• breyta flows search <query> is a different catalog: it returns approved example flows to inspect and copy from.

Public flow checklist:

1. Tag the flow with end-user.
2. Choose one visibility path:
   • Source-first: add :discover {:public true} to the flow definition before push.
   • Explicit after push: wait until after push, then run breyta flows discover update <slug> --public=true.
3. Push the flow with breyta flows push --file ....
4. If you chose the explicit path, run breyta flows discover update <slug> --public=true after push.
5. Release/promote it so there is an installable live version.
6. Verify it in the web Discover UI. If you have another workspace, you can also confirm with breyta flows discover list or breyta flows discover search <query>.

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 metadata includes the end-user tag
• 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 --pretty.
• 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."
  ]
}

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.

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

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:<profile-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:

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

• breyta flows promote <slug>

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.

Related

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