The Rougail Command Line Interface
========================================

help
------------

::

    rougail -u yaml -h

Standard usage 
-----------------

::

    rougail -m firefox/ -u yaml -yf config/02/config.yml



::

    rougail --cli.versions 

    tiramisu: 5.2.0a9
    tiramisu-cmdline-parser: 0.7.0a1
    rougail: 1.2.0a29
    rougail-cli: 0.2.0a19
    rougail-user-data-environment: 0.1.0a9
    rougail-user-data-yaml: 0.2.0a11
    rougail-output-console: 0.2.0a11
    rougail-output-json: 0.2.0a8

::

    env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m structfile/proxy2.yml -u yaml  environment --yaml.filename userdata/proxy.yml -o json

::

    env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m structfile/proxy2.yml -u yaml --yaml.filename userdata/proxy.yml -o json --json.get manual.https_proxy --json.read_write
    {
      "address": "toto.fr",
      "port": "8888"
    }

CLI root
-------------

::

    (.venv) ubuntu@monessai:~/workplace/rougail-tutorials$ env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m firefox/ --cli.root manual.https_proxy -u yaml environment -yf ^Cnfig/01/config.yml --cli.read_write
    (.venv) ubuntu@monessai:~/workplace/rougail-tutorials$ cat config/01/config.yml 
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: http.proxy.net
        port: 3128
      use_for_https: false
      https_proxy:
        address: https.proxy.net
    (.venv) ubuntu@monessai:~/workplace/rougail-tutorials$ rougail -m firefox/ --cli.root manual.https_proxy  -u yaml -yf config/01/config.yml
    [WARNING]: Deprecation warnings can be disabled by setting `deprecation_warnings=False` in ansible.cfg.
    [DEPRECATION WARNING]: Importing 'to_bytes' from 'ansible.module_utils._text' is deprecated. This feature will be removed from ansible-core version 2.24. Use ansible.module_utils.common.text.converters instead.
    ╭────────────── Caption ───────────────╮
    │ Variable Default value               │
    │          Modified value              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    ┣━━ 📓 HTTPS address: https.proxy.net ◀ loaded from the YAML file "config/01/config.yml" (⏳ https.proxy.net ◀ loaded from the YAML file "config/01/config.yml" ⏳ http.proxy.net)
    ┗━━ 📓 HTTPS port: 3128


.. FIXME: sortie normale: 

.. FIXME: sortie pour n'afficher qu'une family: 

::

    rougail -m firefox/ -u yaml -yf config/01/config

on a:

::

    Variables:
    ┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No proxy)
    ┗━━ 📂 Manual proxy configuration
        ┣━━ 📂 HTTP Proxy
        ┃   ┣━━ 📓 HTTP address: http.proxy.net ◀ loaded from the YAML file "config/01/config.yml"
        ┃   ┗━━ 📓 HTTP Port: 3128 ◀ loaded from the YAML file "config/01/config.yml" (⏳ 8080)
        ┣━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file "config/01/config.yml" (⏳ true)
        ┣━━ 📂 HTTPS Proxy
        ┃   ┣━━ 📓 HTTPS address: https.proxy.net ◀ loaded from the YAML file "config/01/config.yml" (⏳ http.proxy.net)
        ┃   ┗━━ 📓 HTTPS port: 3128
        ┗━━ 📂 SOCKS Proxy
            ┣━━ 📓 SOCKS address: http.proxy.net
            ┣━━ 📓 SOCKS port: 3128
            ┗━━ 📓 SOCKS host version used by proxy: v5


for a more precise output: 

::

    rougail -m firefox/ -u yaml -yf config/01/config.yml --cli.root manual.https_proxy

we have

::

    Variables:
    ┣━━ 📓 HTTPS address: https.proxy.net ◀ loaded from the YAML file "config/01/config.yml" (⏳ https.proxy.net ◀ loaded from the YAML file "config/01/config.yml" ⏳ http.proxy.net)
    ┗━━ 📓 HTTPS port: 3128


Invalid user data error
-----------------------------

::

    rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.invalid_user_data_error

Unknown user data error 
-----------------------------

The option "`--cli.unknown_user_data_error`" looks like "`--cli.invalid_user_data_error`" but here it concerns unknown variables (or here disabled or hidden but it amounts to the same thing) loaded into user data.


.. note:: The `--cli.unknown_user_data_error` option changes the behaviour of the Rougail CLI's standard output: 
          when an unknown (or disabled or hidden) variable is declared in the :term:`user data file <user data>` 
          then it appears in the output as an error instead of a warning.

The output doc 
----------------

::

    rougail -m structure.yml -o doc --doc.output_format github > README.md 

::

      doc:
      Generate documentation from structural files

      -do [{console,asciidoc,html,github,gitlab,json}], --doc.output_format [{console,asciidoc,html,github,gitlab,json}]
                            The output format of the generated documentation (default: console)
      -dm [{two_columns,three_columns,four_columns,five_columns,six_columns}], --doc.tabular_template [{two_columns,three_columns,four_columns,five_columns,six_columns}]
                            Generate document with this tabular model (default: two_columns)
      -dc {variables,example,changelog} [{variables,example,changelog} ...], --doc.contents {variables,example,changelog} [{variables,example,changelog} ...]
                            Generated content (default: variables)
      -dt [TITLE_LEVEL], --doc.title_level [TITLE_LEVEL]
                            Starting title level (default: 1)
      --doc.default_values  Modify values to document all variables (default: True)
      --doc.no-default_values
      --doc.document_a_type
                            Documentation a structural type (default: False)
      --doc.no-document_a_type


The formatter
----------------

::

    rougail -o formatter -m structure.yml > a.yml; mv a.yml structure.yml

The namespaces
-----------------

::

    rougail -m structure.yml -u yaml -yf userdata.yml -s intranet -xn hosts -xd 0 hosts.yml


::

    rougail -m structure.yml -u yaml -yf userdata.yml -s intranet -xn hosts orem srem prom -xd 0 hosts.yml -xd 1 packages/OREM -xd 2 packages/SREM -xd 3 packages/SREP

Commandline user data
----------------------------

Commandline user data can be used:

::

    rougail -m mon_fichier.yml -u commandline --family.variable pouet

Ansible export 
-------------------

rougail -m structure.yml -u yaml -yf userdata.yml -s intranet -xn hosts -xd 0 hosts.yml -o ansible > ansible.json

:: 

    ansible-inventory -i $(which rougail) --list

Ansible lists your inventory

::

    ansible-inventory -i $(which rougail) --host tutu.fr 

::

    ansible-playbook -i $(which rougail) install.yml

