examples-README

Overview

Date: 2026-05-11

Time: 15:19

Overview

The FTL2 Examples page provides a guided tour of FTL2's capabilities through five progressive examples, covering local execution, remote SSH, multi-host deployments, FTL modules (in-process Python execution), and event streaming. It includes prerequisites, common commands, troubleshooting, and a recommended learning path for new users.

Key Concepts

FTL2 is a Python automation framework similar to Ansible, executing modules on local and remote systems via SSH.
Examples are progressive: local → single remote host → multi-host → FTL modules → event streaming.
FTL modules execute as in-process Python (claimed 250x faster than subprocess execution), with support for remote async SSH execution, bundle building, and caching.
Gate zipapp mechanism is used for remote execution — pre-built bundles sent to remote hosts.
Inventory is YAML-based, supporting host groups (e.g., webservers, databases), group variables, and pattern matching.
Parallel execution is supported across multiple hosts.
Event streaming provides real-time progress events, rich progress bars, and event callbacks.
Docker/Colima is used to create test environments for remote and multi-host examples.
Output format: JSON results per host with SUCCESS/FAILED status, changed boolean, and rc return codes.
Security warning: examples use simplified security (password auth, disabled host key checking) not suitable for production.

Commands and Syntax

Installation


cd /path/to/faster-than-light2
python -m venv .venv
source .venv/bin/activate
pip install -e .
ftl2 --version

Core CLI Commands


ftl2 -m ping -i inventory.yml                         # Ping hosts
ftl2 -m setup -i inventory.yml                        # Gather system facts
ftl2 -m shell -i inventory.yml -a "cmd='whoami'"      # Run shell command
ftl2 -m file -i inventory.yml -a "path=/tmp/test state=touch"  # Create file
ftl2 -m copy -i inventory.yml -a "src=/local/file dest=/remote/file"  # Copy file

Host Targeting


ftl2 -m ping -i inventory.yml --limit webservers      # Target group
ftl2 -m ping -i inventory.yml --limit web01            # Target host
ftl2 -m ping -i inventory.yml --limit "web*"           # Pattern match
ftl2 -m ping -i inventory.yml --limit "!databases"     # Exclude hosts

FTL Module Execution (Python API)


uv run python example_local.py
uv run python example_remote.py

Docker Environment Management


./setup.sh start | stop | status | logs | restart

Relationships

Inventory management — examples demonstrate YAML inventory with groups, host vars, and patterns.
Module usage — covers core modules (ping, setup, file, shell, copy) and FTL modules (in-process).
Gate modules — the gate zipapp mechanism appears in remote SSH examples for pre-building remote execution bundles.
Event streaming — connects to real-time progress tracking and callbacks, relevant to building applications on FTL2.
Vault/secrets — production security section references secrets management (Vault) as a next step beyond example patterns.
Migration from Ansible — FTL2 is described as "similar to Ansible," and the CLI syntax (-m, -i, -a, --limit) mirrors Ansible's.

Exam-Relevant Points

FTL2 requires Python 3.11+.
The CLI flag pattern is -m <module> -i <inventory> -a "<args>".
The --limit flag supports group names, host names, glob patterns (web*), and exclusion (!databases).
Module argument syntax uses key=value pairs: -a "path=/tmp/test state=touch".
FTL modules are 250x faster because they run as in-process Python rather than subprocess execution.
Output JSON includes changed (boolean) and rc (return code, non-zero = failure).
The five example categories in order: local execution, remote SSH, multi-host, FTL modules, event streaming.
Production security requirements: SSH key auth, strict host key checking, unique credentials per host, secrets management, audit logging, bastion hosts.
Docker/Colima is the test environment; setup.sh manages container lifecycle.
uv run python is used to execute FTL module Python scripts (not the ftl2 CLI).