<Check>

The <Check> block runs a shell command or script and reports whether the user’s system is in the expected state. Use it for pre-flight checks before a Command, to validate what a Command did, or as a smoke test at the end of a runbook.

Basic usage

<Check
    id="check-git"
    command="git --version"
    title="Check if Git is installed"
    description="We need Git for version control"
    successMessage="Git is installed!"
    failMessage="Git is not installed. Please install it from https://git-scm.com/"
/>

vs. Command

Check and Command blocks share most of their features. A Check reads the state of the world and validates it. A Command changes it.

A Check has a Check button where a Command has Run. It also accepts a warnMessage and shows exit code 2 as a warning, where a Command shows it as a failure.

Props

Required props

• id (string): unique identifier for this check block

Optional props

• title (string): display title shown in the UI. Supports inline markdown (bold, italic, links, code).
• description (string): longer description of what’s being checked. Supports inline markdown.
• command (string): inline command to execute. Use either this or path.
• path (string): path to a shell script file relative to the runbook. Use either this or command.
• inputsId (string | string[]): ID of an Inputs block to get template variables from. Can be a single ID or an array of IDs. When multiple IDs are provided, variables are merged in order, and later IDs override earlier ones.
• awsAuthId (string): ID of an AwsAuth block for AWS credentials. The credentials are passed as environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION). The Check button is disabled until authentication completes.
• gitAuthId (string): ID of a GitAuth, GitHubAuth or GitLabAuth block, for either provider. Its credentials are passed as environment variables (GITHUB_TOKEN and GITHUB_USER, or GITLAB_TOKEN and GITLAB_USER). The Check button is disabled until authentication completes.
• githubAuthId (string): ID of a GitHubAuth block. GitHub only. The credentials are passed as environment variables (GITHUB_TOKEN, GITHUB_USER). The Check button is disabled until authentication completes. Prefer gitAuthId.
• googleAuthId (string): ID of a GoogleAuth block for Google Cloud credentials. The block’s credentials are passed as environment variables (GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT, GOOGLE_PROJECT, CLOUDSDK_CORE_ACCOUNT, and the region/zone variables), overriding the session environment for this execution only. The Check button is disabled until authentication completes.
• successMessage (string): message shown when the check succeeds. Default “Success”. Supports inline markdown.
• warnMessage (string): message shown on warning. Default “Warning”. Supports inline markdown.
• failMessage (string): message shown when the check fails. Default “Failed”. Supports inline markdown.
• runningMessage (string): message shown while running. Default “Checking…”. Supports inline markdown.
• timeoutMs (number): maximum time, in milliseconds, the script may run before it is killed and the block is marked as failed. Defaults to 3600000 (60 minutes). Lower it so a hung check fails sooner, for example timeoutMs={120000} for a 2-minute probe, or raise it for checks that run longer.
• dependsOn (string | string[]): ID of a Command or Check block, or an array of IDs, that must finish with a success or a warning before this block can run. See Run order.
• exclusive (boolean): whether this block runs alone. Defaults to false. While it runs, no other Command or Check block can start, and it can’t start while another one is running. See Run order.

Inline content

You can nest an <Inputs> component directly inside the Check:

<Check
    id="check-s3-bucket"
    path="checks/s3-bucket-exists.sh"
    title="Verify S3 Bucket Exists"
>
    <Inputs id="bucket-config">
    ```yaml
    variables:
      - name: BucketName
        type: string
        description: Name of the S3 bucket to check
        validations:
          - required
    ```
    </Inputs>
</Check>

The embedded <Inputs> renders inside the Check block, so users fill in variables before running the check. Other blocks can reference it by inputsId like any standalone Inputs block.

Writing scripts

Scripts can be defined inline with the command prop or stored in external files referenced by the path prop.

Defining scripts

Inline scripts

For simple checks, define the script directly in the command prop:

<Check
    id="check-git"
    command="git --version"
    title="Check if Git is installed"
    successMessage="Git is installed!"
    failMessage="Git is not installed."
/>

Inline scripts suit one-liners. For anything longer, use an external script file.

External scripts

<Check
    id="check-aws-auth"
    path="checks/aws-authenticated.sh"
    title="Verify AWS Authentication"
    description="Checking if you're authenticated to AWS"
    successMessage="AWS credentials are valid!"
    failMessage="AWS authentication failed. Run 'aws configure' to set up credentials."
/>

External scripts are plain bash scripts. The referenced checks/aws-authenticated.sh might look like:

#!/bin/bash

log_info "Checking AWS authentication..."

if aws sts get-caller-identity &>/dev/null; then
    log_info "AWS credentials are valid"
    exit 0
else
    log_error "Not authenticated to AWS"
    exit 1
fi

If you edit the script file while the runbook is open, the block shows a “Script changed” notice with the diff and keeps running the version it loaded. Click Reload script in the notice to run the new version. See Reloading a changed script file.

Exit codes

Exit code	Result
0	Success (green), with successMessage
2	Warning (yellow), with warnMessage
Anything else	Failure (red), with failMessage

A script killed by timeoutMs is a failure.

Logging

Check scripts get the same log_info, log_warn, log_error and log_debug functions and log files as Command scripts. See Logging in the Command block docs, including Log files and Local development.

With variables

A Check takes variables the same way a Command does: from inputsId, from several inputsId values, or from a nested <Inputs>. Reference a value as {{ .inputs.VariableName }} in the command, the script, or the message props.

<Inputs id="region-config">
```yaml
variables:
  - name: AwsRegion
    type: string
    description: AWS region to check
    default: us-east-1
```
</Inputs>

<Check
    id="check-region"
    command='aws ec2 describe-availability-zones --region "{{ .inputs.AwsRegion }}"'
    inputsId="region-config"
    title="Check AWS Region Accessibility"
    successMessage="Region {{ .inputs.AwsRegion }} is accessible!"
    failMessage="Cannot access region {{ .inputs.AwsRegion }}"
/>

See With variables in the Command block docs for merging several Inputs blocks, and How values are inserted for quoting and for passing {{ }} through to another tool.

Execution context

Check scripts run in the same persistent, non-interactive shell environment as Command scripts. A check that exits 0 or 2 carries its export, unset and cd changes forward to later blocks. See Execution context.

Examples

Basic validation script

checks/tofu-installed.sh

#!/bin/bash
log_info "Checking for OpenTofu installation..."

if command -v tofu &> /dev/null; then
    log_info "OpenTofu is installed: $(tofu version | head -1)"
    exit 0
else
    log_error "OpenTofu is not installed"
    exit 1
fi

Script with warning

checks/disk-space.sh

#!/bin/bash
log_info "Checking available disk space..."
available=$(df -h / | awk 'NR==2 {print $4}' | sed 's/G//')
log_debug "Available space: ${available}GB"

if [ "$available" -lt 1 ]; then
    log_error "Less than 1GB available"
    exit 1
elif [ "$available" -lt 5 ]; then
    log_warn "Less than 5GB available"
    exit 2
else
    log_info "Disk space OK: ${available}GB available"
    exit 0
fi

Parameterized script

checks/s3-bucket-exists.sh

#!/bin/bash
BUCKET_NAME="{{ .inputs.BucketName }}"

log_info "Checking if S3 bucket exists..."
log_debug "Bucket name: ${BUCKET_NAME}"

if aws s3 ls "s3://${BUCKET_NAME}" &> /dev/null; then
    log_info "Bucket ${BUCKET_NAME} exists"
    exit 0
else
    log_error "Bucket ${BUCKET_NAME} does not exist"
    exit 1
fi

Viewing logs

A check’s output streams into the same View Logs panel as a command’s. See Viewing logs.

Block outputs

A check script can write key=value pairs to the $RUNBOOK_OUTPUT file, and later blocks reference them as {{ .outputs.<block-id>.<key> }}:

#!/bin/bash
# Verify an account and output its ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
echo "account_id=$ACCOUNT_ID" >> "$RUNBOOK_OUTPUT"

A Check that references another block’s outputs keeps its Check button disabled, and names the blocks that need to run first, until those outputs exist. The button is also disabled while the upstream block is running again. See Run order.

See Block outputs in Inputs and outputs. The block-outputs feature demo includes a Check that consumes outputs from upstream Command blocks.

Capturing output files

A check script can write to $GENERATED_FILES and read or modify $REPO_FILES the same way a command script does. Files in $GENERATED_FILES are captured when the check exits 0 or 2, so a check that ends in a warning still keeps its files. See Capturing output files.

A check more often reads $REPO_FILES than writes to it:

#!/bin/bash
# Validate a config file in the cloned repo
if [ -z "${REPO_FILES:-}" ]; then
    log_error "No git worktree available. Clone a repo first."
    exit 1
fi

if [ -f "$REPO_FILES/terragrunt.hcl" ]; then
    log_info "Found terragrunt.hcl"
    exit 0
else
    log_error "Missing terragrunt.hcl"
    exit 1
fi