CLI Commands
Reference for the canonical Breyta CLI lifecycle and docs navigation.
Core Surface
| Command | What it does |
|---|---|
breyta docs | Show docs command surface (find, show, sync). |
breyta docs find "flows" | Search docs pages. |
breyta docs show <slug> | Print a docs page. |
breyta docs sync --out ./.breyta-docs --clean | Download docs corpus for offline grep/search. |
breyta flows search <query> | Search approved example flows that the Breyta team has approved for reuse. These are definitions to inspect and copy from, not public installables. Global search works without a selected workspace; --catalog-scope workspace still requires one. |
breyta flows discover list | Browse public installable end-user flows for the current workspace. This is the same discover/install catalog used by the web app. |
breyta flows discover search <query> | Search public installable end-user flows for the current workspace. |
breyta connections list [--type ...] | List reusable workspace connections. |
breyta connections usages [--connection-id <id>] [--flow <slug>] [--only-connected] | Show which flow targets (draft/live/installation) currently use each connection. |
breyta connections create ... | Create a new connection when no reusable one exists. |
breyta connections test <connection-id> | Test one connection health directly. This confirms health/config state, not end-to-end step execution. |
breyta connections test --all [--only-failing] | Run workspace-wide connection health checks before wiring. This is a preflight check, not runtime proof. |
breyta connections delete <connection-id> | Delete an unbound connection. If still bound, CLI returns a hint to move/unset bindings first. |
breyta secrets list [--secret-id <id>] | List workspace secret IDs. |
breyta secrets usages [--secret-id <id>] [--flow <slug>] [--only-connected] | Show which flow targets (draft/live/installation) currently reference each secret. |
breyta secrets delete <secret-id> | Delete an unbound secret. If still bound, CLI returns a hint to move/unset bindings first. |
breyta flows list [--pretty] | List workspace flows. Grouped flows include groupKey, groupName, groupDescription, and groupOrder in the response. Flow metadata can also include primaryDisplayConnectionSlot for icon rendering. |
breyta flows show <slug> [--pretty] | Show one flow. Grouped flows also include groupFlows with sibling flows in the same group, ordered by explicit groupOrder when present. When the flow exposes :requires, :connections, or a saved display selector, JSON responses also include _hints for inspecting and updating icon metadata. |
breyta flows discover update <slug> --public=true|false | Update stored public discover visibility for an end-user flow. Use this when you want the flow to appear in discover/install surfaces or when you want to hide it again later. |
breyta flows update <slug> ... | Update mutable flow metadata. Use breyta help flows update for exact flag shape. Use this surface for grouping metadata, including --group-order, --primary-display-connection-slot <selector>, and install-surface copy via --publish-description / --publish-description-file, then verify with flows show --pretty. |
breyta flows pull <slug> --out ./tmp/flows/<slug>.clj | Pull definition to local file. |
breyta flows push --file ./tmp/flows/<slug>.clj | Push working copy. |
breyta flows diff <slug> | Show a unified source diff between draft and live by default (or compare explicit versions with flags). |
breyta flows configure suggest <slug> [--target live] | Suggest --set bindings from existing connections and show unresolved slots. |
breyta flows configure <slug> --set ... | Configure draft runtime target (bindings/inputs) when required. For live, use --target live and optional --version <n|latest>. |
breyta flows configure check <slug> | Check required bindings/inputs for draft target. For live, use --target live and optional --version <n|latest>. |
breyta flows validate <slug> | Optional read-only validation (useful for CI/troubleshooting/explicit target checks). |
breyta flows run <slug> --wait | Start a run using draft-target bindings/config by default. Code version comes from the active release unless --version overrides it. |
breyta runs list --query 'status:failed flow:my-flow installation:prof-1 version:7' | List runs with the canonical structured filter syntax used by the web runs list. |
breyta runs list --installation-id <profile-id> --version <n> | Legacy-discrete filter flags for API mode. These override matching --query tokens. |
breyta runs show <workflow-id> | Inspect one run in detail. |
breyta resources list [--query "<text>"] [--types file,result] [--accept text/*,application/json] [--exclude-tier ephemeral] [--storage-backend gcs] [--storage-root reports/acme] [--path-prefix exports/2026] [--limit 1000] | List resources with picker-style filters, including storage-scoped filters, so you can debug the same candidate pool used by resource selectors. |
breyta resources search "<query>" [--type result|file] [--content-sources file,result] [--storage-backend gcs] [--storage-root reports/acme] [--path-prefix exports/2026] | Search workspace files and persisted blobs by filename/path/URI/content snippet, with optional storage backend/root/path narrowing. |
breyta feedback send --title "..." --description "..." | Send issue/feature feedback to the Breyta team. |
Resource storage filters use the normalized indexed storage fields rather than the raw full object path:
--storage-backendmatches backend family such asgcs--storage-rootmatches the configured root such asreports/acme--path-prefixmatches the relative path under that root such asexports/2026- broad text search can still match the full indexed
pathwhen you need raw path/debug search
Delete guards are profile-binding based (draft/live/installation).
Even if flow source changed, delete is blocked until old bindings are moved/unset.
flows show/pull/validate target draft by default.
Grouping metadata is mutable workspace metadata, not part of the pulled flow source file.
Display icon selection is also mutable workspace metadata, not part of the pulled flow source file.
Use --primary-display-connection-slot <selector> to choose which connection/provider icon renders anywhere the flow icon is shown today.
Selectors can come from declared :requires slots or normalized keys from :connections.
Clear the selector with --primary-display-connection-slot ''.
If unset or no longer matched, rendering falls back to the first explicit :connections icon, then the first inferred :requires icon.
Publish description is mutable workspace metadata, not part of the pulled flow source file.
Use --publish-description '## Install copy' for short markdown content or --publish-description-file ./publish-description.md for longer install-facing content.
This markdown is used on install/discover dialog surfaces for installable flows.
If no publish description is set, install dialogs fall back to the normal flow description.
Discover cards still use the regular short description preview.
Clear only the publish description with --publish-description ''.
Public discover visibility is stored metadata used by discover/install surfaces and the public discover index.
You can author it directly in a flow file with :discover {:public true} and it will persist on push, or manage it explicitly with breyta flows discover update <slug> --public=true|false.
Public discover requires the end-user tag and a released installable flow.
breyta flows search is intentionally separate: it searches approved example flows to copy from, not the public discover/install catalog.
Public flow checklist:
- Tag the flow with
end-user. - Choose one visibility path:
- Source-first: add
:discover {:public true}to the flow definition before push. - Explicit after push: run
breyta flows discover update <slug> --public=trueonly after the flow has been pushed.
- Source-first: add
- Push the flow.
- If you chose the explicit path, run
breyta flows discover update <slug> --public=trueafter push. - Release/promote it so there is an installable live version.
- Verify it in the web Discover UI. If you have another workspace, you can also confirm with
breyta flows discover listorbreyta flows discover search <query>.
Ordering notes:
groupOrderis explicit manual metadata. Lower numbers sort first.- Use spaced values like
10,20,30so future insertions are easy. - Clear only ordering with
breyta flows update <slug> --group-order "". - Clear the full group with
breyta flows update <slug> --group-key "".
Use breyta flows configure <slug> --target live --from-draft [--version <n|latest>] to promote draft bindings directly to the live target.
Advanced Rollout Commands
| Command | Use |
|---|---|
breyta flows release <slug> | Create an immutable release and update live installation for the selected workspace (default). Attach markdown context with --release-note / --release-note-file. For brand-new flows with required slots, prepare live bindings first with flows configure --target live --version latest .... |
breyta flows promote <slug> | Promote a release to live installation scope. |
breyta flows versions update <slug> --version <n> | Update mutable version metadata such as the markdown releaseNote. |
Advanced Install Commands
| Command | Use |
|---|---|
breyta flows installations list <flow-slug> | List installations for a flow. |
breyta flows installations create <flow-slug> --name "..." | Create installation (disabled by default). |
breyta flows installations get <installation-id> | Inspect installation state (installedVersion, latestAvailable, updateAvailable, policy). |
breyta flows installations configure <installation-id> --input '{...}' | Set installation inputs/config. |
breyta flows installations enable <installation-id> / disable | Toggle installation state. |
breyta flows installations triggers <installation-id> | Show installation trigger endpoints. |
breyta flows installations upload <installation-id> --file ./a.pdf | Upload files to installation webhook trigger. |
breyta flows installations delete <installation-id> | Delete installation. |
New end-user installations default to track-latest.
breyta flows release <slug> always promotes the live target and also promotes track-latest installations by default. Use --skip-promote-installations when you only want the live promotion step.
Recommended release-note flow:
- inspect changes first:
breyta flows diff <slug> - release with markdown note:
breyta flows release <slug> --release-note-file ./release-note.md - edit later if needed:
breyta flows versions update <slug> --version <n> --release-note-file ./release-note.md
Functional Split: Draft Vs Live
| Aspect | draft | live |
|---|---|---|
| Definition source | Latest pushed working copy | Installed released version |
| What updates it | breyta flows push --file ... | breyta flows release <slug> / breyta flows promote <slug> |
| Default run target | Yes (breyta flows run <slug>) | No (must use --target live or --installation-id) |
| Primary intent | Fast authoring iteration | Stable installed runtime behavior |
Run Flag Matrix
breyta flows run <slug> defaults to draft-target bindings/config resolution. By default it still executes the active flow version, so brand-new flows need an active version before they are runnable without --version.
| Need | Flags |
|---|---|
| Default draft target bindings/config | none |
| Installed live target (advanced) | --target live |
| Exact installation (advanced) | --installation-id <id> |
| Explicit release version | --version <n> |
| Runtime input payload | --input '{...}' |
| Wait for completion | --wait (plus optional --timeout, --poll) |
--target selects which bindings/config target to use. It does not switch execution to the mutable draft definition.
breyta flows release <slug> updates live installation for the selected workspace by default, but does not change the default run target. Use --target live or --installation-id when you need installation runtime behavior.
breyta runs list supports the same structured filter tokens as the web runs list:
status:<running|completed|failed|waiting>flow:<slug>installation:<profile-id>version:<n>
Docs Search Examples
| Query | Command |
|---|---|
| Source-filtered query | breyta docs find "source:cli release" |
| Phrase + boolean | breyta docs find "\"end-user\" AND source:flows-api" |
| Pagination | breyta docs find "install" --limit 20 --offset 20 |
| Snippets/explain | breyta docs find "release" --with-snippets --explain --format json |
Compatibility Surface
Legacy command aliases remain executable for compatibility but are not part of the canonical command surface.