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.

Settings

# # 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
#     job-events: False
#
#   app: run
#
#   collection-doc-cache-path: /tmp/cache.db
#
#   color:
#     enable: False
#     osc4: False
#
#   editor:
#     command: vim_from_setting
#     console: False
#
#   enable-prompts: 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¶

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

    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

    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

    ansible-navigator:
      ansible-runner:
        timeout:

ansible-runner-write-job-events ¶

Write ansible-runner job_events in the artifact directory

Added in version: v2.3

Choices: 'True' or 'False'

Default: False

CLI: --rwje or --ansible-runner-write-job-events

ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_WRITE_JOB_EVENTS

Settings

    ansible-navigator:
      ansible-runner:
        job-events:

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

    ansible-navigator:
      app:

cmdline ¶

Extra parameters passed to the underlying ansible command (e.g. ansible-playbook, ansible-doc, etc)

Added in version: v1.0

Default: No default value set

CLI: positional

ENV: ANSIBLE_NAVIGATOR_CMDLINE

Settings

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    ansible-navigator:
      time-zone:

¶

Subcommand: builder¶

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

    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

    ansible-navigator:
      ansible-builder:
        workdir:

¶

Subcommand: collections¶

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

    ansible-navigator:
      format:

¶

Subcommand: config¶

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

    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

    ansible-navigator:
      ansible:
        config:
          help:

¶

Subcommand: doc¶

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

    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

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

plugin-type ¶

Specify the plugin type, 'become', 'cache', 'callback', 'cliconf', 'connection', 'filter', 'httpapi', 'inventory', 'keyword', 'lookup', 'module', 'netconf', 'role', 'shell', 'strategy', 'test' or 'vars'

Added in version: v1.0

Choices: 'become', 'cache', 'callback', 'cliconf', 'connection', 'filter', 'httpapi', 'inventory', 'keyword', 'lookup', 'module', 'netconf', 'role', 'shell', 'strategy', 'test' or 'vars'

Default: module

CLI: -t or --type

ENV: ANSIBLE_NAVIGATOR_PLUGIN_TYPE

Settings

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

¶

Subcommand: exec¶

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

    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

    ansible-navigator:
      exec:
        shell:

¶

Subcommand: images¶

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

    ansible-navigator:
      format:

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

    ansible-navigator:
      images:
        details:

¶

Subcommand: inventory¶

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

    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

    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

    ansible-navigator:
      inventory-columns:

¶

Subcommand: lint¶

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

    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

    ansible-navigator:
      ansible-lint:
        lintables:

¶

Subcommand: replay¶

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

    ansible-navigator:
      playbook-artifact:
        replay:

¶

Subcommand: run¶

enable-prompts ¶

Enable prompts for password and in playbooks. This will set mode to stdout and disable playbook artifact creation

Added in version: v2.3

Choices: 'True' or 'False'

Default: False

CLI: --ep or --enable-prompts

ENV: ANSIBLE_NAVIGATOR_ENABLE_PROMPTS

Settings

    ansible-navigator:
      enable-prompts:

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

    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

    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

    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

    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

    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

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

¶

Subcommand: 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

    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

    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

    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

    ansible-navigator:
      settings:
        sources: