Overview

Date: 2026-05-11

Time: 15:33

Overview

This is the main entry point for FTL2 automation scripts — the automation() async context manager. It wraps AutomationContext in a clean async with pattern, giving users ftl.module_name() syntax to call automation modules. Every FTL2 script starts here. The context manager handles setup (module discovery, inventory loading, vault secrets, policy loading, state recovery) and teardown (summary printing, audit recording, state persistence).

Usage Patterns

The primary pattern is always an async context manager:

import asyncio
from ftl2.automation import automation

async def main():
    async with automation() as ftl:
        await ftl.file(path="/tmp/test", state="directory")
        await ftl.copy(src="config.yml", dest="/etc/app/config.yml")

asyncio.run(main())

Remote execution requires an inventory file:

async with automation(inventory="hosts.yml") as ftl:
    await ftl.run_on("webservers", "file", path="/var/www", state="directory")

Namespaced modules use dot-access:

async with automation() as ftl:
    await ftl.community.general.slack(channel="#deploy", msg="Done!")

Secrets are loaded from env vars or HashiCorp Vault:

async with automation(secrets=["API_TOKEN"]) as ftl:
    token = ftl.secrets["API_TOKEN"]

# Or from Vault:
async with automation(vault_secrets={"DB_PW": "myapp#db_password"}) as ftl:
    pw = ftl.secrets["DB_PW"]

Check mode (dry run):

async with automation(check_mode=True) as ftl:
    await ftl.file(path="/tmp/test", state="absent")  # reports only, no changes

API and Configuration

| Parameter | Type | Default | Purpose |

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

| modules | list[str] | None (all) | Restrict which modules can be called |

| inventory | str | None (localhost) | Path to inventory YAML file |

| secrets | list[str] | None | Env var names to load as secrets |

| secret_bindings | dict | None | Auto-inject secrets into modules by pattern |

| check_mode | bool | False | Dry-run mode |

| verbose | bool | False | Show per-module execution output with timing |

| quiet | bool | False | Suppress all output (overrides verbose) |

| onevent | EventCallback | None | Callback for structured events (modulestart, module_complete) |

| fail_fast | bool | False | Raise AutomationError on first failure |

| print_summary | bool | True | Print per-host summary on exit |

| print_errors | bool | True | Print error summary on exit |

| autoinstalldeps | bool | False | Auto-install missing Python deps via uv |

| record_deps | bool | False | Record module dependencies to file |

| deps_file | str | .ftl2-deps.txt | Dependency output file |

| modules_file | str | .ftl2-modules.txt | Module names output file |

| gatemodules | list[str]\|str | None | Modules to bake into gate; "auto" reads from modulesfile |

| gate_subsystem | bool | False | Register gate as SSH subsystem (requires root) |

| state_file | str | .ftl2-state.json | Persistent state for crash recovery; None to disable |

| record | str | None | Path for audit trail JSON |

| replay | str | None | Path to previous audit JSON for resume-from-failure |

| vault_secrets | dict | None | Vault KV v2 refs in "path#field" format |

| policy | str | None | Path to YAML policy file |

| environment | str | "" | Environment label for policy matching |

| policy_audit | str | None | JSON-lines file for streaming policy audit events |

| ignoremissinginventory | bool | True | Don't error on missing inventory file |

Vault env vars required: VAULTADDR and VAULTTOKEN when using vault_secrets.

Key Behaviors

• Error handling has two modes: By default (failfast=False), errors are collected in ftl.errors and execution continues. With failfast=True, the first failure raises AutomationError immediately.
• Module restriction: Passing modules=["file", "copy"] means calling any other module raises AttributeError.
• Secret bindings use glob patterns for module names (e.g., "amazon.aws.*") — secrets are injected automatically so scripts never see actual credential values.
• Replay matching is positional — it replays by action order, not by content. Previously successful actions return cached output; execution resumes from the first unmatched or failed action.
• State file enables crash recovery: add_host() persists immediately, and hosts reload from state on next run.
• Policy audit is crash-safe — events are appended as JSON lines immediately after evaluation.
• Gate modules eliminate per-task module transfer overhead for remote execution. Using gate_modules="auto" records on first run and reads from file on subsequent runs.
• Performance: In-process module execution is stated as 250x faster than subprocess-based Ansible.

Relationships

• Wraps: AutomationContext from ftl2.automation.context — all the real logic lives there.
• Proxy classes: ModuleProxy, NamespaceProxy, HostScopedProxy, HostScopedModuleProxy from ftl2.automation.proxy — these enable the ftl.module_name() and ftl.namespace.module() attribute-access syntax.
• Types re-exported: AutomationError, EventCallback, OutputMode — available from the top-level ftl2.automation import.
• External integrations: HashiCorp Vault (via vault_secrets), SSH (via gate system), inventory files (YAML), policy engine (YAML policy files).
• File artifacts produced: .ftl2-state.json (state), .ftl2-deps.txt (deps), .ftl2-modules.txt (modules), audit JSON, policy audit JSON-lines.