import awxkit

Co-authored-by: Christopher Wang <cwang@ansible.com>
Co-authored-by: Jake McDermott <jmcdermott@ansible.com>
Co-authored-by: Jim Ladd <jladd@redhat.com>
Co-authored-by: Elijah DeLee <kdelee@redhat.com>
Co-authored-by: Alan Rominger <arominge@redhat.com>
Co-authored-by: Yanis Guenane <yanis@guenane.org>

awxkit/awxkit/cli/docs/source/authentication.rst

@@ -0,0 +1,69 @@
+.. _authentication:
+
+Authentication
+==============
+
+Generating a Personal Access Token
+----------------------------------
+
+The preferred mechanism for authenticating with AWX and |RHAT| is by generating and storing an OAuth2.0 token.  Tokens can be scoped for read/write permissions, are easily revoked, and are more suited to third party tooling integration than session-based authentication.
+
+|prog| provides a simple login command for generating a personal access token from your username and password.
+
+.. code:: bash
+
+    TOWER_HOST=https://awx.example.org \
+        TOWER_USERNAME=alice \
+        TOWER_PASSWORD=secret \
+        awx login
+
+As a convenience, the ``awx login`` command prints a shell-formatted token
+value:
+
+.. code:: bash
+
+    export TOWER_TOKEN=6E5SXhld7AMOhpRveZsLJQsfs9VS8U
+
+By ingesting this token, you can run subsequent CLI commands without having to
+specify your username and password each time:
+
+.. code:: bash
+
+    export TOWER_HOST=https://awx.example.org
+    $(TOWER_USERNAME=alice TOWER_PASSWORD=secret awx login)
+    awx config
+
+Working with OAuth2.0 Applications
+----------------------------------
+
+AWX and |RHAT| allow you to configure OAuth2.0 applications scoped to specific
+organizations.  To generate an application token (instead of a personal access
+token), specify the **Client ID** and **Client Secret** generated when the
+application was created.
+
+.. code:: bash
+
+    TOWER_USERNAME=alice TOWER_PASSWORD=secret awx login \
+        --conf.client_id <value> --conf.client_secret <value>
+
+
+OAuth2.0 Token Scoping
+----------------------
+
+By default, tokens created with ``awx login`` are write-scoped.  To generate
+a read-only token, specify ``--scope read``:
+
+.. code:: bash
+
+    TOWER_USERNAME=alice TOWER_PASSWORD=secret \
+        awx login --conf.scope read
+
+Session Authentication
+----------------------
+If you do not want or need to generate a long-lived token, |prog| allows you to
+specify your username and password on every invocation:
+
+.. code:: bash
+
+    TOWER_USERNAME=alice TOWER_PASSWORD=secret awx jobs list
+    awx --conf.username alice --conf.password secret jobs list

awxkit/awxkit/cli/docs/source/conf.py

@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'AWX CLI'
+copyright = '2019, Ansible by Red Hat'
+author = 'Ansible by Red Hat'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'awxkit.cli.sphinx'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'classic'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+rst_epilog = '''
+.. |prog| replace:: awx
+.. |at| replace:: Ansible Tower
+.. |RHAT| replace:: Red Hat Ansible Tower
+'''

awxkit/awxkit/cli/docs/source/examples.rst

@@ -0,0 +1,60 @@
+Usage Examples
+==============
+
+Verifying CLI Configuration
+---------------------------
+
+To confirm that you've properly configured ``awx`` to point at the correct
+AWX/|RHAT| host, and that your authentication credentials are correct, run:
+
+.. code:: bash
+
+    awx config
+
+.. note:: for help configurating authentication settings with the awx CLI, see :ref:`authentication`.
+
+Printing the History of a Particular Job
+----------------------------------------
+
+To print a table containing the recent history of any jobs named ``Example Job Template``:
+
+.. code:: bash
+
+    awx jobs list --all --name 'Example Job Template' \
+        -f human --filter 'name,created,status'
+
+Creating and Launching a Job Template
+-------------------------------------
+
+Assuming you have an existing Inventory named ``Demo Inventory``, here's how
+you might set up a new project from a GitHub repository, and run (and monitor
+the output of) a playbook from that repository:
+
+.. code:: bash
+
+    export TOWER_COLOR=f
+    INVENTORY_ID=$(awx inventory list --name 'Demo Inventory' -f jq --filter '.results[0].id')
+    PROJECT_ID=$(awx projects create --wait \
+        --organization 1 --name='Example Project' \
+        --scm_type git --scm_url 'https://github.com/ansible/ansible-tower-samples' \
+        -f jq --filter '.id')
+    TEMPLATE_ID=$(awx job_templates create \
+        --name='Example Job Template' --project $PROJECT_ID \
+        --playbook hello_world.yml --inventory $INVENTORY_ID \
+        -f jq --filter '.id')
+    awx job_templates launch $TEMPLATE_ID --monitor
+
+Importing an SSH Key
+--------------------
+
+DOCUMENT ME
+
+Creating a Job Template with Extra Vars
+---------------------------------------
+
+DOCUMENT ME
+
+Granting Membership to a Team or Organization
+---------------------------------------------
+
+DOCUMENT ME

awxkit/awxkit/cli/docs/source/index.rst

@@ -0,0 +1,36 @@
+.. AWX CLI documentation master file, created by
+   sphinx-quickstart on Mon Jul 22 11:39:10 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+AWX Command Line Interface
+==========================
+
+|prog| is the official command-line client for AWX and |RHAT|.  It:
+
+* Uses naming and structure consistent with the AWX HTTP API
+* Provides consistent output formats with optional machine-parsable formats
+* To the extent possible, auto-detects API versions, available endpoints, and
+  feature support across multiple versions of AWX and |RHAT|.
+
+Potential uses include:
+
+* Configuring and launching jobs/playbooks
+* Checking on the status and output of job runs
+* Managing objects like organizations, users, teams, etc...
+
+.. toctree::
+   :maxdepth: 3
+
+   usage
+   authentication
+   output
+   examples
+   reference
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

awxkit/awxkit/cli/docs/source/output.rst

@@ -0,0 +1,59 @@
+.. _formatting:
+
+
+Output Formatting
+=================
+
+By default, awx prints valid JSON for successful commands.  The ``-f`` (or
+``--conf.format``) global flag can be used to specify alternative output
+formats.
+
+YAML Formatting
+---------------
+
+To print results in YAML, specify ``-f yaml``:
+
+.. code:: bash
+
+    awx jobs list -f yaml
+
+Human-Readable (Tabular) Formatting
+-----------------------------------
+
+|prog| provides *optional* support for printing results in a human-readable
+tabular format, but it requires an additional Python software dependency,
+``tabulate``.
+
+To use ``-f human``, you must install the optional dependency via ``pip install tabulate``.
+
+.. code:: bash
+
+    awx jobs list -f human
+    awx jobs list -f human --filter name,created,status
+
+
+Custom Formatting with jq
+-------------------------
+
+|prog| provides *optional* support for filtering results using the ``jq`` JSON
+processor, but it requires an additional Python software dependency,
+``jq``.
+
+To use ``-f jq``, you must install the optional dependency via ``pip
+install jq``.  Note that some platforms may require additional programs to
+build ``jq`` from source (like ``libtool``).  See https://pypi.org/project/jq/ for instructions.
+
+.. code:: bash
+
+    awx jobs list \
+        -f jq --filter '.results[] | .name + " is " + .status'
+
+For details on ``jq`` filtering usage, see the ``jq`` manual at https://stedolan.github.io/jq/
+
+
+Colorized Output
+----------------
+
+By default, |prog| prints colorized output using ANSI color codes.  To disable
+this functionality, specify ``--conf.color f`` or set the environment variable
+``TOWER_COLOR=f``.

awxkit/awxkit/cli/docs/source/reference.rst

@@ -0,0 +1,3 @@
+.. autoprogram:: awxkit.cli.sphinx:parser
+    :prog: awx
+    :maxdepth: 3

awxkit/awxkit/cli/docs/source/usage.rst

@@ -0,0 +1,99 @@
+Basic Usage
+===========
+
+Installation
+------------
+
+The awx CLI is available as part of the ``awxkit`` package on PyPI.
+
+The preferred way to install is through pip:
+
+.. code:: bash
+
+    pip install awxkit
+
+
+Synopsis
+--------
+
+|prog| commands follow a simple format:
+
+.. code:: bash
+
+    awx [<global-options>] <resource> <action> [<arguments>]
+    awx --help
+
+The ``resource`` is a type of object within AWX (a noun), such as ``users`` or ``organizations``.
+
+The ``action`` is the thing you want to do (a verb). Resources generally have a base set of actions (``get``, ``list``, ``create``, ``modify``, and ``delete``), and have options corresponding to fields on the object in AWX.  Some resources have special actions, like ``job_templates launch``.
+
+
+Getting Started
+---------------
+
+Using |prog| requires some initial configuration.  Here is a simple example for interacting with an AWX or |RHAT| server:
+
+.. code:: bash
+
+    awx --conf.host https://awx.example.org \
+        --conf.username joe --conf.password secret \
+        --conf.insecure \
+        users list
+
+There are multiple ways to configure and authenticate with an AWX or |RHAT| server.  For more details, see :ref:`authentication`.
+
+By default, |prog| prints valid JSON for successful commands.  Certain commands (such as those for printing job stdout) print raw text and do not allow for custom formatting.  For details on customizing |prog|'s output format, see :ref:`formatting`.
+
+
+Resources and Actions
+---------------------
+
+To get a list of available resources:
+
+.. code:: bash
+
+    awx --conf.host https://awx.example.org --help
+
+To get a description of a specific resource, and list its available actions (and their arguments):
+
+.. code:: bash
+
+    awx --conf.host https://awx.example.org users --help
+    awx --conf.host https://awx.example.org users create --help
+
+
+.. note:: The list of resources and actions may vary based on context.  For
+    example, certain resources may not be available based on role-based access
+    control (e.g., if you do not have permission to launch certain Job Templates,
+    `launch` may not show up as an action for certain `job_templates` objects.
+
+
+Global Options
+--------------
+|prog| accepts global options that control overall behavior.  In addition to CLI flags, most global options have a corresponding environment variable that may be used to set the value.  If both are provided, the command line option takes priority.
+
+A few of the most important ones are:
+
+``-h, --help``
+    Prints usage information for the |prog| tool
+
+``-v, --verbose``
+    prints debug-level logs, including HTTP(s) requests made
+
+``-f, --conf.format``
+    used to specify a custom output format (the default is json)
+
+``--conf.host, TOWER_HOST``
+    the full URL of the AWX/|RHAT| host (i.e., https://my.awx.example.org)
+
+``-k, --conf.insecure, TOWER_VERIFY_SSL``
+    allows insecure server connections when using SSL
+
+``--conf.username, TOWER_USERNAME``
+    the AWX username to use for authentication
+
+``--conf.password, TOWER_PASSWORD``
+    the AWX password to use for authentication
+
+``--conf.token, TOWER_TOKEN``
+    an OAuth2.0 token to use for authentication