Skip to main content

​
Synopsis

npx @refrainai/cli compose -- \
  --branch-on <varName> \
  --case "match:path.yaml" \
  --output <path> \
  [options]
Merges multiple generated runbooks into a single runbook with conditional branching based on a variable value. Useful when the same workflow has different paths depending on input.

​
Required arguments

ArgumentDescription
--output <path>Output path for the composed runbook YAML

​
Optional arguments

ArgumentDefaultDescription
--branch-on <varName>-Variable name to branch on (interactive if omitted)
--case "match:path.yaml"-Case definition — repeatable for multiple cases
--goal <text>-Goal description for the composed runbook
--locale <code>enUI language: en or ja
If --branch-on or --case are omitted, the CLI enters interactive mode to collect them.

​
How it works

1

Collect inputs

The branch variable, cases, and goal are gathered (from CLI args or interactively).
2

Load runbooks

Each case’s YAML file is loaded and validated.
3

Merge variables

Variables from all cases are merged. The branch variable is added with source: prompt.
4

Build branches

All case steps are assembled into a single branches step.
5

Preview and edit

You can preview the composed runbook and make adjustments before saving.
6

Write output

The final YAML is validated with Zod and written to the output path.

​
Examples

​
Compose with CLI arguments

npx @refrainai/cli compose -- \
  --branch-on accountType \
  --case "personal:./flows/personal-signup.yaml" \
  --case "business:./flows/business-signup.yaml" \
  --goal "Complete signup based on account type" \
  --output ./flows/signup-combined.yaml
This creates a runbook that:
  1. Prompts the user for accountType
  2. If "personal" → runs the personal signup steps
  3. If "business" → runs the business signup steps

​
Interactive mode

npx @refrainai/cli compose -- \
  --output ./flows/combined.yaml
The CLI will interactively ask for the branch variable, cases, and goal.

​
Output structure

The composed runbook contains a single step with branches: 
title: Complete signup based on account type
variables:
  accountType:
    source: prompt
    description: "Branch variable"
    required: true
  # ... merged variables from all cases
steps:
  - ordinal: 0
    description: "Branch based on accountType"
    branches:
      value: "{{accountType}}"
      cases:
        - match: "personal"
          steps:
            # ... steps from personal-signup.yaml
        - match: "business"
          steps:
            # ... steps from business-signup.yaml
See Loops & Branches for the branch schema.