Breyta Flows

https://flows.breyta.ai/docs
Admin
Official documentation for Breyta Flows, a workflow and agent orchestration platform. Covers EDN...
Tokens:192,527
Snippets:2,189
Trust Score:7.8
Update:5 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Prefer EDN flow examples when showing Breyta flow definitions.
- Use deterministic orchestration for workflow structure and reserve agents for bounded tasks.
- Do not hardcode credentials; use Breyta connections, secrets, setup inputs, and runtime inputs.
- When editing flows, validate drafts, inspect draft/live differences, use current entrypoint docs, and release explicitly before publishing.
- Use Runtime Data Shapes when reading run results, resources, CLI output, or API responses.
- Use documented Breyta CLI commands and flags; do not invent subcommands or options.
- For LLM work, prefer structured prompts, explicit inputs, expected outputs, and model/provider settings from the docs.
- For agent steps, keep tasks bounded with clear instructions, tool scope, success criteria, and handoff outputs.
- For Breyta workspace access, use the :breyta step with explicit allowed operations and minimal required scope.
- For public or installable flows, include install/smoke-test considerations when changes affect setup, inputs, outputs, pricing, or publishing.

================
CODE SNIPPETS
================
### Flow Setup and Invocation Input Example

Source: https://flows.breyta.ai/docs/guide-installations

Example demonstrating how setup fields (like region selection) and invocation inputs (text and resources) are combined into the flow's input map. Setup fields are persistent, while invocation inputs are run-specific.

```clojure
{:requires [{:kind :form
             :fields [{:key :region
                       :field-type :select
                       :required true
                       :options ["EU" "US"]}]}]
 :invocations {:default
               {:inputs [{:name :question
                          :type :text
                          :required true}
                         {:name :resources
                          :type :resource
                          :required true
                          :multiple true}]}}
 :flow
 '(let [input (flow/input)
        region (:region input)
        question (:question input)
        resources (:resources input)]
    {:region region
     :question question
     :resource-count (count resources)})

}
```

--------------------------------

### Operator Setup Example

Source: https://flows.breyta.ai/docs/reference-flow-jobs

Recommended operator setup for a worker identity.

```APIDOC
## Recommended operator setup for that worker identity:

```bash
breyta service-accounts create \
  --name agent-review-worker \
  --scope jobs.worker \
  --job-type agent-review

breyta service-accounts keys create <service-account-id> --name agent-review-key
```
```

--------------------------------

### Installation-Scoped Endpoint Examples

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Examples of API endpoints for accessing flow interfaces through a specific installation.

```http
/api/flows/{flow-slug}/installations/{installation-id}/interfaces/{interface-id}
```

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

--------------------------------

### Enable a Breyta Flow Installation (CLI)

Source: https://flows.breyta.ai/docs/guide-installations

Enable a configured installation to start accepting manual runs, interface calls, and schedules. This command activates the installation after setup is complete.

```bash
breyta flows installations enable <installation-id>
```

--------------------------------

### Declare Activation Inputs (Setup Form) for a Flow

Source: https://flows.breyta.ai/docs/guide-installations

Declare installation setup inputs using `{:kind :form ...}` within the `:requires` key. These inputs are filled by the installer during setup and reused on later runs. Use `:invocations` for inputs required on each manual run.

```clojure
{:requires [{:kind :form
             :label "API Key"
             :field :apiKey
             :type :string
             :required true}]}
```

--------------------------------

### Install Breyta CLI (Go)

Source: https://flows.breyta.ai/docs/cli-agent-onboarding

Install the Breyta CLI from source using Go.

```bash
go install github.com/breyta/breyta-cli/cmd/breyta@latest
```

--------------------------------

### Inspect Installation Interfaces

Source: https://flows.breyta.ai/docs/breyta-cli-skill-public-flows

After creating and configuring an installation, inspect its callable surfaces using `breyta flows installations interfaces <installation-id>`.

```bash
breyta flows installations interfaces <installation-id>
```

--------------------------------

### Create a Breyta Flow Installation (CLI)

Source: https://flows.breyta.ai/docs/guide-installations

Use this command to create a new installation for a specified Breyta flow. The `--name` flag allows you to assign a descriptive name to the installation.

```bash
breyta flows installations create <flow-slug> --name "My setup"
```

--------------------------------

### Flow Input Structure Example

Source: https://flows.breyta.ai/docs/guide-installations

Illustrates the structure of the input map seen by the flow, combining setup fields and invocation inputs. This example shows a selected region, a text question, and a list of resource references.

```clojure
{:region "EU"
 :question "What changed since last week?"
 :resources [{:type :resource-ref
              :uri "res://v1/ws/ws-1/file/report-a"}
             {:type :resource-ref
              :uri "res://v1/ws/ws-1/result/summary-b"}]}
```

--------------------------------

### Full Agent Configuration Example

Source: https://flows.breyta.ai/docs/reference-step-agent

This example demonstrates the extensive configuration options available for an agent step. Use only the necessary fields for your specific flows.

```clojure
(flow/step :agent :review
  {:connection :ai
   :provider :openai
   :model "gpt-5.2"
   :objective "Review the proposed changes and return JSON findings."
   :instructions "Use tools for facts. Do not speculate."
   :inputs {:draft changeset-ref
            :risk-level "high"}
   :template :agent-review
   :data {:style "concise"}
   :expect {:contains ["findings"]}

   ;; Model/provider controls inherited from :llm.
   :temperature 0.2
   :top-p 0.9
   :stop ["\nDONE"]
   :max-tokens 4000
   :seed 42
   :presence-penalty 0.0
   :frequency-penalty 0.1
   :reasoning-effort :medium
   :prompt-cache-key "review-v1"
   :previous-response-id "resp_previous"
   :cache-system? true
   :provider-opts {:openai {:responses {:store false}}}
   :base-url "https://api.openai.com/v1"
   :deployment "prod-reviewer"
   :api-version "2025-04-01-preview"

   ;; Tools.
   :available-steps [:files :table :search]
   :tools {:mode :execute
           :allowed ["files" "table" "search"]
           :breyta {:allow [:flows/list :runs/show]
                    :mutations :none}
           :steps [:review/publish-changeset]
           :agents [:review/security]
           :require {:tool-names ["files"]
                     :steps [:review/publish-changeset]
                     :agents [:review/security]}
           :max-iterations 8
           :max-tool-calls 80
           :max-repeated-tool-calls 3}
   :max-iterations 20
   :max-tool-calls 100
   :max-repeated-tool-calls 4
   :max-tokens-budget 120000

   ;; Output and post-processing. Prefer Malli schemas in :output :schema.
   :output {:format :json
            :schema [:map
                     [:findings [:vector :string]]
                     [:risk [:enum "low" "medium" "high"]]]
            :style :deterministic
            :strict? true}
   ;; Legacy compatibility fields. Omit these when using :output above unless
   ;; you intentionally want the top-level values to override canonical output.
   :response-format :json
   :json-schema "{\"type\": \"object\"}"
   :output-persist {:type :blob
                    :name "review-report"
                    :content-type "application/json"}

   ;; Agent runtime features.
   :memory {:table memory-table
            :scope :task
            :scope-key "review-42"
            :auto-recall true
            :auto-summarize true
            :recall-limit 20
            :types ["observation" "decision"]
            :plan {:enforce true :max-steps 6 :strict false}}
   :cost {:enabled true
          :budget {:max-tokens-total 500000 :window-hours 720}}
   :evaluate {:criteria [:relevance :completeness :accuracy]
              :model "gpt-4o-mini"
              :persist-to-memory true}
   :approval {:mode :tools :tool-names #{"files" "publish_changeset"}}
   :trace {:name "review-trace"}
   :before-tool-call (fn [{:keys [proposed-tool-calls]}] nil)
   :after-tool-call (fn [{:keys [tool-calls last-results]}] nil)

   ;; Usually prefer :connection over explicit :auth.
   :auth {:type :api-key :header "Authorization" :prefix "Bearer"}
   :workspace-id "ws-runtime-override"
)
```

--------------------------------

### Consumer Installation Loop CLI Commands

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Commands for consumers to create, configure, enable, and inspect installations, and to call interfaces or view metrics for an installation.

```bash
breyta flows installations create <slug> --name "Client API"
```

```bash
breyta flows installations configure <installation-id> --input '{"setup":"value"}'
```

```bash
breyta flows installations enable <installation-id>
```

```bash
breyta flows installations interfaces <installation-id>
```

```bash
breyta flows interfaces call <slug> <http-interface-id> --installation-id <installation-id> --input '{"key":"value"}' --wait
```

```bash
breyta flows metrics <slug> --installation-id <installation-id>
```

--------------------------------

### Install Breyta Skill Bundle Only

Source: https://flows.breyta.ai/docs/cli-skills

Use this command if you only want to install the Breyta skill bundle without creating a workspace. It installs skill files and guidance for the specified provider.

```bash
breyta skills install --provider codex
breyta skills install --provider cursor
breyta skills install --provider claude
breyta skills install --provider gemini

```

--------------------------------

### Example :tool-summary Configuration

Source: https://flows.breyta.ai/docs/reference-step-agent

This example shows the structure of the :tool-summary used to inform the agent about available tools, their operations, and enabled steps. It includes built-in and packaged tools.

```clojure
{:enabled [{:tool :files
            :name "files"
            :description "Inspect, search, diff, and edit existing source-tree and changeset resources."
            :ops ["init-changeset" "list" "read" "search" "write-file" "apply-edit" "replace" "replace-lines" "delete-file" "move-file" "diff"]} 
           {:tool :table
            :name "table"
            :description "Query, aggregate, inspect, export, and mutate bounded table resources."
            :ops ["query" "get-row" "aggregate" "schema" "export" "update-cell" "update-cell-format" "set-column" "recompute" "materialize-join"]} 
           {:tool :breyta
            :name "breyta"
            :description "Call allowed Breyta workspace control-plane operations in the current workspace."
            :ops ["flows/list" "runs/show"]}]
 :enabled-steps [:files :table]
 :missing []}
```

--------------------------------

### Manual Upload Configuration for Installed Flows

Source: https://flows.breyta.ai/docs/guide-installations

Configure manual uploads using resource invocation fields for installed flows. This setup renders a resource picker and local upload action on the installed run page.

```clojure
{:invocations {:default
               {:label "Analyze images"
                :inputs [{:name :images
                          :label "Images"
                          :type :resource
                          :required true
                          :multiple true
                          :accept ["image/*"]}]}}
 :interfaces {:manual [{:id :run
                        :label "Analyze images"
                        :invocation :default
                        :enabled true}]}}
```

--------------------------------

### Install Breyta Skills

Source: https://flows.breyta.ai/docs/cli-agent-onboarding

Use this command to install or refresh the Breyta skill bundle. Specify `--provider all` to install for all providers or a single provider like `--provider codex`.

```bash
breyta skills install --provider all
```

```bash
breyta skills install --provider codex
```

--------------------------------

### Full KV Workflow Example

Source: https://flows.breyta.ai/docs/reference-step-kv

A complete example showing how to build a session key, load history from KV, update it, and save it back with a TTL.

```clojure
{:functions [{:id :session-key
              :language :clojure
              :code "(fn [input]\n                       {:key (str \"session:\" (:session-id input) \":history\")})"}]
 :flow
 '(let [k (flow/step :function :build-session-key
             {:ref :session-key
              :input (flow/input)})
        history (flow/step :kv :load-history
                  {:operation :get
                   :key (:key k)
                   :default []})
        updated (conj history {:at (flow/now-ms)
                               :message \"hello\"})] 
    (flow/step :kv :save-history
      {:operation :set
       :key (:key k)
       :value updated
       :ttl 86400}))}
```

--------------------------------

### Run Breyta Flow Targeting Live Installation

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Explicitly target the live installation runtime for a Breyta flow.

```bash
breyta flows run <slug> --target live
```

--------------------------------

### Create Flow Installation

Source: https://flows.breyta.ai/docs/reference-cli-commands

Creates a new installation for a specified flow slug. Requires a name for the installation.

```bash
breyta flows installations create <flow-slug> --name "..."
```

--------------------------------

### Table Query Column Formatting Examples

Source: https://flows.breyta.ai/docs/guide-output-artifacts

Examples demonstrating how to format specific columns for currency, timestamps, and email addresses within table embeds.

```clojure
{:columns {"amount" {:label "Amount"
                     :format {:display "currency" :currency "USD"}}
           "created-at" {:label "Created"
                         :format {:display "timestamp"}}
           "owner-email" {:label "Owner"
                          :format {:display "email"}}}}
```

--------------------------------

### Install Breyta CLI (macOS Homebrew)

Source: https://flows.breyta.ai/docs/cli-agent-onboarding

Install the Breyta CLI using Homebrew on macOS.

```bash
brew tap breyta/tap
brew install breyta
```

--------------------------------

### Worker Command Example

Source: https://flows.breyta.ai/docs/reference-flow-jobs

Example of how to run a Breyta worker command.

```APIDOC
## Matching worker command:

```bash
export BREYTA_API_URL="https://flows.breyta.ai"
export BREYTA_WORKSPACE="ws-acme"
export BREYTA_API_KEY="<service-account-api-key>"

breyta jobs worker run --type agent-review --handler ./run-agent-review.sh
```
```

--------------------------------

### Configure Installer Schedule Settings via CLI

Source: https://flows.breyta.ai/docs/guide-installations

Set or update an installation's specific schedule settings using the Breyta CLI. This allows installers to customize schedules for their environment.

```bash
breyta flows installations configure <installation-id> \
  --schedules '{"weekly-review":{"enabled":true,"preset":"weekly","timezone":"Europe/Oslo","hour":9,"minute":0,"dayOfWeek":"MON"}}'
```

--------------------------------

### Single Job Example

Source: https://flows.breyta.ai/docs/reference-flow-jobs

Example demonstrating how to submit and await a single job using the `:job` step surface.

```APIDOC
## Single Job Example

```clojure
(let [{:keys [surface mode timeoutSeconds]} (flow/input)
       queued-job (flow/step :job :submit-agent-review
                    {:op :submit
                     :job-type "agent-review"
                     :payload {:surface (or surface "flows-api")
                               :mode (or mode "succeeded")}
                     :metadata {:campaign "agent-review"}})
       final-job (flow/step :job :await-agent-review
                   {:op :await
                    :job-id (:job-id queued-job)
                    :interval "250ms"
                    :timeout (str (long (or timeoutSeconds 60)) "s")})]
   final-job)
```
```

--------------------------------

### Breyta CLI JSON Probe Example

Source: https://flows.breyta.ai/docs/reference-step-breyta

Demonstrates how to use the Breyta CLI to probe operations with JSON parameters. This example shows listing flows with a limit of 5.

```bash
breyta steps run --flow my-flow --source draft --type breyta \
  --params '{"op":"flows/list","allow":["flows/list"],"args":{"limit":5}}'
```

--------------------------------

### Manually Promote Live Installation

Source: https://flows.breyta.ai/docs/cli-essentials

Manually trigger the promotion of a live installation. This command is used when automatic promotion is skipped or needs to be re-initiated.

```bash
breyta flows promote <slug>
```

--------------------------------

### Discover Public Installable Flows

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Browse public installable flows available for the workspace. Supports listing all or searching with a query.

```bash
breyta flows discover list
```

```bash
breyta flows discover search "<query>"
```

--------------------------------

### Sync SSH Execution Example

Source: https://flows.breyta.ai/docs/reference-step-ssh

An example demonstrating how to execute a command synchronously over SSH. The flow will pause until the command completes or times out.

```APIDOC
### Sync exec

```clojure
'(let [res (flow/step :ssh :exec
                      {:title "Run remote command"
                       :connection :vps
                       :command "echo hello; uname -a"
                       :timeout 60})]
   res)

```
```

--------------------------------

### Start and Inspect Breyta Flow Run

Source: https://flows.breyta.ai/docs/operate-runs-and-outputs

Use this command to start a Breyta flow run, wait for it to complete, and then display its details. It's useful for immediate post-change validation.

```bash
breyta flows run <slug> --input '{"n":41}' --wait
```

```bash
breyta runs show <workflow-id> --pretty
```

--------------------------------

### Create, Configure, Enable, and Run an Installation

Source: https://flows.breyta.ai/docs/guide-installations

Demonstrates the CLI commands to create, configure inputs for, enable, and run an end-user flow installation. Use this to verify the full end-user path when browser access is unavailable.

```bash
breyta flows installations create <slug> --name "Smoke install"
breyta flows installations configure <installation-id> --input '{"<field>":"<value>"}'
breyta flows installations enable <installation-id>
breyta flows run <slug> --installation-id <installation-id> --wait
```

--------------------------------

### Get Installation Details

Source: https://flows.breyta.ai/docs/breyta-cli-skill-authoring-loop

Fetches detailed information about a specific flow installation using its installation ID. This includes configuration and status.

```bash
breyta flows installations get <installation-id>
```

--------------------------------

### Full LLM Step Configuration Example

Source: https://flows.breyta.ai/docs/reference-step-llm

Use this comprehensive example when you need to configure all available options for an LLM step. It includes settings for connections, providers, models, input/output formatting, generation controls, tool calling, and provider-specific options.

```clojure
(flow/step :llm :review
  {:connection :ai
   :provider :openai
   :model "gpt-5.2"
   :expect {:contains ["summary"]}

   ;; Input forms. Use one primary form in real flows.
   :input {:system "You are a precise reviewer."
           :prompt "Review {{topic}}."
           :context {:topic "billing"}}
   :messages [{:role "system" :content "You are a precise reviewer."} 
              {:role "user"
               :content [{:type "text" :text "Review this screenshot."} 
                         {:type "image_url"
                          :image_url {:url "https://example.com/screen.png"
                                      :detail "high"}}]}]
   :system "You are concise."
   :prompt "Summarize {{topic}}."
   :template :summary
   :data {:topic "billing"}

   ;; Generation controls.
   :temperature 0.2
   :top-p 0.9
   :stop ["\nDONE"]
   :max-tokens 2000
   :seed 42
   :presence-penalty 0.0
   :frequency-penalty 0.1

   ;; Structured output. Prefer Malli schemas in :output :schema.
   :output {:format :json
            :schema [:map
                     [:summary :string]
                     [:confidence :double]]
            :style :deterministic
            :strict? true}
   ;; Legacy compatibility fields. Omit these when using :output above unless
   ;; you intentionally want the top-level values to override canonical output.
   :response-format :json
   :json-schema "{\"type\": \"object\"}"

   ;; Provider and endpoint controls.
   :provider-opts {:openai {:responses {:store false}}}
   :base-url "https://api.openai.com/v1"
   :deployment "prod-reviewer"
   :api-version "2025-04-01-preview"
   :reasoning-effort :medium
   :prompt-cache-key "summary-v1"
   :previous-response-id "resp_previous"
   :cache-system? true
   :openai {:responses {:tool-choice "required"
                        :store false}}

   ;; Tool calling.
   :available-steps [:files :table :search]
   :tools {:mode :execute
           :allowed ["files" "table" "search"]
           :steps [:github/open-pr]
           :agents [:review/security]
           :require {:tool-names ["files"]
                     :steps [:github/open-pr]
                     :agents [:review/security]}
           :definitions {:custom_tool {:name "custom_tool"
                                       :type :files}}
           :max-iterations 12
           :max-tool-calls 80
           :max-repeated-tool-calls 3}
   :max-iterations 20
   :max-tool-calls 100
   :max-repeated-tool-calls 4

   ;; Usually prefer :connection over explicit :auth.
   :auth {:type :api-key :header "Authorization" :prefix "Bearer"}
   :workspace-id "ws-runtime-override")

```

--------------------------------

### Initialize Breyta with Skill Bundle and Workspace

Source: https://flows.breyta.ai/docs/cli-skills

Run this command to install the Breyta skill bundle and create a local 'breyta-workspace/' with an 'AGENTS.md' file. This is recommended for reliable agent context and follows draft-first release hygiene.

```bash
breyta init --provider codex
breyta init --provider cursor
breyta init --provider claude
breyta init --provider gemini

```

--------------------------------

### Making an HTTP GET Request

Source: https://flows.breyta.ai/docs/reference-step-http

Example of making a GET request to fetch user data with query parameters, custom headers, and retry logic.

```APIDOC
## GET /users

### Description
Fetches a list of users with optional filtering and retry capabilities.

### Method
GET

### Endpoint
/users

### Query Parameters
- **limit** (integer) - Optional - The maximum number of users to return.

### Headers
- **X-Request-Id** (string) - Required - A unique identifier for the request.

### Retry
- **max-attempts** (integer) - The maximum number of retry attempts.
- **backoff-ms** (integer) - The backoff time in milliseconds between retries.
```

--------------------------------

### Define a Form Field for Setup

Source: https://flows.breyta.ai/docs/guide-installations

Example of defining a select field for region in a setup form. This snippet shows how to configure a required field with predefined options.

```clojure
{:requires [{:kind :form
             :label "Setup"
             :fields [{:key :region
                       :label "Region"
                       :field-type :select
                       :required true
                       :options ["EU" "US"]}]}]}
```

--------------------------------

### Define Setup Form Fields

Source: https://flows.breyta.ai/docs/guide-flow-configuration

Use `:requires` with `{:kind :form ...}` to define fields that are entered once during setup and reused. This example shows a select field for region.

```clojure
{:requires [{:kind :form
             :fields [{:key :region
                       :label "Region"
                       :field-type :select
                       :required true
                       :options ["EU" "US"]}]}]}
```

--------------------------------

### Quick Start Breyta CLI Commands

Source: https://flows.breyta.ai/docs/cli-agent-onboarding

Initialize Breyta, log in, list workspaces, and search for flows and templates.

```bash
breyta init --provider <codex|cursor|claude|gemini>
breyta auth login
breyta workspaces list
breyta flows search "<problem keyword>" --limit 5
breyta flows templates search "<problem keyword>" --limit 5
```

--------------------------------

### Start Local Breyta API with Demo Flows

Source: https://flows.breyta.ai/docs/guide-ssh-testing

Starts a local Breyta API instance with demo flows seeded into the 'ws-acme' workspace. Assumes local CLI defaults are set.

```bash
./scripts/start-flows-api.sh --profile=memory --seed --demos

```

--------------------------------

### KV Get Operation Example

Source: https://flows.breyta.ai/docs/reference-step-kv

Demonstrates retrieving a value from KV storage. Use :default to provide a fallback if the key is missing or expired.

```clojure
{:operation :get
 :key "session:123"
 :default []}
```

--------------------------------

### Configure Installer-Owned Schedule Settings

Source: https://flows.breyta.ai/docs/reference-cli-commands

Sets installer-owned schedule settings for setup schedules for a specific flow installation. Schedules are provided as a JSON string.

```bash
breyta flows installations configure <installation-id> --schedules '{...}'
```

--------------------------------

### Get Compact Configuration Overview

Source: https://flows.breyta.ai/docs/playbook-author-flows

Retrieve a concise overview of configuration objects for a specific step type. Use field lookup before opening full references.

```bash
breyta docs fields http
```

--------------------------------

### Breyta CLI Quickstart Sequence

Source: https://flows.breyta.ai/docs/start-here

This sequence covers common Breyta CLI commands for managing skills, searching for flows and templates, pulling, linting, pushing, configuring, validating, and running flows. It's recommended to check skill status and search for relevant resources before proceeding with flow operations. Configuration is necessary for flows requiring specific slots before the first run.

```bash
# Optional for agent sessions; also follow any CLI missing/stale skill warning:
breyta skills status --provider all
breyta docs find "flows" --limit 5 --format json
breyta flows search "<workspace pattern or integration>" --limit 5
breyta flows templates search "<problem keyword>" --limit 5
breyta resources search "<existing report, upload, or run output>" --limit 5
# Reuse/create/test connections up front (recommended when flow uses external systems):
# breyta connections list
# breyta connections create ...
# breyta connections test <connection-id>   # health/config check only; still do a real flow run
breyta flows pull <slug> --out ./tmp/flows/<slug>.clj
breyta flows lint --file ./tmp/flows/<slug>.clj
breyta flows push --file ./tmp/flows/<slug>.clj
# Configure/check before first run when the flow has :requires slots.
# Example:
# breyta flows configure <slug> --set api.conn=conn-...
breyta flows configure check <slug>
# Optional read-only verification (useful for CI/troubleshooting):
breyta flows validate <slug>
breyta flows run <slug> --input '{"name":"Ada"}' --wait
# Open the run Output page returned by the CLI and confirm the final artifact is readable.

```

--------------------------------

### GitHub HMAC-SHA256 Signature Configuration

Source: https://flows.breyta.ai/docs/guide-webhooks-and-secret-refs

Example configuration for authenticating GitHub webhooks using HMAC-SHA256. This setup specifies how to extract the signature from headers and verify the payload.

```clojure
{
:auth {:type :signature
:algo :hmac-sha256
:signature-header "X-Hub-Signature-256"
:signed-message :payload
:signature-format :hex
:signature-prefix "sha256="
:secret-ref :github-webhook-secret}
}

```

--------------------------------

### Reset Installer-Owned Schedule Override

Source: https://flows.breyta.ai/docs/reference-cli-commands

Removes a specific installer-owned schedule override for a flow installation, causing it to inherit the flow's default setup schedule. Use the schedule ID.

```bash
breyta flows installations configure <installation-id> --schedule-reset <schedule-id>
```

--------------------------------

### Example Blob-Storage Effective Root Path

Source: https://flows.breyta.ai/docs/guide-flow-configuration

Illustrates the default effective root path for a blob-storage slot in an end-user installation. This path is used for persisted blob writes and runtime resource pickers.

```text
installations/inst-1/reports
```

--------------------------------

### Manage Connections

Source: https://flows.breyta.ai/docs/guide-cli-workflow

List, create, and test connections to external systems. Use 'create' with appropriate arguments and 'test' with a connection ID.

```bash
breyta connections list
```

```bash
breyta connections create ...
```

```bash
breyta connections test <connection-id>
```

--------------------------------

### Persist Path Modes Example

Source: https://flows.breyta.ai/docs/reference-flow-definition

Illustrates the usage of two blob persist modes: runtime-managed and slot-managed. The runtime-managed mode writes to a default location, while the slot-managed mode writes to a location controlled by installers.

```clojure
{:flow
 '(let [report-a (flow/step :http :download-inline-managed
                   {:connection :reports-api
                    :response-as :bytes
                    :persist {:type :blob
                              :path "exports/{{input.customer-id}}"
                              :filename "summary.pdf"}})
        report-b (flow/step :http :download-slot-managed
                   {:connection :reports-api
                    :response-as :bytes
                    :persist {:type :blob
                              :slot :archive
                              :path "exports/{{input.customer-id}}"
                              :filename "summary.pdf"}})]
    {:runtime-managed (:uri report-a)
     :slot-managed (:uri report-b)})

}
```

--------------------------------

### Breyta CLI for Installation-Specific Interface Calls

Source: https://flows.breyta.ai/docs/reference-flow-definition

Commands to list and call interfaces for a specific installation, and retrieve installation-specific metrics.

```bash
breyta flows installations interfaces <installation-id>
```

```bash
breyta flows interfaces call company-intel enrich-company --installation-id <installation-id> --input '{"domain":"example.com"}' --wait
```

```bash
breyta flows metrics company-intel --installation-id <installation-id>
```

--------------------------------

### Define Customer Sync Worker Requirement

Source: https://flows.breyta.ai/docs/reference-flow-definition

Specify a requirement for external workers, such as a customer sync worker, that are provided by the installer. This includes details like capability, job types, provider, and links to setup documentation.

```clojure
{:requires [{:kind :worker
             :label "Customer sync worker"
             :provided-by :installer
             :capability "customer-sync"
             :job-types ["customer-sync"]
             :provider "acme/customer-sync-worker"
             :setup-summary "Deploy the packaged worker before enabling this installation."
             :setup-docs-url "https://docs.example.com/customer-sync-worker"}]}
```

--------------------------------

### Initialize Breyta Workspace

Source: https://flows.breyta.ai/docs/cli-agent-onboarding

Initialize a new Breyta workspace, specifying the agent provider.

```bash
breyta init --provider <codex|cursor|claude|gemini>
```

--------------------------------

### Inspect Run Events Timeline

Source: https://flows.breyta.ai/docs/playbook-debug-and-verify

Use this command to get a bounded timeline of run and step events for live debugging. Add `--step <step-id>` to focus on a specific step or `--installation-id <id>` when inspecting through an installed profile.

```bash
breyta runs events <workflow-id> --limit 100
```

--------------------------------

### Resolve, Mutate, and Query Repository Files

Source: https://flows.breyta.ai/docs/reference-step-files

This example demonstrates a full workflow: resolving a Git repository, initializing a changeset, performing various file mutations (writing, replacing, replacing lines, moving, deleting), listing files, searching for content, and generating a diff. Use this for complex, multi-step file modifications.

```clojure
(let [repo-tree (flow/step :files :resolve-repo
                   {:op :resolve-source
                    :source {:type :git
                             :repo "https://github.com/acme/service.git"
                             :ref "main"
                             :connection :github-api}})
       draft (flow/step :files :start-draft
               {:op :init-changeset
                :source repo-tree})
       draft (flow/step :files :update-readme
               {:op :write-file
                :changeset draft
                :path "README.md"
                :content "# Updated service\n"})
       draft (flow/step :files :edit-core
               {:op :replace
                :changeset draft
                :path "src/app/core.clj"
                :match "\"ready\""
                :replace "\"steady\""})
       draft (flow/step :files :tighten-guard
               {:op :replace-lines
                :changeset draft
                :path "src/app/core.clj"
                :line-start 10
                :line-end 14
                :expected "(when insecure?\n  (log/warn \"legacy path\")\n  true)"
                :replace "(when insecure?\n  (log/error \"legacy path\")\n  false)"})
       draft (flow/step :files :move-core
               {:op :move-file
                :changeset draft
                :from-path "src/app/core.clj"
                :to-path "src/app/main.clj"})
       draft (flow/step :files :delete-notes
               {:op :delete-file
                :changeset draft
                :path "docs/notes.txt"})
       files (flow/step :files :list-draft
               {:op :list
                :source draft})
       matches (flow/step :files :search-draft
                 {:op :search
                  :source draft
                  :query "persisted-value"})
       diff (flow/step :files :diff-draft
              {:op :diff
               :source draft})] 
   {:files files
   :matches matches
    :diff diff
    :draft draft})
```

--------------------------------

### Create a New Flow Installation

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Creates a new installation for a specified flow slug. You can provide a custom name for the installation.

```bash
breyta flows installations create <flow-slug> --name "My install"
```

--------------------------------

### Update Installation Activation Inputs

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Update the activation inputs for a specific installation. Provide the installation ID and a JSON string for the inputs.

```bash
breyta flows installations configure <installation-id> --input '{"region":"EU"}'
```

--------------------------------

### Use LLM Prompt Template

Source: https://flows.breyta.ai/docs/reference-templates

Example of using a pre-defined LLM prompt template. This step references the `:welcome` template and provides data for the `user.name` variable.

```clojure
(flow/step :llm :welcome-user
  {:connection :ai
   :template :welcome
   :data {:user {:name "Ada"}}})
```

--------------------------------

### CLI: List Database Connections

Source: https://flows.breyta.ai/docs/reference-step-db-sql

Command to list available database connections configured in Breyta.

```bash
breyta connections list --type database
```

--------------------------------

### Persist and search for support bundles

Source: https://flows.breyta.ai/docs/reference-step-search

This example shows how to persist a support bundle with custom search indexing and then search for it using the :search step. It includes options for content type, search text, tags, and label.

```clojure
'(let [bundle (flow/step :function :persist-support-bundle
                {:input {:rows (:rows (flow/input))}
                 :code '(fn [{:keys [rows]}] rows)
                 :persist {:type :blob
                           :path "support/bundles"
                           :filename "refund-bundle.json"
                           :content-type "application/json"
                           :search-index {:text "refund support bundle refunds chargebacks returns"
                                          :tags ["refund" "support" "bundle"]
                                          :source-label "Refund support bundle"
                                          :include-raw-content? true}})
       hits (flow/step :search :find-support-bundle
              {:query "refund support bundle"
               :targets [:resources]
               :limit 5
               :hydrate {:enabled true
                         :top-k 1
                         :max-chars 20000}})]
   {:bundle bundle
    :hits hits})

```

--------------------------------

### App-Owned Source Example with Monetization Plans

Source: https://flows.breyta.ai/docs/guide-paid-public-flows

Defines an application with multiple monetization plans, including subscription, usage-based, and subscription-usage types, each with specific pricing and trial configurations.

```clojure
{:slug :customer-insights
 :name "Customer Insights"
 :tags ["analytics" "customer-insights"]
 :discover {:public true}
 :marketplace
 {:visible true
  :app
  {:app-id "customer-insights-suite"
   :app-name "Customer Insights"
   :app-primary-flow-slug "customer-insights"
   :app-flow-slugs ["customer-insights"]
   :monetization
   {:plans
    [{:plan-id "starter"
      :name "Starter"
      :default true
      :pricing {:type "subscription"
                :amount 29
                :currency "usd"
                :interval "month"}
      :trial {:days 7
              :payment-method-required false}}
     {:plan-id "pro-pack"
      :name "Pro Pack"
      :pricing {:type "usage"
                :amount 49
                :currency "usd"
                :unit "run"
                :included-quantity 250}}
     {:plan-id "metered"
      :name "Metered"
      :pricing {:type "subscription-usage"
                :amount 99
                :currency "usd"
                :interval "month"
                :unit "run"
                :included-quantity 1000}}]}}}
```

--------------------------------

### Declare GitHub API Connection (Installer Provides Token)

Source: https://flows.breyta.ai/docs/reference-step-files

Declare a GitHub API connection as a requirement for installable flows when the installer provides their own GitHub token. This configures the connection details for subsequent use.

```clojure
{:requires [{:slot :github-api
             :type :http-api
             :label "GitHub API"
             :auth {:type :api-key}
             :base-url "https://api.github.com"}]}
```

--------------------------------

### Delete Flow Installation

Source: https://flows.breyta.ai/docs/reference-cli-commands

Deletes a specific flow installation. Use with caution as this action is irreversible.

```bash
breyta flows installations delete <installation-id>
```

--------------------------------

### Example Breyta Operations

Source: https://flows.breyta.ai/docs/reference-step-breyta

Illustrates common Breyta operations with their respective arguments. Use `:target :draft` for testing unreleased flows and `:target :live` or `:installation-id` for released versions.

```clojure
{:op :flows/list
 :args {:limit 20}}
```

```clojure
{:op :flows/show
 :args {:flow-slug :lead-research
        :source :draft
        :include-flow-literal true}}
```

```clojure
{:op :flows/run
 :args {:flow-slug :lead-research
        :target :draft
        :input {:company "Breyta"}}}
```

```clojure
{:op :resources/read
 :args {:uri "res://v1/ws/ws-acme/result/table/tbl_leads"
        :format :json}}
```

--------------------------------

### Check Installed Breyta Skills Status

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Verify the status of all installed Breyta skills across all providers.

```bash
breyta skills status --provider all
```

--------------------------------

### Quick Answer: Breyta CLI Commands for Connections

Source: https://flows.breyta.ai/docs/guide-connections-first

A sequence of Breyta CLI commands to list, create, test, and configure flows with connections. Use this for a rapid setup.

```bash
breyta connections list
breyta connections create --type http-api --name "Orders API" --base-url https://api.example.com
breyta connections test <connection-id>
breyta flows configure suggest <slug>
breyta flows configure <slug> --set orders-api.conn=<connection-id>
breyta flows configure check <slug>
breyta flows run <slug> --wait

```

--------------------------------

### Run with Installation ID

Source: https://flows.breyta.ai/docs/playbook-release-and-install

Run a flow, specifying an installation ID. This is relevant for installation-specific proof and testing.

```bash
breyta flows run <slug> --installation-id <id>
```

--------------------------------

### Group-by Bucket Specification Examples

Source: https://flows.breyta.ai/docs/reference-step-table

Examples of bucket specifications for grouping data by date or numeric bins.

```clojure
;; Group-by bucket spec
{:field :created-at
 :bucket {:op :date-trunc :unit :month}
 :as :created-month}
{:field :amount
 :bucket {:op :numeric-bin :size 10}
 :as :amount-bin}
```

--------------------------------

### Suggest and Configure Flow Wiring

Source: https://flows.breyta.ai/docs/guide-cli-workflow

Suggest configuration wiring for a flow or configure draft/live targets. Use '--set' for specific configurations and '--target' for live environments.

```bash
breyta flows configure suggest <slug>
```

```bash
breyta flows configure <slug> --set api.conn=conn-123 --set activation.region=EU
```

```bash
breyta flows configure <slug> --target live --version <n|latest> --set api.conn=conn-123
```

--------------------------------

### Full Path Example with Storage Root

Source: https://flows.breyta.ai/docs/guide-persisted-results-and-resources

With a storage root of `reports/customer-a`, a persist write using the `:archive` slot lands at `workspaces/<ws>/storage/reports/customer-a/<tenant-id>/<run-date>/summary-<report-id>.pdf`.

```text
workspaces/<ws>/storage/reports/customer-a/<tenant-id>/<run-date>/summary-<report-id>.pdf

```

--------------------------------

### Advanced Install Commands

Source: https://flows.breyta.ai/docs/reference-cli-commands

Commands for managing Breyta flow installations, including listing, creating, configuring, and enabling/disabling them.

```APIDOC
## breyta flows installations list <flow-slug>

### Description
List all installations for a given flow.

### Usage
`breyta flows installations list <flow-slug>`
```

```APIDOC
## breyta flows installations create <flow-slug> --name "..."

### Description
Create a new installation for a flow with a specified name.

### Usage
`breyta flows installations create <flow-slug> --name "<installation-name>"`
```

```APIDOC
## breyta flows installations create <flow-slug> --source-workspace-id <ws> --local-private-test

### Description
For local development only: test a private cross-workspace installation without public visibility.

### Usage
`breyta flows installations create <flow-slug> --source-workspace-id <workspace-id> --local-private-test`
```

```APIDOC
## breyta flows installations get <installation-id>

### Description
Inspect the state of an installation, including `installedVersion`, `latestAvailable`, `updateAvailable`, and `policy`.

### Usage
`breyta flows installations get <installation-id>`
```

```APIDOC
## breyta flows configure <flow-slug> --schedules '{...}'

### Description
Set author-owned schedule defaults for setup schedules of a flow.

### Usage
`breyta flows configure <flow-slug> --schedules '<json-schedule-config>'`
```

```APIDOC
## breyta flows configure <flow-slug> --schedule-enable <schedule-id> / --schedule-disable <schedule-id>

### Description
Toggle the enabled state of an author-owned schedule override for a flow.

### Usage
`breyta flows configure <flow-slug> --schedule-enable <schedule-id>`
`breyta flows configure <flow-slug> --schedule-disable <schedule-id>`
```

```APIDOC
## breyta flows configure <flow-slug> --schedule-reset <schedule-id>

### Description
Remove an author-owned schedule override and revert to the flow's default schedule settings.

### Usage
`breyta flows configure <flow-slug> --schedule-reset <schedule-id>`
```

```APIDOC
## breyta flows installations configure <installation-id> --input '{...}'

### Description
Set installation inputs or configuration for a specific installation.

### Usage
`breyta flows installations configure <installation-id> --input '<json-input-config>'`
```

```APIDOC
## breyta flows installations configure <installation-id> --schedules '{...}'

### Description
Set installer-owned schedule settings for setup schedules of an installation.

### Usage
`breyta flows installations configure <installation-id> --schedules '<json-schedule-config>'`
```

```APIDOC
## breyta flows installations configure <installation-id> --schedule-enable <schedule-id> / --schedule-disable <schedule-id>

### Description
Toggle the enabled state of an installer-owned schedule override for an installation.

### Usage
`breyta flows installations configure <installation-id> --schedule-enable <schedule-id>`
`breyta flows installations configure <installation-id> --schedule-disable <schedule-id>`
```

```APIDOC
## breyta flows installations configure <installation-id> --schedule-reset <schedule-id>

### Description
Remove an installer-owned schedule override and revert to the flow's default schedule settings.

### Usage
`breyta flows installations configure <installation-id> --schedule-reset <schedule-id>`
```

```APIDOC
## breyta flows installations enable <installation-id> / disable <installation-id>

### Description
Enable or pause an installation. Disabled installations reject manual runs, interface calls, and schedules while preserving per-schedule and per-interface settings.

### Usage
`breyta flows installations enable <installation-id>`
`breyta flows installations disable <installation-id>`
```

```APIDOC
## breyta flows installations interfaces <installation-id>

### Description
Show manual/HTTP/webhook/MCP interface surfaces available on the installed flow version.

### Usage
`breyta flows installations interfaces <installation-id>`
```

```APIDOC
## breyta flows installations upload <installation-id> --file <file-path>

### Description
Upload files to an installation's webhook interface.

### Usage
`breyta flows installations upload <installation-id> --file <file-path>`
```

```APIDOC
## breyta flows installations delete <installation-id>

### Description
Delete an installation.

### Usage
`breyta flows installations delete <installation-id>`
```
Tokens:
Raw