AnsibleByExample

Ansible Navigator — Modern CLI for Playbooks and EEs

Beginner
2024-01-013By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Ansible Navigator — Modern CLI for Playbooks and EEs

Introduction

ansible-navigator is a text-based user interface (TUI) for Ansible that replaces ansible-playbook, ansible-doc, ansible-inventory, and ansible-config with a single tool. It runs playbooks inside Execution Environments (EEs) by default and provides interactive exploration of runs, inventory, and documentation.

Install

pip install ansible-navigator

# Verify
ansible-navigator --version

Run Playbooks

# Interactive mode (TUI) — default
ansible-navigator run site.yml

# Stdout mode (like ansible-playbook)
ansible-navigator run site.yml --mode stdout

# With a custom Execution Environment
ansible-navigator run site.yml --eei my-ee:latest

# With extra variables
ansible-navigator run site.yml -e "env=production" --mode stdout

# With inventory
ansible-navigator run site.yml -i inventory/production

Interactive Mode

The TUI provides real-time navigation through playbook execution:

  PLAY NAME              OK CHANGED UNREACHABLE FAILED SKIPPED
0│Deploy webservers       12      3           0      0       2
1│Configure databases      8      1           0      0       0

# Type a number to drill into a play
# :0 → shows tasks in play 0
# :0:2 → shows task 2 details including stdout/stderr
# :back → go up one level
# :quit → exit

Key Subcommands

# Browse Ansible documentation
ansible-navigator doc ansible.builtin.copy

# Explore inventory
ansible-navigator inventory -i hosts.yml

# View collections
ansible-navigator collections

# Check configuration
ansible-navigator config

# Replay a previous run
ansible-navigator replay /tmp/artifact.json

# View images (EEs)
ansible-navigator images

Configuration File

# ansible-navigator.yml (project root)
---
ansible-navigator:
  execution-environment:
    enabled: true
    image: my-ee:latest
    pull:
      policy: missing

  mode: stdout

  playbook-artifact:
    enable: true
    save-as: artifacts/{playbook_name}-{time_stamp}.json

  logging:
    level: warning
    file: /var/log/ansible-navigator.log

  ansible:
    inventories:
      - inventory/production
    config:
      path: ansible.cfg

Stdout vs Interactive Mode

Feature--mode stdout--mode interactive
OutputLike ansible-playbookTUI with navigation
CI/CD✅ Ideal❌ Needs terminal
DebuggingScroll through outputDrill into tasks
ArtifactsOptionalAlways saved

Artifacts and Replay

Every interactive run saves an artifact JSON file. Replay it later:

# Find artifacts
ls artifacts/

# Replay a past run
ansible-navigator replay artifacts/site-2026-05-02T10:30:00.json

# Share with teammates — they can replay without running

Troubleshooting

# Container runtime not found
ansible-navigator --ce docker  # or podman

# EE image pull issues
ansible-navigator images --eei my-ee:latest

# Run without EE (use local ansible)
ansible-navigator run site.yml --ee false

# Verbose execution
ansible-navigator run site.yml -v --mode stdout

Conclusion

ansible-navigator modernizes the Ansible CLI experience — run playbooks in EEs for consistency, drill into task results interactively, and replay past runs for debugging. For CI/CD, use --mode stdout. For development, the interactive TUI is invaluable.

All Tutorials