btecli 2.0.0

Extensible CLI

Table of Contents generated with DocToc

• Overview
• Design
  • Features
• Plugin Architecture
  • Creating Plugins
  • Installing Plugins
• Usage examples
  • Usage examples - Utilizing Windows Credentials Manager
• Installation
  • Prerequisites
  • ecli
• Appendix
  • Sub-Command naming logic

Overview

As systems engineers, we spend much of our time on our command-line terminals interacting with a myriad of systems in support of the overarching infrastructure.

Our daily tasks can often be repetitive, which is why we often find ourselves utilizing or creating automation to lessen our keystrokes.

This brings us to a question:

• What do you get when each member of a team of engineers has an affinity for creating their own little scripts to make their lives easier?
  Hint: It's something messy.

The ecli app aims to clean up this proclivity for command-line mess in the team setting by unifying disparate pieces of automation into a single entrypoint, thus creating a homogenous command-line experience.

This is accomplished by a modular design that can accomodate just about any executable piece of code.

The following sections go over this in detail.

Design

The ecli app is made up of two major components:

• A base command module written in python
• Plugins that extend the base command module

The plugin system essentially allows contributers to define namespaces of commands, along with their corresponding subcommands.

Features

• Commands are executables organized by subfolders in a given plugin directory
  (See the Appendix for list of supported executable types)
• Subfolders are interpreted as the namespace name for
  the given scripts/executables contained therein
• Subcommands follow a dot-notation style of reference, e.g.
  pluginfolder.namespace.command ¹

Installation

Prerequisites

You'll need python3 & pip for the pip distribution.

To install,

• For Windows:
  • choco
    1. Start an elevated powershell prompt and run the following commands:
    2. Set-Variable -Name "ChocolateyInstall" -Value "$(Join-Path -Path $Env:LocalAppData -ChildPath chocolatey)"
    3. New-Item $ChocolateyInstall -Type Directory -Force
    4. [Environment]::SetEnvironmentVariable("ChocolateyInstall", $ChocolateyInstall)
    5. Set-ExecutionPolicy Bypass -Scope Process iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))
  • Microsoft C++ Build Tools: choco install visualstudio2017buildtools
    Or Install the latest from the Microsoft Website: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  • python 3.7.x: choco install python --version=3.7.4
    
• For Linux, just install python3 via your distro's package manager.
• For OSX, if not already present, I recommend you install python3 via the brew package manager

Back to Top

Installing ecli

There are two distributions of the ecli

1. python package: Installed via pip3 install btecli
2. The Windows bundled executable, available via Releases
   Note that the bundled executable can be slow to initialize.
   This is because python itself is bundled into the ecli binary
   The python package runs much faster, as there
   is no need unpacking resources.
   Also, it has a much slower release cadence.
3. If you are behind a corporate proxy, and get SSL errors when installing, try your installation command with the --trusted-host flags, as with:
   

pip3 install \
--trusted-host=pypi.org \
--trusted-host=github.com \
--trusted-host=files.pythonhosted.org \
btecli

The next section will cover Plugins.

Back to Top

Plugin Architecture

As mentioned before, the ecli plugins extend the base command module. That is, for every plugin detected, a new ecli subcommand is made available.

Creating Plugins

Plugins are really easy to create, as they are simply executable files neatly organized into folders bearing the name of the plugin's namespace.

You need only enough proficiency to write a script in either bash,
python, powershell, or ruby to get started. I will eventually add binaries (e.g. golang, Windows .exe's) and rust to the mix.

Installing Plugins

Invoke the plugins.install built-in subcommand to install a given plugin repo. The syntax is ecli plugins.install -S -r <gitrepo>.

You can install my plugin repo to start:

ecli plugins.install -S -r https://github.com/berttejeda/bert.ecli.plugins.git -a ecli.plugins

Once you've installed a plugin repo, run ecli to get the list of newly available subcommands

The usage examples in the following sections assume you've installed the plugin repository above.

Back to Top

Usage examples

Usage examples - Utilizing Windows Credentials Manager

We'll be demonstrating ecli's integration with Windows Credential Manager.

The first step is to create Windows Generic Credentials a given subcommand.

You can do that by launching credential manager via ecli: ecli system.launcher -n cred-mgr

Once the Windows Credential manager is in view,

• Click Windows Credentials
• Then click Add generic credential
  • Internet or network address: {{ name_of_subcommand }}
  • User name: {{ username }}
  • Password: {{ password }}

With these populated, ecli should be able to read from the Windows credential store when you call the given subcommand with the --use-cred-mgr flag.

Doing so will populate variables $username and $password during command runtime.

Back to Top

Appendix

Sub-Command naming logic

As mentioned in the previous sections, commands follow a dot-notation style of reference,
e.g. pluginfolder.namespace.command.

Of note is that the pluginfolder prefix only takes effect for
plugin folders not bearing a name similar to ecli.plugins e.g. a plugin folder
named foo will yield plugins conforming to foo.namespace.command.

However, if a plugin folder name matches the regular expression ecli.plugins[\W]+?|ecli.plugins,
its effective name will be stripped of that pattern, i.e. the following plugin folders:

• ecli.plugins
• ecli.plugins-fork
• ecli.plugins01
• ecli.plugins-02
• ecli.plugins.new

will yield sub-commands with the following dot-notation (respectively):

• namespace.command
• fork.namespace.command
• 01.namespace.command
• 02.namespace.command
• new.namespace.command