Text User Interface (TUI)
=========================

The Text User Interface of Exosphere provides a visual, interactive way of
accessing the information gathered by Exosphere across your hosts.

It is a modal interface comprised of several screens you can toggle between,
and allows you to perform actions such as:

- Viewing the status of all hosts in a Dashboard
- Viewing the inventory status and drilling down into host details
- Performing actions such as refreshing updates, pinging hosts, etc.
- Viewing runtime logs in a nice colored panel.

While the TUI does not provide *all* the features of the CLI, it is often more
convenient for overviews and at-a-glance status checks. It does provide most
of the same host operation features through screen actions as well as the
command palette, and it can also easily be used in conjunction with the
:doc:`cli` for more advanced operations.

Launching the UI
----------------

You can launch the UI by running:

.. code-block:: shell

    $ exosphere ui


Or, from interactive mode:

.. code-block:: exosphere

    exosphere> ui


.. tip::

    Launching the UI from interactive mode will allow you to return to the CLI
    when exiting the UI, making it possible to switch back and forth between
    the two interfaces seamlessly.

.. note::

    The ``ui start`` command used in previous versions of Exosphere is still
    accepted as an alias for ``ui``, for backward compatibility.

Interface Navigation
--------------------

The UI is divided into several screens, each accessible via a keybind.
At the very top of the screen, you will see the title bar with the current screen name.

The UI is separated in three main screens:

- **Dashboard**: A grid view of all hosts, showing their online status.
- **Inventory**: A detailed view of all hosts and their updates.
- **Logs**: A real-time view of the logs generated by Exosphere.

The bottom of the screen contains a status bar with keybinds for navigation and actions.

.. image:: /_static/ui_commands_sample.png
   :alt: Example of Exosphere TUI with commands

Some of the keys displayed there will show up globally, while others are specific to the
current screen you are on.

For instance here, you can press ``i`` to go to the Inventory screen.
Keys are shown as they should be typed, so ``shift+p`` will trigger Ping All,
and ``ctrl+d`` will trigger Discover All.

Universally, in every screen, you can press ``ctrl+p`` to access the command
palette, which you can use to get keybind help, change the color theme, or run
operations against all or specific hosts.

**On Any Screen**, you can press ``ctrl+q`` to Quit the UI.

Executing Operations
--------------------

Most if not all of the operations you can perform on hosts in the UI are going
to be dispatched through the same parallelized Thread Pool as the CLI, with
minor implementation differences.

The UI will present a modal progress bar whenever this is occurring:

.. image:: /_static/ui_progress_sample.png
   :alt: Example of Exosphere TUI Progress Bar

.. admonition:: Note

    While you can press ESC to cancel the operation, it will not abort already
    executing tasks in the Thread Pool, only prevent new tasks from being
    started past this point.

The Command Palette
-------------------

Pressing ``ctrl+p`` from any screen will open the Command Palette, which allows you
to select and fuzzy search through commands that can be invoked. This includes
some built-in ones like **Keys** and **Theme**, but also Exosphere specific commands
allowing you to perform operations on hosts in your inventory.

The palette can be invoked from any screen, and the available commands will be
contextual to the screen you are on, if applicable.

.. image:: /_static/palette_sample.png
   :alt: Example of Exosphere TUI Command Palette

Host operations come in three flavors:

**On All Hosts**

.. image:: /_static/palette_all_sample.png
   :alt: Example of Exosphere TUI Command Palette with global host operations

These include operations like **Ping all hosts**, **Discover all hosts**,
**Refresh all hosts** etc. Invoking these will perform the action immediately,
displaying the progress screen, as described in the previous section.
These can be invoked from any screen.

**On Any Host**

These commands allow you to select a specific host from your inventory and perform an
operation on it, such as **Ping...**, **Discover...**, **Refresh...**, etc.

.. image:: /_static/palette_any_sample.png
   :alt: Example of Exosphere TUI Command Palette with host-specific operations

Invoking these will open a second prompt with a list of hosts available in your
inventory, allowing you to either select one with the arrow keys and ``Enter``, or
to fuzzy search for it by typing its name, completely or partially.

.. image:: /_static/palette_fuzzy_select_sample.png
   :alt: Example of Exosphere TUI Command Palette with host selection

These commands can also be invoked from any screen.

**On the currently selected host**

When the palette is opened from the Inventory screen, each operation will also
propose a variant that applies to the currently selected host in the inventory table.

.. image:: /_static/palette_selected_host_sample.png
   :alt: Example of Exosphere TUI Command Palette with current host operations

Selecting it will let you run that operation immediately on whichever host is
currently under the cursor in the inventory. These options will also sort above
the global ones in the palette, making them quick to access.

These can only be invoked from the Inventory screen.

.. tip::

   All palettes are fuzzy-searched, so you rarely need to scroll. In any of
   the pickers, just type part of the command or host, and the list will
   narrow down immediately.

The Dashboard
-------------

The default screen Exosphere launches into is the Dashboard. It presents a
colored grid, each square representing a host in your inventory.

.. image:: /_static/dashboard_sample.png
   :alt: Example of Exosphere TUI Dashboard

Each square is color coded according to the status of the host.
Green for Online, Red for Offline. Basic information about each host is also
displayed.

This view is mostly useful as a poor man's monitoring dashboard,
allowing you to quickly see which hosts are online or offline at a glance.

The following operations can be performed from the Dashboard:

- **Ping All**: Press `shift+p` to ping all hosts and update their status.
- **Discover All**: Press `ctrl+d` to discover all hosts and update their platform information.

Inventory Screen
----------------

.. image:: /_static/inventory_sample.png
   :alt: Example of Exosphere TUI Inventory

The Inventory screen provides a detailed view of all the hosts in your inventory.

The following operations can be performed from the Inventory screen:

- **Refresh Updates**: Press `ctrl+r` to refresh the updates for all hosts.
- **Sync & Refresh**: Press `ctrl+x` to sync the repositories and refresh updates
  for all hosts.
- **Filter**: Press `ctrl+f` to filter the hosts shown in the table.
- **Sort**: Press `ctrl+s` to sort the table by a chosen column.

.. admonition:: Note

   Syncing repositories may take a long time depending on inventory size and
   host specifications.

It functions almost identically to the ``inventory status`` command in the CLI,
but it allows you to navigate the rows with the Arrow Keys. The same status
indicators apply, with ``*`` marking stale data and ``!`` marking a pending
reboot, as shown in the table legend.

You can select a host with ``Enter``, which will open a panel with more details:

.. image:: /_static/ui_inventory_hostpanel.png
   :alt: Example of Exosphere TUI Host Details

Any available updates will be displayed in a list. You can navigate this list with the
arrow keys, much like the inventory itself, and select any of them with ``Enter``.

.. image:: /_static/ui_inventory_updatepanel.png
   :alt: Example of Exosphere TUI Update Details

Details about the currently selected update will be displayed in a new panel.
This includes the package name, source, version change and whether or not it is
a security update.

**Filtering Hosts**

It is also possible to filter hosts with `ctrl+f`, which will open a prompt
with the available filters.

.. image:: /_static/filter_sample.png
   :alt: Example of Exosphere TUI Filter Prompt

.. tip::
   Each entry also has an underlined quick-select key (``u`` for "Updates Only",
   for instance) that will **immediately** apply that filter when pressed.

After selecting a filter, only hosts matching the criteria will be displayed.
The active filter will be shown in the status bar at the bottom of the screen:

.. image:: /_static/ui_inventory_statusbar.png
   :alt: Exosphere TUI Inventory Status Bar with Security Updates filter active

You can clear the filter by pressing `ctrl+f` again and selecting the
"Show All" option.

**Sorting Hosts**

You can sort the hosts with `ctrl+s`, which opens a prompt listing the
sortable columns along with a *Reverse order* checkbox. Navigate the
columns with the Arrow Keys, toggle reverse by pressing ``r`` (or focusing
the checkbox with ``Tab`` and pressing ``Space``), and press ``Enter`` to
apply.

.. image:: /_static/sort_sample.png
   :alt: Example of Exosphere TUI Sort Prompt

.. tip::
   Each entry also has an underlined quick-select key (``h`` for
   *Host*, ``o`` for *OS*, ``s`` for *Security*, etc.) that will select the
   option when pressed. So to get a reverse sort by Security Updates, it is
   possible to simply press ``ctrl+s, s, r, enter``.

After applying a sort, the active sort field and direction are shown in
the status bar alongside any active filter. You can restore the original
configuration order by pressing `ctrl+s` again and selecting the
"Default (config order)" option (or pressing ``D``).

.. image:: /_static/ui_inventory_sort_statusbar.png
   :alt: Exosphere TUI Inventory Status Bar with sorted status and direction

Sorting and filtering are independent and can be combined freely.

.. admonition:: Note

   Sorting by *Version* groups hosts by flavor first, then orders versions
   within each flavor, since version numbers are not directly comparable
   across different flavors. Likewise, sorting by *Flavor* groups hosts by
   OS first, keeping OS families together.

   Additionally, hosts with no meaningful data for the selected sort column
   always sort to the bottom of the list, regardless of the requested order.
   Within that bottom tier, Undiscovered hosts sort above Unsupported ones.

Logs Screen
-----------

.. image:: /_static/logs_sample.png
   :alt: Example of Exosphere TUI Logs

The Logs screen provides a real-time view of the logs generated by Exosphere.
You can access it by pressing ``l`` from the Dashboard or Inventory screen.

The window can be scrolled left and right, and will color certain elements.

.. tip::

    The logs are always written to file. You can access them at the
    path returned by the ``exosphere config paths`` command.
