<Inputs>

The <Inputs> block dynamically renders a web form to collect user input. The collected values can be used by Command, Check, or Template blocks for variable substitution.

Basic Usage

<Inputs id="config">
```yaml
variables:
  - name: ProjectName
    type: string
    description: Name of your project
    validations: "required"
```
</Inputs>

vs. Template

Inputs and Template both render forms to collect variable values, but they have different purposes:

Feature	<Inputs>	<Template>
Collects variables	✓	✓
Generates files	✗	✓
Button text	”Submit"	"Generate”
Use case	Collect values for other blocks	Generate files from templates

Use <Inputs> when you need to collect variable values without generating files. Use <Template> when you need to generate files from a Boilerplate template directory.

Props

Required Props

• id (string) - Unique identifier for this component. Other blocks reference this ID via inputsId to access the collected values.

”Exactly one required” props

You must provide variables using exactly one of the following methods (but not both):

• Inline YAML - Write the variable definitions directly inside the <Inputs> tags in the style of a boilerplate.yml file.
• path (string) - Path to a directory containing a boilerplate.yml file, relative to the runbook.

Optional Props

• prefilledVariables (object) - An object of variable names to values that pre-populate the form fields. These values override any default values defined in the YAML.

Variable Definitions

Variables are defined using the Boilerplate variable syntax.

Declaring variables

There are two ways to declare the variables you want to collect from users. Use exactly one of these, but not both at the same time.

Inline YAML

Define variables directly in the Inputs block:

<Inputs id="user-settings">
```yaml
variables:
  - name: Username
    type: string
    description: Your username
    validations: "required"
  - name: NotifyByEmail
    type: bool
    description: Receive email notifications
    default: true
```
</Inputs>

Loading from Path

Load variables from an external boilerplate.yml file:

<Inputs id="vpc-config" path="templates/vpc" />

This loads variable definitions from templates/vpc/boilerplate.yml relative to your runbook file.

Prefilled Variables

Pre-populate form fields with specific values. These override any default values:

<Inputs
    id="aws-config"
    path="templates/aws-settings"
    prefilledVariables={{
        AwsRegion: "us-west-2",
        Environment: "production"
    }}
/>

Using Variables in Commands and Checks

The primary use case for Inputs is to provide variables to Command and Check blocks. Inputs can also feed other Templates.

Reference by inputsId

<Inputs id="vpc-config">
```yaml
variables:
  - name: VpcName
    type: string
    description: Name for the VPC
  - name: CidrBlock
    type: string
    description: CIDR block for the VPC
    default: "10.0.0.0/16"
```
</Inputs>

<Command
    id="create-vpc"
    command="aws ec2 create-vpc --cidr-block {{ .CidrBlock }} --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value={{ .VpcName }}}]'"
    inputsId="vpc-config"
    title="Create VPC"
    successMessage="VPC {{ .VpcName }} created!"
/>

Reference Multiple Inputs

You can reference multiple Inputs blocks by passing an array of IDs. Variables are merged in order, with later IDs overriding earlier ones:

<Inputs id="global-config">
```yaml
variables:
  - name: Environment
    type: enum
    options: [dev, staging, prod]
    default: dev
```
</Inputs>

<Inputs id="app-config">
```yaml
variables:
  - name: AppName
    type: string
  - name: Port
    type: int
    default: 8080
```
</Inputs>

<Command
    id="deploy"
    path="scripts/deploy.sh"
    inputsId={["global-config", "app-config"]}
    title="Deploy Application"
/>

In this example, the command has access to variables from both Inputs blocks.

Embedded in Command or Check

You can embed Inputs directly inside a Command or Check block:

<Command
    id="greet"
    command='echo "Hello, {{ .Name }}!"'
    title="Say Hello"
>
    <Inputs id="greeting-inputs">
    ```yaml
    variables:
      - name: Name
        type: string
        description: Your name
        validations: "required"
    ```
    </Inputs>
</Command>

When embedded, the Inputs form renders inline within the parent block without a separate submit button. The variables are automatically available to the parent.

Other blocks can still reference embedded Inputs using the standard inputsId pattern.

Sections (Grouping Variables)

Group related variables under section headers using the x-section extension:

variables:
  - name: FunctionName
    type: string
    description: Name of the Lambda function
    x-section: Basic Configuration

  - name: Runtime
    type: enum
    options: [python3.12, nodejs20.x]
    x-section: Basic Configuration

  - name: MemorySize
    type: int
    description: Memory allocation in MB
    default: 128
    x-section: Advanced Settings

  - name: Timeout
    type: int
    description: Timeout in seconds
    default: 30
    x-section: Advanced Settings

Variables with the same x-section value are grouped together in the form under a section header.

Common Use Cases

The <Inputs> block works well for:

• Collecting configuration values: Gather settings that Commands and Checks need
• Reusable variables: Define values once and reference from multiple blocks
• User preferences: Collect environment-specific settings like regions or account names
• Parameterizing scripts: Provide dynamic values to shell scripts

Complete Example

Here’s a complete example showing Inputs used with Check and Command:

# Create a GitHub Repository

Enter your repository settings:

<Inputs id="repo-settings">
```yaml
variables:
  - name: OrgName
    type: string
    description: GitHub organization name
    validations: "required"
  - name: RepoName
    type: string
    description: Repository name
    validations: "required"
  - name: Visibility
    type: enum
    description: Repository visibility
    options:
      - private
      - public
    default: private
```
</Inputs>

First, verify you're authenticated to GitHub:

<Check
    id="check-auth"
    command="gh auth status"
    title="Verify GitHub Authentication"
    successMessage="Authenticated to GitHub!"
    failMessage="Not authenticated. Run 'gh auth login' first."
/>

Now create the repository:

<Command
    id="create-repo"
    command="gh repo create {{ .OrgName }}/{{ .RepoName }} --{{ .Visibility }}"
    inputsId="repo-settings"
    title="Create Repository"
    successMessage="Repository {{ .OrgName }}/{{ .RepoName }} created!"
    failMessage="Failed to create repository"
/>

Verify the repository was created:

<Check
    id="verify-repo"
    command="gh repo view {{ .OrgName }}/{{ .RepoName }}"
    inputsId="repo-settings"
    title="Verify Repository Exists"
    successMessage="Repository verified!"
/>