compose

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

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`

If --branch-on or --case are omitted, the CLI enters interactive mode to collect them.

How it works

Collect inputs

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

Load runbooks

Each case’s YAML file is loaded and validated.

Merge variables

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

Build branches

All case steps are assembled into a single branches step.

Preview and edit

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

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:

Prompts the user for accountType
If "personal" → runs the personal signup steps
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.

Getting Started

Workflow Guides

Use Cases

Support

Web Console

CLI Reference

SDK

Runbook YAML

Concepts

Synopsis

Required arguments

Optional arguments

How it works

Examples

Compose with CLI arguments

Interactive mode

Output structure

​Synopsis

​Required arguments

​Optional arguments

​How it works

​Examples

​Compose with CLI arguments

​Interactive mode

​Output structure

Synopsis

Required arguments

Optional arguments

How it works

Examples

Compose with CLI arguments

Interactive mode

Output structure