.. _Inventory:

Virtual Machine Inventory Report
================================

Inventory reports are useful to provide an offline overview of your virtual machines.
When you submit an inventory report request, a CSV or JSON file will be generated with
the selected attributes.

The command ``vss-cli compute inventory`` provides the sub-commands to generate and
download inventory files:

.. code-block:: bash

    Usage: vss-cli compute inventory [OPTIONS] COMMAND [ARGS]...

      Create or download an inventory file of your virtual machines hosted.
      Inventory files are created and transferred to your VSKEY-STOR space and
      are also available through the API.

    Options:
      --help  Show this message and exit.

    Commands:
      dl  download inventory report
      mk  create inventory report


Create
------

Creating inventory files is as simple as running ``vss-cli compute inventory mk`` and
all supported attributes will be included in the default format ``CSV``. However, the
following options area available:

.. code-block:: bash

    Usage: vss-cli compute inventory mk [OPTIONS] [ATTRIBUTE]...

      Submits an inventory report request to generate file in JSON or CSV of
      your virtual machines.

    Options:
      -f, --fmt [json|csv]        report format  [default: csv]
      --transfer / --no-transfer  Transfer report to personal store  [default:
                                  False]
      -a, --all                   include all attributes
      --help                      Show this message and exit.


Every attribute included in the report is passed as an argument, but as already mentioned,
"no argument" adds all attributes. Attributes are dynamic and provided by the API, thus we
strongly recommend setup **autocompletion** to have them listed as follows:

.. code-block:: bash

    vss-cli compute inventory mk <tab-tab>

    admin             -- Admin
    cdBacking         -- CD/DVD unit backing
    client            -- Client
    clientNotes       -- Client Notes
    cpu               -- CPU Count
    diskCount         -- Disk Count
    diskTotalSize     -- Disk Total Size
    disks             -- Hard Disks
    domain            -- Fault Domain
    folder            -- Folder
    guestOsId         -- Guest OS Id
    haGroup           -- HA Group
    hardwareVersion   -- Hardware Version
    hostName          -- Host Name
    inform            -- Inform
    ipAddress         -- IP Address
    isTemplate        -- Is Template
    memory            -- Memory GB
    networkIds        -- Network IDs
    nicCount          -- NIC Count
    nics              -- NICs
    options           -- Vss Options
    osId              -- OS Id
    provisionedSpace  -- Provisioned Space
    requested         -- Requested
    service           -- Vss Service
    snapshot          -- Snapshot
    state             -- State
    status            -- Status
    uncommittedSpace  -- Uncommitted Space
    usedSpace         -- Used Space
    vmtRunning        -- VMware Tools Running Status
    vmtVersion        -- VMware Tools Version Status

For example, to generate an inventory file in **CSV** format which includes: memory, provisionedSpace,
folder and domain, the command should look like:

.. code-block:: bash

    vss-cli compute inventory mk memory provisionedSpace folder domain --fmt=csv

By default, the ``vss-cli`` won't transfer the file to your personal space at `VSKEY-STOR`_, however if
you wish to have a copy of the report stored there, add the ``--transfer`` option to the command as
follows:

.. code-block:: bash

    vss-cli compute inventory mk memory provisionedSpace folder domain --fmt=csv --transfer

Once the request is completed, the file should be downloadable wit the ``vss-cli compute inventory dl``
command or via the web interface of `VSKEY-STOR`_.

Download
--------

To download the inventory file generated by the ``mk`` command, the ``vss-cli compute inventory dl``
provides the tools to specify a target directory ``-d/--directory`` or open ``-l/--launch`` the
downloaded file with the default application (Excel, Numbers, Calc, etc.).

For example, to download an open the file with the default application:

.. code-block:: bash

    vss-cli compute inventory dl -d ~/Downloads -l <request-number>


Create and Download
-------------------

Creating and downloading inventory files is now possible with the ``--wait`` option that checks
for the request complete and prompt for downloading the file as follows:

.. code-block:: bash

    vss-cli --wait  compute inventory mk memory provisionedSpace folder domain --fmt=csv

    id                  : 0000
    status              : SUBMITTED
    task_id             : fa762cac-6772-480a-bc31-311468db1977
    message             : Request has been accepted for processing
    ⏳ Waiting for request to complete. -

    🎉 Request completed successfully.
    warnings            : Inventory Report has been created fad51dd5-e6d4-495e-865a-7ad27129e4f5.csv
    errors              :
    Would you like to download? [y/N]: y

    FILE                : ./fad51dd5-e6d4-495e-865a-7ad27129e4f5.csv

.. _`VSKEY-STOR`: https://vskey-stor.eis.utoronto.ca