xpln 🛠️

xpln is a python package made available as a CLI tool that explains terminal commands for you to understand what they do before you execute them.

📦Installation

xpln is available on PyPI under the package name xpln2me. It can be installed by running

pip install xpln2me

At this point, xpln should be globally accessible from the terminal!

Note

On linux, this may not be as straightforward due to restrictions of direct installations of non-Debian-packaged Python packages. It's recommended to use pipx install xpln2me for this instead which will automatically create a virtual environment to install the package and creates a symlink in /.local/bin/xpln pointing to the real executable

📌 Usage

Basic Usage

Run xpln on the terminal to begin, or xpln --help to get the available commands

xpln is powered by Google AI Studio, hence requires an an API Key to initialize and an internet connection to use. Once you have an API Key, initialize the CLI by running xpln init and following the instructions. This key can be updated at any time by running xpln init with the --update / -u option

Alternatively, an API Key can be directly specified by including the --key / -k option

xpln init --key <API KEY>

xpln init --update --key <UPDATED API KEY>

Once initialized, use the this command to get explanations of different commands

xpln this <COMMAND>

Example Usage

There are 2 ways of using xpln:

1. Directly pasting commands into xpln this

xpln this ls -al

2. Piping the input into xpln this

cat script.sh | xpln this

⚙️ Technical Details

Tools Used

• Python 3.12 - Core language
• Poetry - Dependency & package management
• Click/Typer - CLI framework
• GitHub Actions - CI/CD automation

How xpln2me is Packaged

• Python CLI tools can be packaged as:

  • sdist [Source Distribution] - Requires building before installation
  • Wheel (.whl) [Built Distribution] - Prebuilt, faster to install

• This project uses Poetry to build and distribute both formats.

Versioning & Automated Releases

• Uses Semantic Versioning: MAJOR.MINOR.PATCH
• On PR merge, GitHub Actions:
  1. Bumps the version

     This is done by including special indicators in PR titles (commit messages to main)

     • #major - bumps the major version
     • #minor - bumps the minor version
     • Failure to include one of these bumps the patch version

  2. Creates a Git tag
  3. Publishes to PyPI the new version