Chapter 8. Automation content navigator configuration settings

As a content creator, you can configure Automation content navigator to suit your development environment.

8.1. Creating an Automation content navigator settings file

You can alter the default Automation content navigator settings through:

  • The command line
  • Within a settings file
  • As an environment variable

Automation content navigator checks for a settings file in the following order and uses the first match:

  • ANSIBLE_NAVIGATOR_CONFIG - The settings file path environment variable if set.
  • ./ansible-navigator.<ext> - The settings file within the current project directory, with no dot in the file name.
  • \~/.ansible-navigator.<ext> - Your home directory, with a dot in the file name.

Consider the following when you create an Automation content navigator settings file:

  • 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 Automation content navigator finds more than one settings file in either directory, it results in an error.

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

    ---
    ansible-navigator:
    #   ansible:
    #     config: /tmp/ansible.cfg
    #     cmdline: "--forks 15"
    #     inventories:
    #     - /tmp/test_inventory.yml
    #     playbook: /tmp/test_playbook.yml
    #   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
    #   documentation:
    #     plugin:
    #       name: shell
    #       type: become
    #   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-policy: never
    #     volume-mounts:
    #     - src: "/test1"
    #       dest: "/test1"
    #       label: "Z"
    #   help-config: True
    #   help-doc: True
    #   help-inventory: True
    #   help-playbook: False
    #   inventory-columns:
    #     - ansible_network_os
    #     - ansible_network_cli_ssh_type
    #     - ansible_connection
      logging:
    #     append: False
        level: critical
    #     file: /tmp/log.txt
    #   mode: stdout
    #   playbook-artifact:
    #     enable: True
    #     replay: /tmp/test_artifact.json
    #     save-as: /tmp/test_artifact.json

8.2. Automation content navigator general settings

The following table describes each general parameter and setting options for Automation content navigator.

Table 8.1. Automation content navigator general parameters settings

ParameterDescriptionSetting options

ansible-runner-artifact-dir

The directory path to store artifacts generated by ansible-runner.

Default: No default value set

CLI: --rad or --ansible-runner-artifact-dir

ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ARTIFACT_DIR

Settings file: 

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 are not deleted.

Default: No default value set

CLI: --rac or --ansible-runner-rotate-artifacts-count

ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_ROTATE_ARTIFACTS_COUNT

Settings file: 

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

ansible-runner-timeout

The timeout value after which ansible-runner force stops the execution.

Default: No default value set

CLI: --rt or --ansible-runner-timeout

ENV: ANSIBLE_NAVIGATOR_ANSIBLE_RUNNER_TIMEOUT

Settings file: 

ansible-navigator:
  ansible-runner:
    timeout:

app

Entry point for Automation content navigator.

Choices: collections, config, doc, images, inventory, replay, run or welcome

Default: welcome

CLI example: ansible-navigator collections

ENV: ANSIBLE_NAVIGATOR_APP

Settings file: 

ansible-navigator:
  app:

cmdline

Extra parameters passed to the corresponding command.

Default: No default value

CLI: positional

ENV: ANSIBLE_NAVIGATOR_CMDLINE

Settings file: 

ansible-navigator:
  ansible:
    cmdline:

collection-doc-cache-path

The path to the collection doc cache.

Default: $HOME/.cache/ansible-navigator/collection_doc_cache.db

CLI: --cdcp or --collection-doc-cache-path

ENV: ANSIBLE_NAVIGATOR_COLLECTION_DOC_CACHE_PATH

Settings file: 

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

container-engine

Specify the container engine (auto=podman then docker).

Choices: auto, podman or docker

Default: auto

CLI: --ce or --container-engine

ENV: ANSIBLE_NAVIGATOR_CONTAINER_ENGINE

Settings file: 

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

display-color

Enable the use of color in the display.

Choices: True or False

Default: True

CLI: --dc or --display-color

ENV: NO_COLOR

Settings file: 

ansible-navigator:
  color:
    enable:

editor-command

Specify the editor used by Automation content navigator

Default:* vi +{line_number} {filename}

CLI: --ecmd or --editor-command

ENV: ANSIBLE_NAVIGATOR_EDITOR_COMMAND

Settings file: 

ansible-navigator:
  editor:
    command:

editor-console

Specify if the editor is console based.

Choices: True or False

Default: True

CLI: --econ or --editor-console

ENV: ANSIBLE_NAVIGATOR_EDITOR_CONSOLE

Settings file: 

ansible-navigator:
  editor:
    console:

execution-environment

Enable or disable the use of an automation execution environment.

Choices: True or False

Default: True

CLI: --ee or --execution-environment

ENV:* ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT

Settings file: 

ansible-navigator:
  execution-environment:
    enabled:

execution-environment-image

Specify the name of the automation execution environment image.

Default: quay.io/ansible/ansible-runner:devel

CLI: --eei or --execution-environment-image

ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_IMAGE

Settings file: 

ansible-navigator:
  execution-environment:
    image:

execution-environment-volume-mounts

Specify volume to be bind mounted within an automation execution environment (--eev /home/user/test:/home/user/test:Z)

Default: No default value set

CLI: --eev or --execution-environment-volume-mounts

ENV: ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT_VOLUME_MOUNTS

Settings file: 

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 is created per session.

Choices: True or False

Default: True

CLI: --la or --log-append

ENV: ANSIBLE_NAVIGATOR_LOG_APPEND

Settings file: 

ansible-navigator:
  logging:
    append:

log-file

Specify the full path for the Automation content navigator log file.

Default: $PWD/ansible-navigator.log

CLI: --lf or --log-file

ENV: ANSIBLE_NAVIGATOR_LOG_FILE

Settings file: 

ansible-navigator:
  logging:
    file:

log-level

Specify the Automation content navigator log level.

Choices: debug, info, warning, error or critical

Default: warning

CLI: --ll or --log-level

ENV: ANSIBLE_NAVIGATOR_LOG_LEVEL

Settings file: 

ansible-navigator:
  logging:
    level:

mode

Specify the user-interface mode.

Choices: stdout or interactive

Default: interactive

CLI: -m or --mode

ENV: ANSIBLE_NAVIGATOR_MODE

Settings file: 

ansible-navigator:
  mode:

osc4

Enable or disable terminal color changing support with OSC 4.

Choices: True or False

Default: True

CLI: --osc4 or --osc4

ENV: ANSIBLE_NAVIGATOR_OSC4

Settings file: 

ansible-navigator:
  color:
    osc4:

pass-environment-variable

Specify an exiting environment variable to be passed through to and set within the automation execution environment (--penv MY_VAR)

Default: No default value set

CLI: --penv or --pass-environment-variable

ENV: ANSIBLE_NAVIGATOR_PASS_ENVIRONMENT_VARIABLES

Settings file: 

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

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

Choices: always, missing, never, or tag

Default: tag

CLI: --pp or --pull-policy

ENV: ANSIBLE_NAVIGATOR_PULL_POLICY

Settings file: 

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

set-environment-variable

Specify an environment variable and a value to be set within the automation execution environment (--senv MY_VAR=42)

Default: No default value set

CLI: --senv or --set-environment-variable

ENV: ANSIBLE_NAVIGATOR_SET_ENVIRONMENT_VARIABLES

Settings file: 

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

8.3. Automation content navigator config subcommand settings

The following table describes each parameter and setting options for the Automation content navigator config subcommand.

Table 8.2. Automation content navigator config subcommand parameters settings

ParameterDescriptionSetting options

config

Specify the path to the Ansible configuration file.

Default: No default value set

CLI: -c or --config

ENV: ANSIBLE_CONFIG

Settings file: 

ansible-navigator:
  ansible:
    config:

help-config

Help options for the ansible-config command in stdout mode.

Choices:* True or False

Default: False

CLI: --hc or --help-config

ENV: ANSIBLE_NAVIGATOR_HELP_CONFIG

Settings file: 

ansible-navigator:
  help-config:

8.4. Automation content navigator doc subcommand settings

The following table describes each parameter and setting options for the Automation content navigator doc subcommand.

Table 8.3. Automation content navigator doc subcommand parameters settings

ParameterDescriptionSetting options

help-doc

Help options for the ansible-doc command in stdout mode.

Choices: True or False

Default: False

CLI: --hd or --help-doc

ENV: ANSIBLE_NAVIGATOR_HELP_DOC

Settings file: 

ansible-navigator:
  help-doc:

plugin-name

Specify the plugin name.

Default: No default value set

CLI: positional

ENV: ANSIBLE_NAVIGATOR_PLUGIN_NAME

Settings file: 

ansible-navigator:
  documentation:
    plugin:
      name:

plugin-type

Specify the plugin type.

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: 

ansible-navigator:
  documentation:
    plugin:
      type:

8.5. Automation content navigator inventory subcommand settings

The following table describes each parameter and setting options for the Automation content navigator inventory subcommand.

Table 8.4. Automation content navigator inventory subcommand parameters settings

ParameterDescriptionSetting options

help-inventory

Help options for the ansible-inventory command in stdout mode.

Choices: True or False

Default: False

CLI: --hi or --help-inventory

ENV: ANSIBLE_NAVIGATOR_INVENTORY_DOC

Settings file: 

ansible-navigator:
  help-inventory:

inventory

Specify an inventory file path or comma separated host list.

Default: no default value set

CLI: --i or --inventory

ENV: ANSIBLE_NAVIGATOR_INVENTORIES

Settings file: 

ansible-navigator:
  inventories:

inventory-column

Specify a host attribute to show in the inventory view.

Default: No default value set

CLI: --ic or --inventory-column

ENV:* ANSIBLE_NAVIGATOR_INVENTORY_COLUMNSSettings file: 

ansible-navigator:
  inventory-columns:

8.6. Automation content navigator replay subcommand settings

The following table describes each parameter and setting options for the Automation content navigator replay subcommand.

Table 8.5. Automation content navigator replay subcommand parameters settings

ParameterDescriptionSetting options

playbook-artifact-replay

Specify the path for the playbook artifact to replay.

Default: No default value set

CLI: positional

ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY

Settings file: 

ansible-navigator:
  playbook-artifact:
    replay:

8.7. Automation content navigator run subcommand settings

The following table describes each parameter and setting options for the Automation content navigator run subcommand.

Table 8.6. Automation content navigator run subcommand parameters settings

ParameterDescriptionSetting options

playbook-artifact-replay

Specify the path for the playbook artifact to replay.

Default: No default value set

CLI: positional

ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_REPLAY

Settings file: 

ansible-navigator:
  playbook-artifact:
    replay:

help-playbook

Help options for the ansible-playbook command in stdout mode.

Choices: True or False

Default: False

CLI: --hp or --help-playbook

ENV: ANSIBLE_NAVIGATOR_HELP_PLAYBOOK

Settings file: 

ansible-navigator:
  help-playbook:

inventory

Specify an inventory file path or comma separated host list.

Default: no default value set

CLI: --i or --inventory

ENV: ANSIBLE_NAVIGATOR_INVENTORIES

Settings file: 

ansible-navigator:
  inventories:

inventory-column

Specify a host attribute to show in the inventory view.

Default: No default value set

CLI: --ic or --inventory-column

ENV:* ANSIBLE_NAVIGATOR_INVENTORY_COLUMNSSettings file: 

ansible-navigator:
  inventory-columns:

playbook

Specify the playbook name.

Default: No default value set

CLI: positional

ENV: ANSIBLE_NAVIGATOR_PLAYBOOK

Settings file:* 

ansible-navigator:
  ansible:
    playbook:

playbook-artifact-enable

Enable or disable the creation of artifacts for completed playbooks. Note: not compatible with --mode stdout when playbooks require user input.

Choices: True or False

Default: True

CLI: --pae or --playbook-artifact-enableENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLESettings file: 

ansible-navigator:
  playbook-artifact:
    enable:

playbook-artifact-save-as

Specify the name for artifacts created from completed playbooks.

Default: {playbook_dir}/{playbook_name}-artifact-{ts_utc}.json

CLI: --pas or --playbook-artifact-save-as

ENV: ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_SAVE_AS

Settings file: 

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