iap-cli 2024.4a1

Lightweight CLI tool to simplify the process of interacting with the Itential Automation Platform.

itential-iap-cli

Lightweight CLI tool to simplify the process of interacting with the Itential Automation Platform.

This is an early alpha release. It is incomplete and will change.

The CLI tool is built using Typer and Typer-CLI. It uses iap-sdk for any API calls to IAP.

This package was written for Itential Automation Platform 2023.1.

Installation

Make sure you have a supported version of Python installed, and then create and activate a virtual environment:

python -m venv venv
source /venv/bin/activate
python -m pip install --upgrade pip

You can install the iap_cli from Pypi as follows:

pip install iap-cli

Or you can install it from source as follows:

git clone https://github.com/awetomate/itential-iap-cli.git
cd itential-iap-cli
python -m pip install -r requirements.txt
python -m pip install -e .

Verify

Verify that the CLI tool got installed correctly:

iap version

If the 'iap' command does not get recognised, try adding your current path to the Python path as follows:

export PYTHONPATH=`pwd`

Install autocompletion for your shell

Install the autocompletion for your shell using the following command and then restart your terminal.

iap --install-completion

First Steps / Setup

Use the --help option

Use the --help option to see all available command completions for the current position. In most cases, sending an incomplete command will also show the help page. If you have the autocompletion installed, you can just hit TAB-TAB, which will keep autocompleting and showing the available options.

iap --help

 Usage: iap [OPTIONS] COMMAND [ARGS]...

 CLI tool for interacting with Itential.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                                                                         │
│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                                                  │
│ --help                        Show this message and exit.                                                                                                       │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ config                  Manage configurations for the Itential CLI app.                                                                                         │
│ get                     Get resources from your IAP server.                                                                                                     │
│ restart                 Restart resources in your IAP server.                                                                                                   │
│ version                                                                                                                                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

iap get --help

 Usage: iap get [OPTIONS] COMMAND [ARGS]...

 Get resources from your IAP server.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ adapters                       Get the health of all adapters for one or more servers.                                                                          │
│ applications                   Get the health of all applications for one more servers.                                                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

1. Configure username and password

Define the username and password that will be used to connect to the IAP servers. The credentials will be stored in a .env file in your user profile. The CLI tool will use these credentials for all API calls.

iap config add credentials

Provide the user credentials to use to authenticate with the Itential servers.
The credentials will be stored in the /Users/your_user/.iap_cli/.env file.
Username: your_username
Password:

2. Add servers to your inventory

Add servers and/or clusters to an inventory file. An inventory.json file will created in your user profile.

Add individual server:

iap config add server

Provide a friendly name for the server (will be used for all CLI operations) and an FQDN/IP address.
The server will be stored in the /Users/your_user/.iap_cli/inventory.json file.
Server Friendly Name: dev1
Server FQDN or IP: iap1-dev.domain.com

Add a server cluster:

iap config add cluster

Provide a friendly name for the cluster (will be used for all CLI operations) and a comma-separated list of FQDNs/IP addresses.
The cluster will be stored in the /Users/your_user/.iap_cli/inventory.json file.
Cluster Friendly Name: devAll
Server FQDNs or IP addresses: iap1-dev.domain.com,iap2-dev.domain.com,iap3-dev.domain.com

The commands above will create an inventory.json file that looks like this:

{
    "dev1": "iap1-dev.domain.com",
    "dev2": "iap2-dev.domain.com",
    "dev3": "iap3-dev.domain.com",
    "devAll": [
        "iap1-dev.domain.com",
        "iap2-dev.domain.com",
        "iap3-dev.domain.com"
    ]
}

If you have the autocompletion installed, you can just hit TAB-TAB, which will keep autocompleting and showing the available server/cluster names.

iap restart application AGManager dev
dev1    dev2    dev3    devAll

You can also modify the inventory.json file directly.

Available Operations

config

operation	description
iap config add credentials	Creates/updates a .env file to store the username and password to use for the API calls to IAP
iap config add cluster	Creates/updates an inventory.json file to store the server connections in. Cluster Friendly Name: Friendly/short name to identify the cluster. You will use this value for all CLI operations. E.g. devAll or PROD or cluster1 Server FQDNs or IP addresses: A comma-separated string containing all server FQDNs or IP addresses. E.g. iap1-dev.domain.com,iap2-dev.domain.com,iap3-dev.domain.com
iap config add server	Creates/updates an inventory.json file to store the server connections in. Server Friendly Name: Friendly/short name to identify the server. You will use this value for all CLI operations. E.g. dev1 or PROD1 or server1 Server FQDNs or IP addresses: The FQDN or IP address of the server. E.g. iap1-dev.domain.com

get

operation	description
iap get adapters host	Get a list and health status for all adapters on the target server/cluster host: Use the friendly name of the server/cluster as the target host. Examples: iap get adapters dev1 iap get adapters devAll
iap get applications host	Get a list and health status for all applications on the target server/cluster host: Use the friendly name of the server/cluster as the target host. Examples: iap get applications dev1 iap get applications devAll

If you have the autocompletion installed, you can just hit TAB-TAB, which will keep autocompleting and showing the available server/cluster names.

restart

operation	description
iap restart adapter name host	Start (if adapter is stopped) or restart an adapter in a server or a cluster of servers. name: Enter the name of the adapter to start/restart(case-sensitive!) host: Use the friendly name of the server/cluster as the target host. Examples: iap restart adapter ServiceNow devAll iap restart adapter Email dev1 NOTE: the adapter name is case-sensitive!
iap restart application name host	Start (if application is stopped) or restart an application in a server or a cluster of servers. name: Enter the name of the application to start/restart. Use autocompletion or use --help to see the list of available application names. host: Use the friendly name of the server/cluster as the target host. Examples: iap restart application AGManager devAll iap restart application Jst dev1

If you have the autocompletion installed, you can just hit TAB-TAB, which will keep autocompleting and showing the available server/cluster names and Application names (this does not work for adapter names).

version

operation	description
iap version	Displays the CLI app version.