Leverage CLI
Leverage CLI is the tool used to manage and interact with any Leverage project.
It transparently handles the most complex and error-prone tasks that arise from working with a state-of-the-art infrastructure definition like our Leverage Reference Architecture. It understands the structure of the Leverage Reference Architecture and assists the user in their day-to-day operation.
Leverage CLI orchestrates a set of tools used to operate in a Leverage project. Usually this means OpenTofu/Terraform, but also aws-cli, kubectl and more.
Reviewing and implementing the Binbash Leverage Landing Zone for AWS would be a very good place to start!
Documentation
For installation instructions and all documentation regarding Leverage CLI, please refer to this page.
Note for migration from previous versions
If you come from Leverage CLI version <3.0.0 and want to use Leverage CLI version >= 3.0.0 keep into account the following.
Leverage CLI no longer runs tools inside a Docker container; it executes the OpenTofu/Terraform binaries installed on
your host. Because of this, the TERRAFORM_IMAGE_NAME/TF_IMAGE_NAME and TERRAFORM_IMAGE_TAG/TF_IMAGE_TAG
parameters in the build.env file no longer exist. In their place, the optional TF_BINARY parameter specifies the path
to the OpenTofu/Terraform binary to use. As an example, this is the old format:
# Project settings
PROJECT=bb
# General
MFA_ENABLED=false
# Terraform
TF_IMAGE_TAG=1.5.0-0.2.0
New version example:
# Project settings
PROJECT=bb
# General
MFA_ENABLED=false
# OpenTofu/Terraform binary
TF_BINARY=/usr/local/bin/tofu
So, if you have created a project with version <3.0.0 and want to use it with version >=3.0.0 you should:
- remove the
TERRAFORM_IMAGE_NAME/TF_IMAGE_NAMEandTERRAFORM_IMAGE_TAG/TF_IMAGE_TAGlines - install OpenTofu or Terraform on your host
- optionally, set
TF_BINARYto the path of the binary. This is useful when you have multiple versions of OpenTofu/Terraform installed, or when the binary lives in an unconventional location. It can be an absolute path, a path starting with~, or a path relative to the project root. If not set, thetofuorterraformbinary is looked up in yourPATH. Keep in mind the binary must match the command you use:leverage tofuexpects OpenTofu andleverage terraformexpects Terraform.
System requirements
Supported python versions
Leverage CLI explicitly supports the following Python versions:
- Python 3.9.x
- Python 3.10.x
- Python 3.11.x
- Python 3.12.x
- Python 3.13.x
These versions are not only supported but are also the only versions used in our CI/CD pipelines to ensure compatibility and performance. This rigorous testing helps prevent compatibility issues and ensures that the Leverage CLI performs as expected under these versions.
Please ensure that your development and deployment environments are set up with one of these supported versions. Our GitHub Actions and other CI workflows are specifically configured to test against these Python versions, which reinforces our commitment to maintaining a reliable and stable toolset.
Installing multiple python versions with pyenv
If you need to install one of the supported Python versions and would like to manage multiple
Python environments, pyenv is a highly recommended tool. Here’s how you can use pyenv to install and manage Python
versions:
- Installing Pyenv:
curl https://pyenv.run | bash
- Add Pyenv to your shell to automate the setup process (if using bash, otherwise you can find details on how to set it up here):
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
exec "$SHELL"
- Installing python versions:
Once pyenv is installed, you can install any supported Python version by following these steps:
pyenv install 3.9.7
pyenv install 3.10.1
pyenv install 3.11.8
pyenv install 3.12.7
pyenv install 3.13.6
- Create a virtual environment for the leverage project:
Create a virtual environment for your project using Python 3.13.x:
pyenv virtualenv 3.13.6 leverage_py_313_venv
- Set your virtual environment to be used in the project:
To set this virtual environment as the local environment for your project, navigate to your project directory and run:
cd <path_to_leverage_project_root>
pyenv local leverage_py_313_venv
This setup commands pyenv to use leverage_py_313_venv as the local Python version for your project directory,
ensuring that all Python operations within this directory use this isolated environment.
Setting up development environment
Before you begin, ensure you are running one of the supported Python versions.
We now use Poetry for dependency management. Setup your development environment as follows:
- Install Poetry:
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.8.2 python -
- Clone the repository and navigate into it:
git clone https://github.com/binbashar/leverage.git
cd leverage
- Install dependencies using Poetry:
poetry install --with=dev --with=main
- To activate the virtual environment and start using the CLI in dev mode, use:
poetry shell
Pre-commit hooks
In order to run black automatically on every commit, you should install pre-commit first:
https://pre-commit.com/#installation
And then the hooks:
poetry run pre-commit install
Running Tests
To run unit tests, pytest is the tool of choice, and the required dependencies are available in the
corresponding dev-requirements.txt.
Integration tests are implemented using bats. They drive the installed
leverage command, and work on temporary directories of their own, so they can be run directly on your machine.
- Unit tests:
poetry run pytest
- Integration tests:
Install dependencies (MacOS):
brew install bats-core
brew tap bats-core/bats-core
brew install bats-support
brew install bats-assert
The cli runs the infrastructure binaries directly, so terraform and tofu need to be installed as well. See
System requirements.
bats -r tests/bats
If bats-support and bats-assert are not installed in a location bats searches by default, point BATS_LIB_PATH at
the directory holding them:
BATS_LIB_PATH=/opt/homebrew/lib bats -r tests/bats
Alternatively, make tests runs both suites, and make test-unit or make test-int runs one of them.
Release Process
- On every PR, a Github Action workflow is triggered to create/update a release draft.
- The version number is determined by the labels of those PRs (major, minor, fix).
- The release draft has to be manually published. This allows for any number of PR (features, fixes) to make the cut.
- Once a release is published, another workflow is triggered to create and push the package to PyPi.
Release Candidate Process
- There is an Action called "Test Build Package and Push".
- This Action can be called manually on any branch specifying the version to release to test.
- The version is a Release Candidate following the Semver: e.g. if the next release is 1.2.3, the test version should be 1.2.3rc.1
- The package will be published to PyPi.
Contributors/Contributing
- Leverage CLI was initially based on Pynt: https://github.com/rags/pynt
License
Leverage CLI is licensed under MIT licenseBinBash Inc
Metadata
Release files for leverage 3.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| leverage-3.2.0.tar.gz | 54.3 kB | Without provenance | Details for leverage-3.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| leverage-3.2.0-py3-none-any.whl | Python 3 | none | any | Details for leverage-3.2.0-py3-none-any.whl |
Total release size: 115.7 kB
Release files / leverage-3.2.0.tar.gz
| Download URL | leverage-3.2.0.tar.gz |
|---|---|
| Size | 54.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c2eac8bd9397ecfce2d89de12d8ba24814021c15d5e82e100c212ad9a057a5b
|
|
BLAKE2b-256 checksum How to use checksums |
5a4253930556db9a2d000be137dd90b28123db6ca90f88dbc0a70c0bebe33e08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.18
|
Release files / leverage-3.2.0-py3-none-any.whl
| Download URL | leverage-3.2.0-py3-none-any.whl |
|---|---|
| Size | 61.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
43a888d15002825ff6c68677e9601ec36173dfad599d36287818dba5757759cb
|
|
BLAKE2b-256 checksum How to use checksums |
260f49820b926ec173faacf02b309167613d739855d575af773e240815ee1393
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.18
|
Security for leverage 3.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.