> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# compose

> Merge multiple runbooks into a single branching runbook.

## Synopsis

```bash theme={null}
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

| Argument          | Description                               |
| ----------------- | ----------------------------------------- |
| `--output <path>` | Output path for the composed runbook YAML |

## Optional arguments

| Argument                   | Default | Description                                         |
| -------------------------- | ------- | --------------------------------------------------- |
| `--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>`          | `en`    | UI language: `en` or `ja`                           |

<Note>
  If `--branch-on` or `--case` are omitted, the CLI enters interactive mode to collect them.
</Note>

## How it works

<Steps>
  <Step title="Collect inputs">
    The branch variable, cases, and goal are gathered (from CLI args or interactively).
  </Step>

  <Step title="Load runbooks">
    Each case's YAML file is loaded and validated.
  </Step>

  <Step title="Merge variables">
    Variables from all cases are merged. The branch variable is added with `source: prompt`.
  </Step>

  <Step title="Build branches">
    All case steps are assembled into a single `branches` step.
  </Step>

  <Step title="Preview and edit">
    You can preview the composed runbook and make adjustments before saving.
  </Step>

  <Step title="Write output">
    The final YAML is validated with Zod and written to the output path.
  </Step>
</Steps>

## Examples

### Compose with CLI arguments

```bash theme={null}
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

```bash theme={null}
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`:

```yaml theme={null}
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](/yaml/loops-and-branches#branches) for the branch schema.