Overview

Date: 2026-05-11

Time: 15:46

Overview

This is a Phase 1 example script demonstrating FTL2's core automation context manager interface. It shows how to use the automation() async context manager from ftl2 to run modules (file, copy, command) with a clean ftl.module_name() syntax, and covers module restriction, verbose mode, and result tracking.

Usage Patterns

The primary pattern is an async context manager that exposes modules as direct method calls:

from ftl2 import automation

async with automation() as ftl:
    result = await ftl.file(path="/tmp/test.txt", state="touch")
    result = await ftl.command(cmd="echo hello")
    result = await ftl.copy(src="/tmp/a.txt", dest="/tmp/b.txt")

Module results are dicts with keys like changed, stdout. Results are also tracked on ftl.results as objects with .success, .changed, and .module attributes.

Restricting available modules:

async with automation(modules=["file", "copy"]) as ftl:
    # ftl.command() would raise AttributeError

Verbose/debug mode:

async with automation(verbose=True) as ftl:
    ...

API and Configuration

| Parameter | Type | Description |

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

| modules | list[str] | Restrict which modules are available (default: all). Unlisted modules raise AttributeError. |

| verbose | bool | Enable verbose output for debugging. |

Module call signatures shown:

• ftl.file(path=str, state=str) — states include "touch", "directory"
• ftl.copy(src=str, dest=str) — file copy
• ftl.command(cmd=str) — shell command execution

Result dict keys: changed, stdout (for command).

Tracked result attributes: .success, .changed, .module.

Key Behaviors

• All module calls are async — must be awaited.
• The context manager tracks all executions in ftl.results for post-run inspection.
• Module restriction is enforced at the attribute level — calling a disabled module raises AttributeError, not a runtime policy error.
• The available_modules property lists currently enabled modules.
• The script notes FTL2's automation is "250x faster than subprocess execution" — modules run in-process, not via shell.

Relationships

• Imports: ftl2.automation — the core automation context manager.
• Modules used: file, copy, command — these are FTL2 built-in modules exposed as methods on the context object.
• Standalone script — run directly with uv run python examplephase1basic.py. No inventory or host configuration needed (runs locally).
• Part of a series — labeled "Phase 1", implying later phases add inventory, hosts, privilege escalation, or policy features.