ansible-navigator settings

The ansible-navigator settings file

Settings for ansible-navigator can be provided on the command line, set using an environment variable or specified in a settings file.

The settings file name and path can be specified with an environment variable or it can be placed in one of two default directories.

Currently the following are checked and the first match is used:

  • ANSIBLE_NAVIGATOR_CONFIG (settings file path environment variable if set)

  • ./ansible-navigator.<ext> (project directory) (NOTE: no dot in the file name)

  • ~/.ansible-navigator.<ext> (home directory) (NOTE: note the dot in the file name)

Note

  • The settings file can be in JSON or YAML format.

  • For settings in JSON format, the extension must be .json.

  • For settings in YAML format, the extension must be .yml or .yaml.

  • The project and home directories can only contain one settings file each.

  • If more than one settings file is found in either directory, it will result in an error.

You can copy the example settings file below into one of those paths to start your ansible-navigator settings file.

# # cspell:ignore cmdline, workdir
---
ansible-navigator:
#
#   ansible:
#     config:
#       help: False
#       path: /tmp/ansible.cfg
#     cmdline: "--forks 15"
#     doc:
#       help: False
#       plugin:
#         name: shell
#         type: become
#     inventory:
#       help: False
#       entries:
#         - /tmp/test_inventory.yml
#     playbook:
#       help: False
#       path: /tmp/test_playbook.yml
#
#   ansible-builder:
#     help: False
#     workdir: /tmp/
#
#   ansible-lint:
#     config: ~/ansible-lint.yml
#     lintables: ~/myproject/
#
#   ansible-runner:
#     artifact-dir: /tmp/test1
#     rotate-artifacts-count: 10
#     timeout: 300
#
#   app: run
#
#   collection-doc-cache-path: /tmp/cache.db
#
#   color:
#     enable: False
#     osc4: False
#
#   editor:
#     command: vim_from_setting
#     console: False
#
#   exec:
#     shell: False
#     command: /bin/foo
#
#   execution-environment:
#     container-engine: podman
#     enabled: False
#     environment-variables:
#       pass:
#         - ONE
#         - TWO
#         - THREE
#       set:
#         KEY1: VALUE1
#         KEY2: VALUE2
#         KEY3: VALUE3
#     image: test_image:latest
#     pull:
#       arguments:
#         - "--tls-verify=false"
#       policy: never
#     volume-mounts:
#       - src: "/tmp"
#         dest: "/test1"
#         options: "Z"
#     container-options:
#       - "--net=host"
#
#   format: json
#
#   images:
#     details:
#       - ansible_version
#       - python_version
#
#   inventory-columns:
#     - ansible_network_os
#     - ansible_network_cli_ssh_type
#     - ansible_connection
#
  logging:
    level: critical
#     append: False
#     file: /tmp/log.txt
#
#   mode: stdout
#
#   playbook-artifact:
#     enable: True
#     replay: /tmp/test_artifact.json
#     save-as: /tmp/test_artifact.json
#
#   settings:
#     effective: False
#     sample: False
#     schema: json
#     sources: False
#
#   time-zone: Japan

The following table describes all available settings.

General parameters

Name

Description

Settings

ansible-runner-artifact-dir

The directory path to store artifacts generated by ansible-runner
Added in version: v1.0
Default: No default value set
CLI: --rad or --ansible-runner-artifact-dir
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ARTIFACT_DIR
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
artifact-dir:

ansible-runner-rotate-artifacts-count

Keep ansible-runner artifact directories, for last n runs, if set to 0 artifact directories won’t be deleted
Added in version: v1.0
Default: No default value set
CLI: --rac or --ansible-runner-rotate-artifacts-count
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ROTATE_ARTIFACTS_COUNT
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
rotate-artifacts-count:

ansible-runner-timeout

The timeout value after which ansible-runner will forcefully stop the execution
Added in version: v1.0
Default: No default value set
CLI: --rt or --ansible-runner-timeout
ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_TIMEOUT
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-runner:
timeout:

app

Subcommands
Added in version: v1.0
Choices: ‘builder’, ‘collections’, ‘config’, ‘doc’, ‘exec’, ‘images’, ‘inventory’, ‘lint’, ‘replay’, ‘run’, ‘settings’ or ‘welcome’
Default: welcome
CLI: positional
ENV: ANSIBLE_NAVIGATOR_APP
Settings file:

.. code-block:: yaml

ansible-navigator:
app:

cmdline

Extra parameters passed to the corresponding command
Added in version: v1.0
Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_CMDLINE
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
cmdline:

collection-doc-cache-path

The path to collection doc cache
Added in version: v1.0
Default: ~/.cache/ansible-navigator/collection_doc_cache.db
CLI: --cdcp or --collection-doc-cache-path
ENV: ANSIBLE_NAVIGATOR_COLLECTION_DOC_CACHE_PATH
Settings file:

.. code-block:: yaml

ansible-navigator:
collection-doc-cache-path:

container-engine

Specify the container engine (auto=podman then docker)
Added in version: v1.0
Choices: ‘auto’, ‘podman’ or ‘docker’
Default: auto
CLI: --ce or --container-engine
ENV: ANSIBLE_NAVIGATOR_CONTAINER_ENGINE
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
container-engine:

container-options

Extra parameters passed to the container engine command
Added in version: v2.0
Default: No default value set
CLI: --co or --container-options
ENV: ANSIBLE_NAVIGATOR_CONTAINER_OPTIONS
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
container-options:

display-color

Enable the use of color for mode interactive and stdout
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --dc or --display-color
ENV: NO_COLOR
Settings file:

.. code-block:: yaml

ansible-navigator:
color:
enable:

editor-command

Specify the editor command
Added in version: v1.0
Default: vi +{line_number} {filename}
CLI: --ecmd or --editor-command
ENV: ANSIBLE_NAVIGATOR_EDITOR_COMMAND
Settings file:

.. code-block:: yaml

ansible-navigator:
editor:
command:

editor-console

Specify if the editor is console based
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --econ or --editor-console
ENV: ANSIBLE_NAVIGATOR_EDITOR_CONSOLE
Settings file:

.. code-block:: yaml

ansible-navigator:
editor:
console:

execution-environment

Enable or disable the use of an execution environment
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --ee or --execution-environment
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
enabled:

execution-environment-image

Specify the name of the execution environment image
Added in version: v1.0
Default: None
CLI: --eei or --execution-environment-image
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_IMAGE
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
image:

execution-environment-volume-mounts

Specify volume to be bind mounted within an execution environment (–eev /home/user/test:/home/user/test:Z)
Added in version: v1.0
Default: No default value set
CLI: --eev or --execution-environment-volume-mounts
ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
volume-mounts:

log-append

Specify if log messages should be appended to an existing log file, otherwise a new log file will be created per session
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --la or --log-append
ENV: ANSIBLE_NAVIGATOR_LOG_APPEND
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
append:

log-file

Specify the full path for the ansible-navigator log file
Added in version: v1.0
Default: ./ansible-navigator.log
CLI: --lf or --log-file
ENV: ANSIBLE_NAVIGATOR_LOG_FILE
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
file:

log-level

Specify the ansible-navigator log level
Added in version: v1.0
Choices: ‘debug’, ‘info’, ‘warning’, ‘error’ or ‘critical’
Default: warning
CLI: --ll or --log-level
ENV: ANSIBLE_NAVIGATOR_LOG_LEVEL
Settings file:

.. code-block:: yaml

ansible-navigator:
logging:
level:

mode

Specify the user-interface mode
Added in version: v1.0
Choices: ‘stdout’ or ‘interactive’
Default: interactive
CLI: -m or --mode
ENV: ANSIBLE_NAVIGATOR_MODE
Settings file:

.. code-block:: yaml

ansible-navigator:
mode:

osc4

Enable or disable terminal color changing support with OSC 4
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --osc4 or --osc4
ENV: ANSIBLE_NAVIGATOR_OSC4
Settings file:

.. code-block:: yaml

ansible-navigator:
color:
osc4:

pass-environment-variable

Specify an existing environment variable to be passed through to and set within the execution environment (–penv MY_VAR)
Added in version: v1.0
Default: No default value set
CLI: --penv or --pass-environment-variable
ENV: ANSIBLE_NAVIGATOR_PASS_ENVIRONMENT_VARIABLES
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
environment-variables:
pass:

pull-arguments

Specify any additional parameters that should be added to the pull command when pulling an execution environment from a container registry. e.g. –pa=’–tls-verify=false’
Added in version: v2.0
Default: No default value set
CLI: --pa or --pull-arguments
ENV: ANSIBLE_NAVIGATOR_PULL_ARGUMENTS
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
pull:
arguments:

pull-policy

Specify the image pull policy always:Always pull the image, missing:Pull if not locally available, never:Never pull the image, tag:if the image tag is ‘latest’, always pull the image, otherwise pull if not locally available
Added in version: v1.0
Choices: ‘always’, ‘missing’, ‘never’ or ‘tag’
Default: tag
CLI: --pp or --pull-policy
ENV: ANSIBLE_NAVIGATOR_PULL_POLICY
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
pull:
policy:

set-environment-variable

Specify an environment variable and a value to be set within the execution environment (–senv MY_VAR=42)
Added in version: v1.0
Default: No default value set
CLI: --senv or --set-environment-variable
ENV: ANSIBLE_NAVIGATOR_SET_ENVIRONMENT_VARIABLES
Settings file:

.. code-block:: yaml

ansible-navigator:
execution-environment:
environment-variables:
set:

time-zone

Specify the IANA time zone to use or ‘local’ to use the system time zone
Added in version: v2.0
Default: UTC
CLI: --tz or --time-zone
ENV: TZ
Settings file:

.. code-block:: yaml

ansible-navigator:
time-zone:


Subcommand: builder

Name

Description

Settings

help-builder

Help options for ansible-builder command in stdout mode
Added in version: v2.0
Choices: ‘True’ or ‘False’
Default: False
CLI: --hb or --help-builder
ENV: ANSIBLE_NAVIGATOR_HELP_BUILDER
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-builder:
help:

workdir

Specify the path that contains ansible-builder manifest files
Added in version: v2.0
Default: .
CLI: --bwd or --workdir
ENV: ANSIBLE_NAVIGATOR_WORKDIR
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-builder:
workdir:

Subcommand: collections

Name

Description

Settings

format

Specify the format for stdout output.
Added in version: v2.3
Choices: ‘json’ or ‘yaml’
Default: yaml
CLI: --fmt or --format
ENV: ANSIBLE_NAVIGATOR_FORMAT
Settings file:

.. code-block:: yaml

ansible-navigator:
format:

Subcommand: config

Name

Description

Settings

config

Specify the path to the ansible configuration file
Added in version: v1.0
Default: No default value set
CLI: -c or --config
ENV: ANSIBLE_CONFIG
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
config:
path:

help-config

Help options for ansible-config command in stdout mode
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: False
CLI: --hc or --help-config
ENV: ANSIBLE_NAVIGATOR_HELP_CONFIG
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
config:
help:

Subcommand: doc

Name

Description

Settings

help-doc

Help options for ansible-doc command in stdout mode
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: False
CLI: --hd or --help-doc
ENV: ANSIBLE_NAVIGATOR_HELP_DOC
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
doc:
help:

plugin-name

Specify the plugin name
Added in version: v1.0
Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLUGIN_NAME
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
doc:
plugin:
name:

plugin-type

Specify the plugin type, ‘become’, ‘cache’, ‘callback’, ‘cliconf’, ‘connection’, ‘httpapi’, ‘inventory’, ‘lookup’, ‘module’, ‘netconf’, ‘shell’, ‘strategy’ or ‘vars’
Added in version: v1.0
Choices: ‘become’, ‘cache’, ‘callback’, ‘cliconf’, ‘connection’, ‘httpapi’, ‘inventory’, ‘lookup’, ‘module’, ‘netconf’, ‘shell’, ‘strategy’ or ‘vars’
Default: module
CLI: -t or --type
ENV: ANSIBLE_NAVIGATOR_PLUGIN_TYPE
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
doc:
plugin:
type:

Subcommand: exec

Name

Description

Settings

exec-command

Specify the command to run within the execution environment
Added in version: v2.0
Default: /bin/bash
CLI: positional
ENV: ANSIBLE_NAVIGATOR_EXEC_COMMAND
Settings file:

.. code-block:: yaml

ansible-navigator:
exec:
command:

exec-shell

Specify the exec command should be run in a shell
Added in version: v2.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --exshell or --exec-shell
ENV: ANSIBLE_NAVIGATOR_EXEC_SHELL
Settings file:

.. code-block:: yaml

ansible-navigator:
exec:
shell:

Subcommand: images

Name

Description

Settings

images-details

Provide detailed information about the selected execution environment image
Added in version: v2.0
Choices: ‘ansible_collections’, ‘ansible_version’, ‘everything’, ‘os_release’, ‘python_packages’, ‘python_version’, ‘redhat_release’ or ‘system_packages’
Default: [‘everything’]
CLI: -d or --details
ENV: ANSIBLE_NAVIGATOR_IMAGES_DETAILS
Settings file:

.. code-block:: yaml

ansible-navigator:
images:
details:

Subcommand: inventory

Name

Description

Settings

help-inventory

Help options for ansible-inventory command in stdout mode
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: False
CLI: --hi or --help-inventory
ENV: ANSIBLE_NAVIGATOR_HELP_INVENTORY
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
inventory:
help:

inventory

Specify an inventory file path or comma separated host list
Added in version: v1.0
Default: No default value set
CLI: -i or --inventory
ENV: ANSIBLE_INVENTORY
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
inventory:
entries:

inventory-column

Specify a host attribute to show in the inventory view
Added in version: v1.0
Default: No default value set
CLI: --ic or --inventory-column
ENV: ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS
Settings file:

.. code-block:: yaml

ansible-navigator:
inventory-columns:

Subcommand: lint

Name

Description

Settings

lint-config

Specify the path to the ansible-lint configuration file
Added in version: v2.0
Default: No default value set
CLI: --lic or --lint-config
ENV: ANSIBLE_LINT_CONFIG
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-lint:
config:

lintables

Path to files on which to run ansible-lint
Added in version: v2.0
Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_LINTABLES
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible-lint:
lintables:

Subcommand: replay

Name

Description

Settings

playbook-artifact-replay

Specify the path for the playbook artifact to replay
Added in version: v1.0
Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
replay:

Subcommand: run

Name

Description

Settings

help-playbook

Help options for ansible-playbook command in stdout mode
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: False
CLI: --hp or --help-playbook
ENV: ANSIBLE_NAVIGATOR_HELP_PLAYBOOK
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
playbook:
help:

inventory

Specify an inventory file path or comma separated host list
Added in version: v1.0
Default: No default value set
CLI: -i or --inventory
ENV: ANSIBLE_INVENTORY
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
inventory:
entries:

inventory-column

Specify a host attribute to show in the inventory view
Added in version: v1.0
Default: No default value set
CLI: --ic or --inventory-column
ENV: ANSIBLE_NAVIGATOR_INVENTORY_COLUMNS
Settings file:

.. code-block:: yaml

ansible-navigator:
inventory-columns:

playbook

Specify the playbook name
Added in version: v1.0
Default: No default value set
CLI: positional
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK
Settings file:

.. code-block:: yaml

ansible-navigator:
ansible:
playbook:
path:

playbook-artifact-enable

Enable or disable the creation of artifacts for completed playbooks. Note: not compatible with ‘–mode stdout’ when playbooks require user input
Added in version: v1.0
Choices: ‘True’ or ‘False’
Default: True
CLI: --pae or --playbook-artifact-enable
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLE
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
enable:

playbook-artifact-save-as

Specify the name for artifacts created from completed playbooks. The following placeholders are available: {playbook_dir}, {playbook_name}, {playbook_status}, and {time_stamp}
Added in version: v1.0
Default: {playbook_dir}/{playbook_name}-artifact-{time_stamp}.json
CLI: --pas or --playbook-artifact-save-as
ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_SAVE_AS
Settings file:

.. code-block:: yaml

ansible-navigator:
playbook-artifact:
save-as:

Subcommand: settings

Name

Description

Settings

settings-effective

Show the effective settings. Defaults, CLI parameters, environment variables, and the settings file will be combined
Added in version: v2.0
Default: False
CLI: --se or --effective
ENV: ANSIBLE_NAVIGATOR_SETTINGS_EFFECTIVE
Settings file:

.. code-block:: yaml

ansible-navigator:
settings:
effective:

settings-sample

Generate a sample settings file
Added in version: v2.0
Default: False
CLI: --gs or --sample
ENV: ANSIBLE_NAVIGATOR_SETTINGS_SAMPLE
Settings file:

.. code-block:: yaml

ansible-navigator:
settings:
sample:

settings-schema

Generate a schema for the settings file (‘json’= draft-07 JSON Schema)
Added in version: v2.0
Choices: ‘json’
Default: json
CLI: --ss or --schema
ENV: ANSIBLE_NAVIGATOR_SETTINGS_SCHEMA
Settings file:

.. code-block:: yaml

ansible-navigator:
settings:
schema:

settings-sources

Show the source of each current settings entry
Added in version: v2.0
Default: False
CLI: --so or --sources
ENV: ANSIBLE_NAVIGATOR_SETTINGS_SOURCES
Settings file:

.. code-block:: yaml

ansible-navigator:
settings:
sources: