ansibleTUI/README.md

ansibleTUI

Terminal UI for running Ansible playbooks against a managed inventory. Browse hosts, check drift, apply playbooks, and review run history — without leaving the terminal.

Built with Bubble Tea and Lip Gloss.

Requirements

• Go 1.21+ (to build from source)
• ansible and ansible-playbook on your PATH (e.g. macOS Homebrew, Linux packages, or WSL on Windows)
• git (only if you use git-backed playbooks or inventory)

Install and run

git clone <your-repo-url> ansibleTUI
cd ansibleTUI
go build -o ansibletui .
./ansibletui

Directory layout

Path	Purpose
~/.config/ansibletui/ansibletui.yaml	Application configuration
~/.ansibletui/playbooks/	Default playbooks directory / git clone
~/.ansibletui/inventory/	Default inventory git clone root
~/.ansibletui/inventory/inventory.yml	Default inventory file
~/.ansibletui/runs/	Saved playbook run logs and metadata

Legacy installs may have had ~/.config/ansibletui/config.yaml and runs/ under config; the app migrates these on first launch.

Configuration

See examples/ansibletui.example.yaml for every supported field with comments. For compliance scan runtime tuning and playbook design guidance, see docs/performance.md.

mkdir -p ~/.config/ansibletui
cp examples/ansibletui.example.yaml ~/.config/ansibletui/ansibletui.yaml
# Edit remotes, paths, and enabled flags

If no config exists, the app creates ansibletui.yaml with sensible defaults under ~/.ansibletui/.

Git-backed playbooks and inventory

You can manage two separate git repositories:

• Playbooks — directory of Ansible playbook files
• Inventory — repo containing inventory.yml (or another name via inventory_git.file)

Per-repo settings:

Field	Description
enabled	Use git for this resource
remote	Git remote URL (required when enabled)
branch	Branch to clone / pull / push (default main)
path	Local directory
on_missing	clone — clone from remote; init — git init, initial commit, push
sync_on_startup	Pull (or bootstrap) when the app starts

Without git, set playbook_dir and inventory_path only and leave enabled: false.

Config tab (CFG)

From the home screen, select the CFG sidebar tab:

Key	Action
↑ / ↓	Select playbooks or inventory repo
← / →	Select field (remote, branch, path, …)
e or Enter	Edit focused field (paste git URL into remote)
Esc	Cancel edit
Enter (while editing)	Save field to config
s	Sync (pull / clone) selected repo
S	Push selected repo
t	Toggle enabled for selected repo

Edit ~/.config/ansibletui/ansibletui.yaml directly for remotes, branches, and paths. Host changes write to the inventory file locally; commit and push via S or an external git client.

Home screen shortcuts

Key	Action
↑ / ↓	Move selection
/	Filter servers
a	Add server
e	Edit server
d	Delete server
p	Quick TCP reachability probe
c	Check (check + diff playbook flow)
f	Fix drifted tagged items
r	Apply selected server manually
Enter	Open host drift details (servers panel) or run details (runs panel)
Tab	Cycle SERV / JOBS / CFG
q	Quit

Check / apply flow

1. Choose a playbook from the playbooks directory
2. Choose mode: check, check+diff, or apply
3. Preview the ansible-playbook command
4. Watch live output and recap

Check mode is a dry run. The app passes --check (and optionally --diff) to Ansible. Structured JSONL events are rendered into concise drift findings; changed=1 still means one task would change the host, not that anything was applied. The server list shows drift and a per-host drift count when a check finds would-be changes. Use Apply only when you intend to make real changes.

The Fix shortcut applies only structured drift findings from the latest compliance check. It limits Ansible to the affected host and the tags on the changed task, for example:

ansible-playbook -i inventory.yml site.yml --limit server-a --tags passwordless

For precise fixes, tag driftable tasks with stable item-level tags such as passwordless, packages, or ssh_config. If task tags are not available, Fix falls back to running the mapped compliance playbook against the drifted host.

Compliance mappings can use either simple playbook names or structured entries with tags:

universal:
  - site.yml
  - playbook: site.yml
    tags: [sudo, packages]

Some modules ignore check mode and can still modify the system; prefer idempotent modules or review the playbook.

Inventory format

The TUI reads and writes a YAML inventory compatible with Ansible:

all:
  hosts:
    media01:
      ansible_host: 192.168.1.10
      ansible_user: frank
      ansible_port: 22
  children:
    media:
      hosts:
        media01: null

Migration from older config

If ~/.config/ansibletui/config.yaml exists and ansibletui.yaml does not:

1. Settings are copied to ansibletui.yaml
2. Legacy config is renamed to config.yaml.migrated
3. Run history under ~/.config/ansibletui/runs/ is moved to ~/.ansibletui/runs/ when the new runs dir is empty

Troubleshooting

Issue	What to do
ansible not found in PATH	Install Ansible or run from WSL; ensure ansible-playbook is available
git errors on sync	Check SSH keys / credentials; verify remote URL
Pull fails with diverged history	Resolve conflicts externally; sync uses git pull --ff-only
No playbooks listed	Confirm playbook_dir or playbooks_git.path contains *.yml playbooks at the repo root or one level down (e.g. services/pi-hole.yml); roles/ and group_vars/ are not listed
Path exists but is not a git repository	Remove or rename the directory, or point path elsewhere

Development

go build .
go run .

Design references live under ux/.

License

See repository license (if applicable).