AAP 2.6 ansible-navigator: Modern CLI for Automation Development

What is ansible-navigator?

ansible-navigator is the modern replacement for ansible-playbook, ansible-doc, ansible-inventory, and ansible-config commands. It provides a text-based user interface (TUI) for interactive exploration and integrates natively with Execution Environments (EEs).

See also: Ansible Automation Platform 2.6 Architecture and Components: Complete Guide

Installation

# RHEL/CentOS/Fedora
sudo dnf install ansible-navigator
# pip install
pip install ansible-navigator
# Verify
ansible-navigator --version

Configuration

ansible-navigator.yml

Create a project-level configuration:

---
ansible-navigator:
  ansible:
    config:
      path: ./ansible.cfg
    inventories:
      - ./inventory/
    playbook: site.yml
execution-environment:
    container-engine: podman
    enabled: true
    image: registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest
    pull:
      policy: missing
    volume-mounts:
      - src: /tmp/secrets/
        dest: /tmp/secrets/
        options: "ro"
logging:
    level: warning
    file: /tmp/ansible-navigator.log
mode: interactive  # or 'stdout' for CI/CD
playbook-artifact:
    enable: true
    save-as: artifacts/{playbook_name}-{time_stamp}.json
color:
    enable: true
    osc4: true

Configuration Hierarchy

Command-line arguments (highest priority) Environment variables (ANSIBLE_NAVIGATOR_*) Project ansible-navigator.yml (in current directory) User ~/.ansible-navigator.yml Defaults

See also: AAP 2.6 Execution Environments: Build, Manage, and Deploy Custom EEs

Running Playbooks

Interactive Mode (TUI)

# Run with TUI
ansible-navigator run site.yml
# With inventory
ansible-navigator run site.yml -i inventory/production
# With extra vars
ansible-navigator run site.yml -e "env=production target=webservers"
# With specific EE
ansible-navigator run site.yml \
  --eei registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest
# With vault
ansible-navigator run site.yml --ask-vault-pass
# Limit hosts
ansible-navigator run site.yml --limit webservers

The TUI shows real-time task execution. Navigate with: • Number keys — drill into specific plays/tasks • :back or Esc — go up a level • :stdout — view raw output • :open — open artifact in editor • :quit or q — exit

Stdout Mode (CI/CD)

# Non-interactive mode for pipelines
ansible-navigator run site.yml --mode stdout
# Equivalent to ansible-playbook
ansible-navigator run site.yml -m stdout -i inventory/production

Exploring Execution Environments

List EE Contents

# Interactive exploration
ansible-navigator images
# View specific image details
ansible-navigator images --eei ee-custom:1.0

The TUI shows: • Image name, tag, and size • Installed collections and versions • Python packages • System packages • Ansible version

Inspect EE

# Non-interactive image info
ansible-navigator images --mode stdout --details \
  --eei registry.redhat.io/ansible-automation-platform-26/ee-supported-rhel9:latest

See also: Ansible Builder & Execution Environments: Complete Guide (2026)

Browsing Collections

# Interactive collection browser
ansible-navigator collections
# View specific collection
ansible-navigator doc ansible.builtin.copy
# List all modules in a collection
ansible-navigator collections --eei ee-custom:1.0

The TUI lets you: Browse all installed collections Drill into modules, roles, plugins Read full documentation with examples Search across collections

Inventory Management

# Interactive inventory browser
ansible-navigator inventory -i inventory/production
# View host details
ansible-navigator inventory -i inventory/production --host webserver01
# List mode
ansible-navigator inventory -i inventory/production --list --mode stdout

Navigate the TUI to explore: • Groups and their members • Host variables • Group variables • Dynamic inventory output

Configuration Inspection

# View effective ansible.cfg settings
ansible-navigator config
# Dump current config
ansible-navigator config dump --mode stdout
# Show only changed settings
ansible-navigator config dump --mode stdout --only-changed

Playbook Artifacts

ansible-navigator saves detailed execution artifacts:

{
  "playbook": "site.yml",
  "status": "successful",
  "duration": 145.2,
  "plays": [
    {
      "name": "Configure web servers",
      "tasks": [
        {
          "name": "Install nginx",
          "action": "ansible.builtin.dnf",
          "host_results": {
            "web01": {"changed": true, "rc": 0},
            "web02": {"changed": false, "rc": 0}
          }
        }
      ]
    }
  ]
}

Replay Artifacts

# Replay a previous run
ansible-navigator replay artifacts/site-2026-04-26.json

This opens the TUI with the saved run, letting you drill into tasks and review results without re-running.

Developer Workflow

Local Development Loop

# 1. Write playbook
vim roles/webserver/tasks/main.yml
# 2. Lint
ansible-navigator lint site.yml --mode stdout
# 3. Run with check mode
ansible-navigator run site.yml --check --diff
# 4. Run for real
ansible-navigator run site.yml
# 5. Review artifact
ansible-navigator replay artifacts/site-latest.json

Working Without EEs

# Disable EE (use local ansible)
ansible-navigator run site.yml --execution-environment false
# or
ansible-navigator run site.yml --ee false

Multiple EE Workflow

# ansible-navigator.yml for multi-EE project
---
ansible-navigator:
  execution-environment:
    enabled: true
    image: ee-base:latest  # Default EE
# Override per playbook:
# ansible-navigator run network.yml --eei ee-network:latest
# ansible-navigator run windows.yml --eei ee-windows:latest
# ansible-navigator run cloud.yml --eei ee-cloud:latest

CI/CD Integration

GitHub Actions

- name: Run Ansible playbook
  run: |
    ansible-navigator run deploy.yml \
      --mode stdout \
      --eei ee-deploy:latest \
      -i inventory/staging \
      -e "version=${{ github.sha }}"

GitLab CI

deploy:
  image: quay.io/ansible/ansible-navigator:latest
  script:
    - ansible-navigator run deploy.yml -m stdout -i inventory/production

Comparison with Legacy Commands

| Legacy Command | Navigator Equivalent | |---------------|---------------------| | ansible-playbook site.yml | ansible-navigator run site.yml | | ansible-doc ansible.builtin.copy | ansible-navigator doc ansible.builtin.copy | | ansible-inventory --list | ansible-navigator inventory --list | | ansible-config dump | ansible-navigator config dump | | ansible-lint | ansible-navigator lint |

Key difference: Navigator runs inside EEs by default, ensuring your development environment matches production AAP.

FAQ

Do I need podman or docker for ansible-navigator?

You need a container runtime (podman or docker) only if using Execution Environments (--ee true, which is the default). Without EEs (--ee false), no container runtime is needed — it uses your local Ansible installation.

Can I use ansible-navigator with AAP?

ansible-navigator is for local development. AAP Controller runs jobs on execution nodes. The benefit: develop locally with the same EE image that AAP uses in production, ensuring consistent behavior.

How do I pass vault passwords?

Use --ask-vault-pass for interactive prompts, --vault-password-file for file-based passwords, or set ANSIBLE_VAULT_PASSWORD_FILE environment variable. These work the same as ansible-playbook.

Why is my playbook slower in navigator?

First run pulls the EE image (can be several GB). Subsequent runs are fast. If consistently slow, the EE might be oversized — build a minimal EE with only required collections.

Can I use custom ansible.cfg with navigator?

Yes. Set ansible.config.path in ansible-navigator.yml or use the ANSIBLE_CONFIG environment variable. The config is mounted into the EE automatically.

Conclusion

ansible-navigator is the standard CLI tool for AAP 2.6 development workflows. Its interactive TUI, EE integration, artifact replay, and collection browser make it far more powerful than the legacy ansible-playbook command. Use it locally to develop and test with the same Execution Environments that run in production AAP.

Related Articles

• AAP 2.6 Execution Environments: Build, Manage, and Deploy Custom EEs • AAP 2.6 Private Automation Hub: Collections and EE Images • AAP 2.6 Architecture and Components: Complete Guide • AAP 2.6 Troubleshooting Guide: Common Issues and Solutions • AAP 2.6 Job Templates and Inventories: Complete Configuration Guide