AlgoKit CLI for contributors

May 28, 2026 · View on GitHub

Commits

We are using the Conventional Commits standard for commit messages. This allows us to automatically generate release notes and version numbers. We do this via Python Semantic Release and GitHub actions.

Guiding Principles

AlgoKit development is done within the AlgoKit Guiding Principles.

Setup (AlgoKit CLI development)

Initial setup

Clone this repository: git clone https://github.com/algorandfoundation/algokit-cli
Install pre-requisites:
- Install uv - the project's package manager:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- Run uv sync in the repository root directory (this sets up .venv and installs all Python dependencies)
- Install tealer - by running uv tool install tealer==0.1.2. This is a prerequisite to running pytest, tealer is a third party tool for static analysis of TEAL code, algokit uses it in task analyse command. AlgoKit uses pytest-xdist to speed up the test suite execution by running tests in parallel, this requires tealer to be installed globally to avoid race conditions.
Install pre-commit hooks (optional but recommended):

pre-commit is configured in this repository. To enable it, make sure that uv sync has been run. Then execute uv run pre-commit install to install the git hook scripts.

Once it is done, git will ensure formatting, linting, and static typing (via mypy) is correct when you perform a commit.
Open the project and start debugging / developing via:
- VS Code
  1. Open the repository root in VS Code.
  2. Install recommended extensions.
  3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
    
    Note The first time you run, VS Code may prompt you to select the Python Interpreter, or if you are having issues running you may need to select it via the Python: Select Interpreter pallette command. You should select the Python Interpreter with the ./.venv path)
- IDEA (e.g. PyCharm)
  1. Open the repository root in the IDE
  2. Hit Shift+F9 (or whatever you have debug mapped to) and it should start running with breakpoint debugging
- Other
  1. Open the repository root in your text editor of choice
  2. In a terminal run uv run python or activate the venv with source .venv/bin/activate
  3. Run ./debug.py through your debugger of choice
- In each of the above cases, an args.in file will be created in the source root. Each line will be executed in order, with the arguments passed to the cli. For example, you could have:
```
version
--help
version --help
```
  Not a terribly useful sequence of commands, but hopefully this helps illustrate the usage.

Subsequently

If you update to the latest source code and there are new dependencies you will need to run uv sync again
Follow step 3 above

Documentation

Markdown documentation can be found within the docs directory of the repo, there is a mixture of handwritten documentation and autogenerated documentation for the CLI tool itself.

To autogenerate the CLI documentation from the click source:

Install the docs dependencies: uv sync --group docs
Run the docs generation: uv run poe docs

Note: this command won't work on Windows.

The CLI docs are generated using Sphinx, and its configuration can be found in docs\sphinx. The generated Markdown output is post processed to add a Table of Contents and top level title and the final Markdown is output to docs\cli. The commands to achieve this are defined in pyproject.toml under [tool.poe.tasks]

Libraries and Tools

AlgoKit uses Python as a main language and many Python libraries and tools. This section lists all of them with a tiny brief.

uv: Python packaging, dependency management, and tool installation.
Click: A Python package for creating beautiful command line interfaces.
Ruff: An extremely fast Python linter and formatter.

Architecture decisions

As part of developing AlgoKit we are documenting key architecture decisions using Architecture Decision Records (ADRs). The following are the key decisions that have been made thus far: