<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Overview](#overview)
- [Design](#design)
- [Features](#features)
- [Plugin Architecture](#plugin-architecture)
- [Creating Plugins](#creating-plugins)
- [Installing Plugins](#installing-plugins)
- [Usage examples](#usage-examples)
- [Usage examples - Utilizing Windows Credentials Manager](#usage-examples---utilizing-windows-credentials-manager)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [ecli](#ecli)
- [Appendix](#appendix)
- [Sub-Command naming logic](#sub-command-naming-logic)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<a name="top"></a>
<a name="overview"></a>
# 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?_<br />
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.
<a name="design"></a>
# 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.
<a name="features"></a>
## Features
- Commands are executables organized by subfolders in a given plugin directory<br />
(See the Appendix for list of supported executable types)
- Subfolders are interpreted as the namespace name for<br />
the given scripts/executables contained therein
- Subcommands follow a dot-notation style of reference, e.g.<br />
_pluginfolder.namespace.command_<sup> [1](#sub-command-naming-logic)</sup>
<a name="installation"></a>
# Installation
<a name="prerequisites"></a>
## Prerequisites
You'll need python3 & pip for the pip distribution.
To install,
* For Windows:
* <a href="https://community.chocolatey.org/" target="_blank">choco</a>
1. Start an elevated powershell prompt and run the following commands:
1. `Set-Variable -Name "ChocolateyInstall" -Value "$(Join-Path -Path $Env:LocalAppData -ChildPath chocolatey)"`
1. `New-Item $ChocolateyInstall -Type Directory -Force`
1. `[Environment]::SetEnvironmentVariable("ChocolateyInstall", $ChocolateyInstall)`
1. `Set-ExecutionPolicy Bypass -Scope Process iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))`
* Microsoft C++ Build Tools: `choco install visualstudio2017buildtools`<br />
Or Install the latest from the Microsoft Website: [https://visualstudio.microsoft.com/visual-cpp-build-tools/](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
* python 3.7.x: `choco install python --version=3.7.4` <br />
* 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](#top)
<a name="ecli"></a>
## Installing ecli
There are two distributions of the `ecli`
1. python package: Installed via
`pip3 install btecli`
1. The Windows bundled executable, available via [Releases](https://github.com/berttejeda/bert.ecli/releases)<br />
Note that the bundled executable can be slow to initialize.<br />
This is because python itself is bundled into the ecli binary<br />
The python package runs much faster, as there<br />
is no need unpacking resources.<br />
Also, it has a much slower release cadence.
1. If you are behind a corporate proxy, and get SSL errors
when installing, try your installation command with
the `--trusted-host` flags, as with:<br />
```bash
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](#top)
<a name="plugin-architecture"></a>
# 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.
<a name="creating-plugins"></a>
## 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,<br />
python, powershell, or ruby to get started.
I will eventually add binaries (e.g. golang, Windows .exe's)
and rust to the mix.
<a name="installing-plugins"></a>
## 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](#top)
# Usage examples
<a name="usage-examples---utilizing-windows-credentials-manager"></a>
## 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](#top)
<a name="appendix"></a>
# Appendix
<a name="sub-command-naming-logic"></a>
## Sub-Command naming logic
As mentioned in the previous sections, commands follow a dot-notation style of reference,<br />
e.g. _pluginfolder.namespace.command_.
Of note is that the _pluginfolder_ prefix only takes effect for<br />
plugin folders not bearing a name similar to _ecli.plugins_ e.g. a plugin folder<br />
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_, <br />
its effective name will be stripped of that pattern, i.e. the following plugin folders:<br />
- 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_
Raw data
{
"_id": null,
"home_page": "https://github.com/berttejeda/bert.ecli.git",
"name": "btecli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "",
"keywords": "bash,python,click,subprocess,yaml,cli,options,extensible,plugins,polyglot",
"author": "Engelbert Tejeda",
"author_email": "berttejeda@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/20/ce/5745e301ba1c2bcd98462393c704f3e8c6cc347b5a5164f4d61ee0dcb4f3/btecli-2.0.0.tar.gz",
"platform": null,
"description": "<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Overview](#overview)\n- [Design](#design)\n - [Features](#features)\n- [Plugin Architecture](#plugin-architecture)\n - [Creating Plugins](#creating-plugins)\n - [Installing Plugins](#installing-plugins)\n- [Usage examples](#usage-examples)\n - [Usage examples - Utilizing Windows Credentials Manager](#usage-examples---utilizing-windows-credentials-manager)\n- [Installation](#installation)\n - [Prerequisites](#prerequisites)\n - [ecli](#ecli)\n- [Appendix](#appendix)\n - [Sub-Command naming logic](#sub-command-naming-logic)\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n<a name=\"top\"></a>\n<a name=\"overview\"></a>\n\n# Overview\n\nAs systems engineers, we spend much of our time on our command-line terminals\ninteracting with a myriad of systems in support of the overarching infrastructure.\n\nOur daily tasks can often be repetitive, \nwhich is why we often find ourselves utilizing \nor creating automation to lessen our keystrokes.\n\nThis brings us to a question:\n\n- _What do you get when each member of a team of engineers has an affinity\n for creating their own little scripts to make their lives easier?_<br />\n Hint: It's something messy.\n \nThe *ecli* app aims to clean up this proclivity for command-line mess in the team setting\nby unifying disparate pieces of automation into a single entrypoint, thus \ncreating a homogenous command-line experience.\n\nThis is accomplished by a modular design that can accomodate just about any executable\npiece of code.\n\nThe following sections go over this in detail.\n\n<a name=\"design\"></a>\n# Design\n\nThe *ecli* app is made up of two major components:\n\n- A base command module written in python\n- Plugins that extend the base command module\n\nThe plugin system essentially allows contributers to \ndefine namespaces of commands, along with their corresponding \nsubcommands.\n\n<a name=\"features\"></a>\n## Features\n\n - Commands are executables organized by subfolders in a given plugin directory<br />\n (See the Appendix for list of supported executable types)\n - Subfolders are interpreted as the namespace name for<br />\n the given scripts/executables contained therein\n - Subcommands follow a dot-notation style of reference, e.g.<br />\n _pluginfolder.namespace.command_<sup> [1](#sub-command-naming-logic)</sup>\n\n<a name=\"installation\"></a>\n# Installation\n\n<a name=\"prerequisites\"></a>\n## Prerequisites\n\nYou'll need python3 & pip for the pip distribution.\n\nTo install,\n\n* For Windows:\n * <a href=\"https://community.chocolatey.org/\" target=\"_blank\">choco</a>\n 1. Start an elevated powershell prompt and run the following commands:\n 1. `Set-Variable -Name \"ChocolateyInstall\" -Value \"$(Join-Path -Path $Env:LocalAppData -ChildPath chocolatey)\"`\n 1. `New-Item $ChocolateyInstall -Type Directory -Force`\n 1. `[Environment]::SetEnvironmentVariable(\"ChocolateyInstall\", $ChocolateyInstall)`\n 1. `Set-ExecutionPolicy Bypass -Scope Process iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))`\n * Microsoft C++ Build Tools: `choco install visualstudio2017buildtools`<br />\n Or Install the latest from the Microsoft Website: [https://visualstudio.microsoft.com/visual-cpp-build-tools/](https://visualstudio.microsoft.com/visual-cpp-build-tools/)\n * python 3.7.x: `choco install python --version=3.7.4` <br />\n* For Linux, just install python3 via your distro's package manager.\n* For OSX, if not already present, I recommend you install \n python3 via the `brew` package manager\n\n[Back to Top](#top)\n<a name=\"ecli\"></a>\n## Installing ecli\n\nThere are two distributions of the `ecli`\n\n1. python package: Installed via \n `pip3 install btecli`\n1. The Windows bundled executable, available via [Releases](https://github.com/berttejeda/bert.ecli/releases)<br />\n Note that the bundled executable can be slow to initialize.<br />\n This is because python itself is bundled into the ecli binary<br />\n The python package runs much faster, as there<br />\n is no need unpacking resources.<br />\n Also, it has a much slower release cadence.\n1. If you are behind a corporate proxy, and get SSL errors \n when installing, try your installation command with \n the `--trusted-host` flags, as with:<br />\n```bash\npip3 install \\\n--trusted-host=pypi.org \\\n--trusted-host=github.com \\\n--trusted-host=files.pythonhosted.org \\\nbtecli\n```\n\nThe next section will cover Plugins.\n\n[Back to Top](#top)\n<a name=\"plugin-architecture\"></a>\n# Plugin Architecture\n\nAs mentioned before, the ecli plugins extend the base command module.\nThat is, for every plugin detected, a new ecli subcommand is made available.\n\n<a name=\"creating-plugins\"></a>\n## Creating Plugins\n\nPlugins are really easy to create, as they are simply executable \nfiles neatly organized into folders bearing the name of \nthe plugin's namespace.\n\nYou need only enough proficiency to write a script in either bash,<br /> \npython, powershell, or ruby to get started. \nI will eventually add binaries (e.g. golang, Windows .exe's) \nand rust to the mix.\n\n<a name=\"installing-plugins\"></a>\n## Installing Plugins\n\nInvoke the `plugins.install` built-in subcommand to install a \ngiven plugin repo. The syntax is `ecli plugins.install -S -r <gitrepo>`.\n\nYou can install my plugin repo to start:\n\n`ecli plugins.install -S -r https://github.com/berttejeda/bert.ecli.plugins.git -a ecli.plugins`\n\nOnce you've installed a plugin repo, run `ecli` to get \nthe list of newly available subcommands \n\nThe usage examples in the following sections \nassume you've installed the plugin repository above.\n\n[Back to Top](#top)\n# Usage examples\n\n<a name=\"usage-examples---utilizing-windows-credentials-manager\"></a>\n## Usage examples - Utilizing Windows Credentials Manager\n\nWe'll be demonstrating ecli's integration with \nWindows Credential Manager.\n\nThe first step is to create Windows Generic Credentials \na given subcommand.\n\nYou can do that by launching credential \nmanager via ecli: `ecli system.launcher -n cred-mgr`\n\nOnce the Windows Credential manager is in view,\n\n- Click Windows Credentials\n- Then click Add generic credential\n - Internet or network address: {{ name_of_subcommand }}\n - User name: {{ username }}\n - Password: {{ password }}\n\nWith these populated, ecli should be able to read \nfrom the Windows credential store when you\ncall the given subcommand with the `--use-cred-mgr flag`.\n\nDoing so will populate variables _$username_ and _$password_ during command runtime.\n\n[Back to Top](#top)\n<a name=\"appendix\"></a>\n# Appendix\n\n<a name=\"sub-command-naming-logic\"></a>\n## Sub-Command naming logic\n\nAs mentioned in the previous sections, commands follow a dot-notation style of reference,<br />\ne.g. _pluginfolder.namespace.command_.\n\nOf note is that the _pluginfolder_ prefix only takes effect for<br />\nplugin folders not bearing a name similar to _ecli.plugins_ e.g. a plugin folder<br />\nnamed _foo_ will yield plugins conforming to _foo.namespace.command_.\n\nHowever, if a plugin folder name matches the regular expression _ecli.plugins[\\W]+?|ecli.plugins_, <br />\nits effective name will be stripped of that pattern, i.e. the following plugin folders:<br />\n\n- ecli.plugins\n- ecli.plugins-fork\n- ecli.plugins01\n- ecli.plugins-02\n- ecli.plugins.new\n\nwill yield sub-commands with the following dot-notation (respectively):\n\n- _namespace.command_\n- _fork.namespace.command_\n- _01.namespace.command_\n- _02.namespace.command_\n- _new.namespace.command_\n",
"bugtrack_url": null,
"license": "",
"summary": "Extensible CLI",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/berttejeda/bert.ecli.git"
},
"split_keywords": [
"bash",
"python",
"click",
"subprocess",
"yaml",
"cli",
"options",
"extensible",
"plugins",
"polyglot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "623c2c1056172ecc2e01e943a42072c10373594399d391ca82009ebd41f533cb",
"md5": "ac673d677d950af47edb56b07dd8e855",
"sha256": "8b6c44b17a8440ec27f57ea8ca3eb1c717e074aad11199a4a4a707fca32702aa"
},
"downloads": -1,
"filename": "btecli-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac673d677d950af47edb56b07dd8e855",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 22393,
"upload_time": "2023-07-18T21:13:18",
"upload_time_iso_8601": "2023-07-18T21:13:18.571029Z",
"url": "https://files.pythonhosted.org/packages/62/3c/2c1056172ecc2e01e943a42072c10373594399d391ca82009ebd41f533cb/btecli-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "20ce5745e301ba1c2bcd98462393c704f3e8c6cc347b5a5164f4d61ee0dcb4f3",
"md5": "e54486f1902e662513eaf4c28dbd4a51",
"sha256": "2b6a7f08e0cbd4a3aeadcc0cdb016e8b16ca69c2ddaeb034953dca9edb76939b"
},
"downloads": -1,
"filename": "btecli-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e54486f1902e662513eaf4c28dbd4a51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 39437,
"upload_time": "2023-07-18T21:13:19",
"upload_time_iso_8601": "2023-07-18T21:13:19.861158Z",
"url": "https://files.pythonhosted.org/packages/20/ce/5745e301ba1c2bcd98462393c704f3e8c6cc347b5a5164f4d61ee0dcb4f3/btecli-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-18 21:13:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "berttejeda",
"github_project": "bert.ecli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "btecli"
}
JSON
