Overview

Date: 2026-05-11

Time: 15:47

Overview

This is a Phase 4 example script demonstrating FTL2's check mode (dry run) capability. It shows how to run automation operations without making actual changes, allowing users to preview what would happen before committing. Check mode is a core safety feature for validating automation scripts before execution.

Usage Patterns

Basic check mode — pass check_mode=True to the automation() context manager:

async with automation(check_mode=True) as ftl:
    result = await ftl.file(path="/tmp/test.txt", state="touch")
    # File is NOT actually created

Check mode with verbose output — combine both flags for detailed dry-run feedback:

async with automation(check_mode=True, verbose=True) as ftl:
    await ftl.file(path="/tmp/test.txt", state="touch")
    await ftl.command(cmd="echo 'Hello'")

Validation-then-execute workflow — run check mode first, then execute if no failures:

# Phase 1: Validate
async with automation(check_mode=True) as ftl:
    for module_name, params in operations:
        module_func = getattr(ftl, module_name)
        await module_func(**params)
    failures = [r for r in ftl.results if not r.success]
    if failures:
        return  # abort

# Phase 2: Execute
async with automation(check_mode=False) as ftl:
    for module_name, params in operations:
        module_func = getattr(ftl, module_name)
        await module_func(**params)

Direct context creation — use AutomationContext directly with check mode:

context = AutomationContext(check_mode=True, verbose=True, modules=["file", "command"])
async with context as ftl:
    await ftl.file(path="/tmp/test.txt", state="touch")

API and Configuration

| Parameter | Type | Description |

|-----------|------|-------------|

| check_mode | bool | Enable dry-run mode — operations report what would change without executing |

| verbose | bool | Show detailed output including [CHECK MODE] indicators |

| secrets | list[str] | Environment variable names to load as secrets (works in check mode) |

| modules | list[str] | Restrict available modules (on AutomationContext) |

Result object properties in check mode:

• result.success — whether the operation would succeed
• result.changed — whether the operation would make changes
• result.module — which module was invoked
• result.error — error message if validation failed
• ftl.check_mode — boolean indicating current mode
• ftl.results — list of all accumulated results

Key Behaviors

• Module support varies: Not all modules fully support check mode. Some may still create files or execute commands despite check mode being enabled. The script notes: "Whether the file is created depends on module implementation."
• Results still accumulate: ftl.results collects results from all operations even in check mode, enabling post-run analysis.
• Changed flag: Results include result.changed to indicate what *would* change, useful for diffing expected state.
• Works with all features: Check mode combines with run_on() (remote execution), secrets, and verbose output.
• Validation pattern: The validate-then-execute pattern (Example 6) is the recommended workflow for critical operations — run check mode first, inspect for failures, then execute for real only if validation passes.

Relationships

• Imports: ftl2.automation (context manager), ftl2.AutomationContext (direct context class)
• Modules used: file (touch, directory creation), command (shell commands)
• Features composed with: run_on() for remote/inventory-targeted execution, secrets for credential management, verbose for detailed logging
• Part of: Phase 4 in a progressive example series (implies Phase 1–3 cover earlier concepts)
• Pattern: Uses getattr(ftl, module_name) for dynamic module dispatch — modules are callable attributes on the context object