algorandfoundation / algokit-cli

The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the Algorand network.

---

The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the Algorand network.

AlgoKit gets developers of all levels up and running with a familiar, fun and productive development environment in minutes. The goal of AlgoKit is to help developers build and launch secure, automated production-ready applications rapidly.

Install AlgoKit | Quick Start Tutorial | Documentation

What is AlgoKit?

AlgoKit compromises of a number of components that make it the one-stop shop tool for developers building on the Algorand network.

AlgoKit can help you learn, develop and operate Algorand solutions. It consists of a number of repositories, including this one.

Learn

There are many learning resources on the Algorand Developer Portal and the AlgoKit landing page has a range of links to more learning materials. In particular, check out the quick start tutorial and the AlgoKit detailed docs page.

If you need help you can access both the Algorand Discord (pro-tip: check out the algokit channel!) and the Algorand Forum.

We have also developed an AlgoKit video series.

Develop

AlgoKit helps you develop Algorand solutions:

• Interaction: AlgoKit exposes a number of interaction methods, namely:
  • AlgoKit CLI: A Command Line Interface (CLI) so you can quickly access AlgoKit capabilities
  • VS Code: All AlgoKit project templates include VS Code configurations so you have a smooth out-of-the-box development experience using VS Code
  • Dappflow: AlgoKit has integrations with Dappflow; a web-based user interface that let's you visualise an Algorand network and deploy and call smart contracts via a graphical user interface
• Getting Started: AlgoKit helps you get started quickly when building new solutions:
  • AlgoKit Templates: Template libraries to get you started faster and quickly set up a productive dev experience
• Development: AlgoKit provides SDKs, tools and libraries that help you quickly and effectively build high quality Algorand solutions:
  • AlgoKit Utils (Python | TypeScript): A set of utility libraries so you can develop, test, build and deploy Algorand solutions quickly and easily
    • algosdk (Python | TypeScript) - The core Algorand SDK providing Algorand protocol API calls, which AlgoKit Utils wraps, but still exposes for advanced scenarios
  • Algorand Python: A semantically and syntactically compatible, typed Python language that works with standard Python tooling and allows you to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM).
  • TEALScript: A subset of TypeScript that can be used to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM).
  • AlgoKit LocalNet: A local isolated Algorand network so you can simulate real transactions and workloads on your computer

Operate

AlgoKit can help you deploy and operate Algorand solutions.

AlgoKit comes with out-of-the-box Continuous Integration / Continuous Deployment (CI/CD) templates that help you rapidly set up best-practice software delivery processes that ensure you build quality in and have a solution that can evolve

What can AlgoKit help me do?

The set of capabilities supported by AlgoKit will evolve over time, but currently includes:

• Quickly run, explore and interact with an isolated local Algorand network (LocalNet)
• Building, testing, deploying and calling Algorand Python / TEALScript smart contracts

For a user guide and guidance on how to use AlgoKit, please refer to the docs.

Future capabilities are likely to include:

• Quickly deploy standardised, audited smart contracts
• Building and deploying Algorand dApps

Is this for me?

The target audience for this tool is software developers building applications on the Algorand network. A working knowledge of using a command line interfaces and experience using the supported programming languages is assumed.

How can I contribute?

This is an open source project managed by the Algorand Foundation. See the contributing page to learn about making improvements to the CLI tool itself, including developer setup instructions.

Install

Prerequisites

The key required dependency is Python 3.10+, but some of the installation options below will install that for you. We recommend using Python 3.12+, as the algokit compile python command requires this version.

AlgoKit also has some runtime dependencies that also need to be available for particular commands.

Note You can still install and use AlgoKit without these dependencies and AlgoKit will tell you if you are missing one for a given command.

• Git: Essential for creating and updating projects from templates. Installation guide available at Git Installation.
• Docker: Necessary for running the AlgoKit LocalNet environment. Docker Compose version 2.5.0 or higher is required. See Docker Installation.
• Node.js: For those working on frontend templates or building contracts using TEALScript. Minimum required versions are Node.js v18 and npm v9. Instructions can be found at Node.js Installation.

Cross-platform installation

AlgoKit can be installed using OS specific package managers, or using the python tool pipx see below for specific installation instructions.

• Windows
• Mac
• Linux
• pipx

Install AlgoKit on Windows

Note This method will install the most recent python3 version via winget. If you already have python 3.10+ installed, you may prefer to use pipx directly instead so you can control the python version used.

1. Ensure prerequisites are installed

   • Git (or winget install git.git)
   • Docker (or winget install docker.dockerdesktop)

     Note See our LocalNet documentation for more tips on installing Docker on Windows

2. Install using WinGet

   1. Install python: winget install python.python.3.11

   2. Restart the terminal to ensure Python and pip are available on the path

      Note Windows has a feature called App Execution Aliases that provides redirects for the Python command that guide users to the Windows Store. Unfortunately these aliases can prevent normal execution of Python if Python is installed via other means, to disable them search for Manage app execution aliases from the start menu, and then turn off entries listed as App Installer python.exe or App Installer python3.exe.

   3. Install pipx:

      pip install --user pipx
      python -m pipx ensurepath
      

   4. Restart the terminal to ensure pipx is available on the path

   5. Install AlgoKit via pipx: pipx install algokit

   6. Restart the terminal to ensure AlgoKit is available on the path

3. Verify installation

Maintenance

Some useful commands for updating or removing AlgoKit in the future.

• To update AlgoKit: pipx upgrade algokit
• To remove AlgoKit: pipx uninstall algokit

Install AlgoKit on Mac

Note This method will install Python 3.10 as a dependency via Homebrew. If you already have python installed, you may prefer to use pipx install algokit as explained here.

1. Ensure prerequisites are installed

   • Homebrew
   • Git (should already be available if brew is installed)
   • Docker, (or brew install --cask docker)

     Note Docker requires MacOS 11+

2. Install using Homebrew brew install algorandfoundation/tap/algokit

3. Restart the terminal to ensure AlgoKit is available on the path

4. Verify installation

Maintenance

Some useful commands for updating or removing AlgoKit in the future.

• To update AlgoKit: brew upgrade algokit
• To remove AlgoKit: brew uninstall algokit

Install AlgoKit on Linux

1. Ensure prerequisites are installed

   • Python 3.10+

     Note There is probably a better way to install Python than to download it directly, e.g. your local Linux package manager

   • pipx

   • Git

   • Docker

2. Continue with step 2 in the following section to install via pipx

Install AlgoKit with pipx on any OS

1. Ensure desired prerequisites are installed

   • Python 3.10+
   • pipx
   • Git
   • Docker

2. Install using pipx pipx install algokit

3. Restart the terminal to ensure AlgoKit is available on the path

4. Verify installation

Maintenance

Some useful commands for updating or removing AlgoKit in the future.

• To update AlgoKit: pipx upgrade algokit
• To remove AlgoKit: pipx uninstall algokit

Verify installation

Verify AlgoKit is installed correctly by running algokit --version and you should see output similar to:

algokit, version 1.0.1

Note If you get receive one of the following errors:

• command not found: algokit (bash/zsh)
• The term 'algokit' is not recognized as the name of a cmdlet, function, script file, or operable program. (PowerShell)

Then ensure that algokit is available on the PATH by running pipx ensurepath and restarting the terminal.

It is also recommended that you run algokit doctor to verify there are no issues in your local environment and to diagnose any problems if you do have difficulties running AlgoKit. The output of this command will look similar to:

timestamp: 2023-03-27T01:23:45+00:00
AlgoKit: 1.0.1
AlgoKit Python: 3.11.1 (main, Dec 23 2022, 09:28:24) [Clang 14.0.0 (clang-1400.0.29.202)] (location: /Users/algokit/.local/pipx/venvs/algokit)
OS: macOS-13.1-arm64-arm-64bit
docker: 20.10.21
docker compose: 2.13.0
git: 2.37.1
python: 3.10.9 (location:  /opt/homebrew/bin/python)
python3: 3.10.9 (location:  /opt/homebrew/bin/python3)
pipx: 1.1.0
poetry: 1.3.2
node: 18.12.1
npm: 8.19.2
brew: 3.6.18

If you are experiencing a problem with AlgoKit, feel free to submit an issue via:
https://github.com/algorandfoundation/algokit-cli/issues/new
Please include this output, if you want to populate this message in your clipboard, run `algokit doctor -c`

Per the above output, the doctor command output is a helpful tool if you need to ask for support or raise an issue.

Troubleshooting

Issue Description	OS(s)	Steps to mitigate
SSL module not available in Python installation, causing pipx install algokit to fail	Debian 12	Run pipx install algokit --python $(which python3) to explicitly use the Python 3 version with SSL support. Ensure that latest pip version is installed, update python alias if needed.

algokit-cli's Issues

Rename Sandbox feature to LocalNet and change all documentation references of "Sandbox" to LocalNet or local network as appropriate to avoid confusion

Bootstrap a project (+ core dependencies)

Acceptance Criteria:

• Running algokit bootstrap within an algokit project directory will ensure that if there is any Python Poetry projects that Poetry is installed (and installs it via pipx if not available) and that poetry install is run for each pyproject.toml
• Running algokit bootstrap within an algokit project directory will ensure that any .env.template files will be copied to .env and any replacement tokens designated by {token_name} will be prompted and replaced if a value provided
• Running algokit bootstrap within an algokit project directory will ensure that if there is any Node.js projects that node LTS is installed and that npm install is run for each package.json
• Bootstrapping works on Windows, Mac and Linux (Ubuntu)
• Project templates have a mechanism to indicate they have a poetry or npm project in a given location that should be bootstrapped and this bootstrapping is run automatically (with wizard / command line option to stop it executing).

Note: installing algokit itself means that Python is available so no need to check for that.

Note also: The Sandbox commands automatically check for Docker installation and provide error messages with instructions to guide installation.

Original description:

AlgoKit CLI allows developers to bootstrap their local environment for Algorand development on Windows, Mac and Linux, including:

• Verifying Docker is installed
• Installation of Python, Node.js (if needed) and any required dependency management tooling

Investigate Linux distribution options outside of pip

such as https://snapcraft.io/ or alternatives

Also see https://azurecliprod.blob.core.windows.net/install.py for inspiration

Create AlgoKit CLI base

Acceptance Criteria:

• There is a Python CLI that you can execute
• When invoking AlgoKit CLI with a version of CPython less than 3.10 then it will show an error and link off to Python installation documentation:

  > algokit
  AlgoKit CLI
  
  Unsupported CPython version (3.9.2) detected. The minimum version of Python supported is CPython 3.10.
  
   If you need help installing then this is a good starting point: https://www.python.org/about/gettingstarted/.
  

• When invoking AlgoKit CLI with no arguments you see general usage:

  > algokit
  Welcome to AlgoKit CLI!
  
  AlgoKit is your one stop shop to develop applications on the Algorand blockchain.
  
  Usage:
    algokit -h|--help
    algokit -v|--version
    algokit [options] [COMMAND] [ARGS...]
  
  Available commands:
     TODO
  

• When invoking AlgoKit CLI with version or --version it will output the current version:

  > algokit --version
  AlgoKit CLI v0.1.0
  

• When invoking AlgoKit CLI with an unknown command it will output an error and show usage information:

  > algokit unknown
  AlgoKit CLI
  
  Unknown command `unknown`; please see usage information below:
  
  Usage:
    algokit -h|--help
    algokit --version
    algokit [options] [COMMAND] [ARGS...]
  
  Available commands:
     TODO
  

Rapidly run cross-platform sandbox (algokit sandbox start)

Acceptance Criteria:

• If you run algokit sandbox start:
  • If you don't have docker or docker-compose installed it should present an error directing you to the Docker / Docker Compose installation instructions
  • If Docker is installed, but the engine is not running it should present an error directing the user to start the docker engine
  • If there is no previous sandbox that exists it will create a new set of sandbox Docker containers running on the standard ports:
    • algod - 4001, 4002 (KMD), 9392 (tealdbg)
    • indexer - 8980
    • postgres - no port exposed
  • If the containers are previously created, but one or more are stopped then start the ones that are stopped
  • If the containers are all created and started do nothing
• The sandbox blockchain state should be persistent across restarts
• Documentation exists documenting: treating sandbox as ephemeral and the Falcon key exhaustion issue

Create GitHub repos and grant access

AlgoKit CLI installation documentation

Acceptance Criteria:

• Install Algokit instructions:
  • Windows
    • Pre-requisites (git, docker)
    • choco install algokit check via algokit --version
    • Install via pipx (link to tab)
    • Update via choco upgrade algokit
    • Uninstall via choco uninstall algokit
  • Mac
    • Pre-requisites (git, docker)
    • brew install algorandfoundation/core/algokit check via algokit --version
    • Install via pipx (link to tab)
    • Update via brew upgrade algokit
    • Uninstall via brew uninstall algokit
  • Linux
    • Pre-requisites (git, docker)
    • Install via pipx (link to tab)
  • Pipx
    • Pre-requisites (git, docker)
    • Install Python + Install pipx + ensure path + pipx install algokit check via algokit --version
    • Update via pipx upgrade algokit
    • Uninstall via pipx uninstall algokit
• After installation suggest algokit doctor
  • Some of the tools can get automatically installed by Algokit as you need them like poetry and node.js, but it will tell you.

Agree on Beaker test strategy

We need to decide how we want to test the Beaker codebase.

Concepts to consider:

• "output stability"
• Auditability
• Evolvability
• Speed to test coverage

Logging

Acceptance Criteria:

• The CLI tool should have logging integrated.
• The log level should determine the output colour:
  • Error / Critical = Red
  • Warning = Yellow
  • Info = White
  • Debug / Trace = Blue
• There should be a -v global option to output debug+ logging, but otherwise only info+ logging

AlgoKit Smart Contract Building Blocks library

Acceptance Criteria:

• There will be a GitHub repository that publishes a PyPi package (with automated CI/CD, release notes and versioning)
• There will be a structure where different arcs can be contributed as a Beaker base class, the audit report, any (Markdown) documentation
• The initial set of smart contracts will be determined in the future
• There will be a CONTRIBUTING.md that outlines that all implementations will be audited and will implement a finalised ARC standard, for now it will note that contributions will be from Algorand Foundation only, but if someone wants to email [email protected].
• Community templates can be managed separately (potentially cloning this repository)

Original notes:

A library for Algorand exists with audited, documented smart contracts and base smart contract templates in PyTEAL that allows Algorand Foundation contributed smart contracts (e.g. ARC reference implementations) and community contributed smart contracts

Inspiration:

• https://github.com/transmissions11/solmate
• https://www.openzeppelin.com/

algokit sandbox status

Acceptance Criteria:

• If the user invokes algokit sandbox status:

  • If the sandbox containers are not present or are stopped then output a message indicating that the sandbox is not running and they should run algokit sandbox start, a non-zero exit code should be returned:

    # algod status
    Status: Not running
    # indexer status
    Status: Error

    Run algokit sandbox start to start the sandbox.

  • If the containers are present and started then:

    • Check the status of algod and show:

      # algod status
      Status: Running
      Port: 4001
      Last round: 0
      Time since last round: 0.0s
      Genesis ID: sandnet-v1
      Genesis hash: 1dpDw4wZL+8OI6IUy7S6LyUqcXQ2busuRZIQRsZjsbE=
      Version: x.y.z

    • Check the status of indexer and show:

      # indexer status
      Status: Running
      Port: 8980
      Last round: 0
      Error(s): {any errors}
      Version: x.y.z

    • Return a non-zero exit code if either algod or indexer are not running and a zero exit code if they are both running OK

PR for copier package to remove dependency on Microsoft Build Tools (via iteration_utilities)

Windows without microsoft c++ build tools gives this error

(algokit-py3.10) PS D:\repositories\MakerX\algokit-cli> poetry install
Installing dependencies from lock file
Warning: poetry.lock is not consistent with pyproject.toml. You may be getting improper dependencies. Run `poetry lock [--no-update]` to fix it.

Package operations: 2 installs, 0 updates, 0 removals

  • Installing iteration-utilities (0.11.0)

  CalledProcessError

  Command 'D:\repositories\MakerX\algokit-cli\.venv\Scripts\python.exe -m pip install --use-pep517 --disable-pip-version-check --prefix D:\repositories\MakerX\algokit-cli\.venv --no-deps C:\Users\wilson\AppData\Local\pypoetry\Cache\artifacts\13\fe\58\dd3a5413393eab8ca2c5b884ff40af30da952dbdc4598df1d7b6cf61b0\iteration_utilities-0.11.0.tar.gz' returned non-zero exit status 1.

  at ~\AppData\Local\Programs\Python\Python310\lib\subprocess.py:524 in run
       520│             # We don't call process.wait() as .__exit__ does that for us.
       521│             raise
       522│         retcode = process.poll()
       523│         if check and retcode:
    →  524│             raise CalledProcessError(retcode, process.args,
       525│                                      output=stdout, stderr=stderr)
       526│     return CompletedProcess(process.args, retcode, stdout, stderr)
       527│
       528│

The following error occurred when trying to handle this error:


  EnvCommandError

  Command D:\repositories\MakerX\algokit-cli\.venv\Scripts\python.exe -m pip install --use-pep517 --disable-pip-version-check --prefix D:\repositories\MakerX\algokit-cli\.venv --no-deps C:\Users\wilson\AppData\Local\pypoetry\Cache\artifacts\13\fe\58\dd3a5413393eab8ca2c5b884ff40af30da952dbdc4598df1d7b6cf61b0\iteration_utilities-0.11.0.tar.gz errored with the following return code 1, and output:
  Processing c:\users\wilson\appdata\local\pypoetry\cache\artifacts\13\fe\58\dd3a5413393eab8ca2c5b884ff40af30da952dbdc4598df1d7b6cf61b0\iteration_utilities-0.11.0.tar.gz
    Installing build dependencies: started
    Installing build dependencies: finished with status 'done'
    Getting requirements to build wheel: started
    Getting requirements to build wheel: finished with status 'done'
    Preparing metadata (pyproject.toml): started
    Preparing metadata (pyproject.toml): finished with status 'done'
  Building wheels for collected packages: iteration-utilities
    Building wheel for iteration-utilities (pyproject.toml): started
    Building wheel for iteration-utilities (pyproject.toml): finished with status 'error'
    error: subprocess-exited-with-error

    Building wheel for iteration-utilities (pyproject.toml) did not run successfully.
    exit code: 1

    [15 lines of output]
    running bdist_wheel
    running build
    running build_py
    creating build
    creating build\lib.win-amd64-cpython-310
    creating build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\_additional_recipes.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\_classes.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\_convenience.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\_recipes.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\_utils.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    copying src\iteration_utilities\__init__.py -> build\lib.win-amd64-cpython-310\iteration_utilities
    running build_ext
    building 'iteration_utilities._iteration_utilities' extension
    error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
    [end of output]

    note: This error originates from a subprocess, and is likely not a problem with pip.
    ERROR: Failed building wheel for iteration-utilities
  Failed to build iteration-utilities
  ERROR: Could not build wheels for iteration-utilities, which is required to install pyproject.toml-based projects


  at ~\AppData\Local\Programs\Python\Python310\lib\site-packages\poetry\utils\env.py:1476 in _run
      1472│                 output = subprocess.check_output(
      1473│                     command, stderr=subprocess.STDOUT, env=env, **kwargs
      1474│                 )
      1475│         except CalledProcessError as e:
    → 1476│             raise EnvCommandError(e, input=input_)
      1477│
      1478│         return decode(output)
      1479│
      1480│     def execute(self, bin: str, *args: str, **kwargs: Any) -> int:

The following error occurred when trying to handle this error:


  PoetryException

  Failed to install C:/Users/wilson/AppData/Local/pypoetry/Cache/artifacts/13/fe/58/dd3a5413393eab8ca2c5b884ff40af30da952dbdc4598df1d7b6cf61b0/iteration_utilities-0.11.0.tar.gz

  at ~\AppData\Local\Programs\Python\Python310\lib\site-packages\poetry\utils\pip.py:51 in pip_install
       47│
       48│     try:
       49│         return environment.run_pip(*args)
       50│     except EnvCommandError as e:
    →  51│         raise PoetryException(f"Failed to install {path.as_posix()}") from e
       52│

Automated update prompt

Acceptance Criteria:

• Pre-release packages get marked in GitHub as a pre-release package so that the "latest" algokit cli release in GitHub is always the latest production release
• algokit doctor command shows the latest algokit version with it in yellow warning if it's more than the current version
• If an algokit command is executed, and it's been at least 24 hours (a bit too invasive) 1 week since a version check was last performed then algokit will check for the latest published release version and store it in the state config
  • https://api.github.com/repos/algorandfoundation/algokit-cli/releases/latest should contain the latest release version (when the repo is public).
• If an algokit command is executed and the current known latest release version is greater than the current version then a warning is displayed to user to let them know that and encourage them to update their algokit (linking to the relevant documentation)
• Any algokit command should be able to be executed with --skip-version-check which will prevent both the version check and the warning from occurring
• If the user executes algokit --disable-version-check then algokit will store a config in it's config directory that results in the equivalent of passing --skip-version-check for every command
• If the user executes algokit --enable-version-check then it will reverse any previous execution of algokit --disable-version-check

algokit init - .env configuration

Acceptance criteria:

• At init the cli should create a template environment variables files that contains all sensitive information such as:
  • Node details
  • Optional mnemonics
• The env file should be included in the .gitignore file by default
• Developers should be able to reference variables present in the file freely across the repo

algokit sandbox stop

Acceptance Criteria:

• When running algokit sandbox stop:
  • Any existing algokit sandbox docker images (algod, indexer and postgres) will stopped and existing network and volumes will be kept intact
• If the user invokes algokit sandbox start after running algokit sandbox stop then the existing container state should be in place

algokit doctor

Acceptance Criteria:

• The installation instructions for algokit cli should suggest that users run algokit doctor after installation to check their system is ready
• The GitHub issue template in algokit cli should indicate that users should run algokit doctor and paste the result before submitting the issue -- << needs GitHub issue template - do we have access>>
• When the user executes algokit doctor it should show:
  • Time: {time}
  • AlgoKit: {version} {path}
  • {% if Windows and choco exists and installed via chocolatey%}Chocolatey installed version: {version}{% endif %}
  • {% if Mac and brew exists and installed via brew%}Brew installed version: {version}{% endif %}
  • OS: {type} {version}
  • Docker: {version of docker} | None found
    • If None found: Docker required to run algokit sandbox command; install via https://docs.docker.com/get-docker/
  • Docker compose: {version of docker compose} | None found
    • If None found or version < 2.5: Docker Compose 2.5 required to run algokit sandbox command; install via https://docs.docker.com/compose/install/
  • Git: {version} | None found
    • If None found:
      • Windows: Git required to run algokit init; install via choco install git if using Chocolatey or via https://github.com/git-guides/install-git#install-git-on-windows
      • Otherwise: Git required to run algokit init; install via https://github.com/git-guides/install-git#install-git-on-windows
  • AlgoKit Python: {version of algokit version} {path} (base path: {base path})
  • Global Python: {version of first global path python3 version} {path} | None found
  • Pipx: {version of global pipx} | None found
    • If no poetry and no pipx then: Pipx is required to install Poetry; install via https://pypa.github.io/pipx/
  • Poetry: {version of global poetry} | None found
    • Poetry is required for some Python-based templates; install via algokit bootstrap within project directory, or via https://python-poetry.org/docs/#installation
  • Node.js: {version of global node} | None found
    • Node.js is required for some Node.js-based templates; install via algokit bootstrap within project directory, or via https://nodejs.dev/en/learn/how-to-install-nodejs/
  • Npm: {version of global npm} | None found
  • If you are experiencing a problem with algokit, feel free to submit an issue via https://github.com/algorandfoundation/algokit-cli/issues/new; please include this output, if you want to populate this message in your clipboard, run algokit doctor -c
• [Stretch goal] There is a -c/--copy-to-clipboard option that places the contents of the doctor message (in Markdown format) in the users clipboard
• Anything that is critical (docker, git) should be red if not found, otherwise yellow
• Return a zero exit code if all critical components are installed with minimum version met, # of critical components missing otherwise

algokit sandbox explore

Acceptance Criteria:

• An algokit sandbox explore command should open an instance of dappflow pointed directly at your local sandbox.
  • The endpoint that the dappflow provided is per the following example:
    https://app.dappflow.org/setup-config?algod_url=https://testnet-api.algonode.cloud&indexer_url=https://testnet-idx.algonode.cloud&redirect=/explorer/transaction/ZDQV5D6L35NG4DRBRKH6SNKAMCQZGWKCQBYJX5L5FTFLHL7EFJ6A
  • And relevant commit on repo can be found here
• An algokit explore command should do the same as algokit sandbox explore
• There should also be:
  • algokit explore sandbox (same as above)
  • algokit explore mainnet - opens mainnet using Algonode (algonode.cloud) endpoints
  • algokit explore testnet - opens testnet using Algonode (algonode.cloud) endpoints

Error executing algokit after following steps in installation guide

Environment

Edition Windows 11 Pro
Version 22H2
Installed on ‎27/‎11/‎2022
OS build 22621.1105
Experience Windows Feature Experience Pack 1000.22638.1000.0

Command line: PowerShell

This is a machine that has not been used for development until this very moment.

Steps to reproduce

Followed Windows installation guide in README verbatim.

Expected result

Commands listed in installation guide run without errors and need for troubleshooting.

Actual result

Blocker

After performing all the steps in the installation guide without errors, trying to verify the installation via algokit --version results in the following output:

Unhandled ImportError: cannot import name 'git' from 'plumbum.cmd' (C:\Users\Home\.local\pipx\venvs\algokit\Lib\site-packages\plumbum\cmd.py)

Major

• Every choco install command had to be run with the additional -y argument, otherwise PowerShell just got stuck and would not react to my input at all
• Without manually adding pip to path, the command pip install --user pipx did not work. Had to run py -m pip install --user pipx instead.
• Without manually adding python to path, the commands python -m pipx ensurepath and python -m pipx install algokit did not work. Had to use py instead of python to invoke the Python Windows Launcher, which doesn't require path modification.

P.S. I'm not a Python dev, though I use it for utility scripts from time to time and have some exposure to the ecosystem and package management. I also do all of my development in the last 5 years on a Mac. Just throwing it out there, in case I missed something stupidly obvious here.

Create community contribution standard across AlgoKit repos

We need to decide on a community contribution standard for AlgoKit.

Related: https://allcontributors.org/docs/en/overview

Inspiration:

• https://github.com/algorand/go-algorand/blob/master/CONTRIBUTING.md
• https://github.com/algorand-devrel/beaker/blob/master/CONTRIBUTING.MD

algokit sandbox console

Acceptance Criteria:

• When the user executes algokit sandbox console it will open a bash terminal on the algod node of the currently running AlgoKit Sandbox
  • Before showing the console, it will a message indicating that they will be inside a Bash terminal, can run goal commands, and need to execute an exit command to get back to their original terminal
• If Sandbox isn't running it will an error message to that effect

algokit sandbox reset

Acceptance Criteria:

• When running algokit sandbox reset:
  • Any existing algokit sandbox docker images (algod, indexer and postgres) will stopped and then removed
  • Any existing algokit sandbox network will be deleted
  • Any existing algokit volumes will be deleted
  • The latest algokit sandbox images will be pulled
  • If there is a new Docker configuration apply that
  • Invoke algod sandbox start
• If there is a change to the Docker configuration e.g. after updating algokit, then it should automatically detect that when running algokit sandbox start and output a warning to indicate that the person should run algokit sandbox reset

AlgoKit CLI CI/CD

Options:

• GitHub flow (pull request -> main) and we can optionally release a build to PyPi (by clicking a button in GitHub actions); vs
• Git Flow (pull request -> develop -> main) and a merge to main automatically

GitHub flow is simpler, Git flow allows for longer-running experimental branches.

We decided to use GitHub flow for simplicity and to encourage regular releasing. If there is a need for an experimental branch then it can be released by running the GitHub action against the branch and thus published as a pre-release.

Acceptance Criteria:

• When a pull request is opened to AlgoKit CLI a GitHub action is run that checks: the code typings are valid, formatting is valid according to the Python Black configuration, any tests (present) pass
• When there's a new commit on the main branch of the AlgoKit CLI a GitHub workflow is run that:
  1. Checks the code typings are valid
  2. Checks the formatting is valid according to the Python Black configuration
  3. Checks the linting is valid according to the TBD configuration
  4. Checks all tests pass
  5. Builds a PyPi Wheel package ready for publishing
  6. Releases a pre-release package to PyPi
• If the branch is not main then the branch name will be used as a pre-release tag, but otherwise it will be beta
• There is an ability for a product manager to trigger a "stable" release, which will deploy a new non-pre-release package to PyPi
  (NOTE: These last criteria are being completed in #16)

Fix indexer restart issue

Note: This is a known issue in Sandbox / Indexer - algorand/sandbox#163. Waiting for confirmation of a likely resolution delay before looking to fix it in AlgoKit.

In the meantime we have placed a note in known issues in the documentation for AlgoKit Sandbox.

Decide on AlgoKit documentation strategy

Need to decide how we want to host / write / publish documentation for AlgoKit.

Broad options:

• Host within https://developer.algorand.org/
• Host in a separate AlgoKit website and link from https://developer.algorand.org/
• Some hybrid

Add mypy support

In an attempt to reduce the chance of bugs, the story requests adding mypy support:

• mypy runs during CI.
• Instructions or local build target exist for running mypy locally.
• In order to provide library importers with type information, release process produces a PEP 561 compatible package (https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages).

In case helpful as a reference point, https://github.com/algorand/pyteal/ supports mypy.

Set up MacOS Brew installation

Acceptance Criteria:

• Mac users can brew install algorandfoundation/core/algokit and get the latest production version of algokit installed to their machine
• If users don't have Python 3.10+ installed then it will be installed for them
• If users don't have pipx installed it will install that for them with pipx available on global path
• New releases are automatically released when a production release of algokit is issued

algokit init - git init

Acceptance Criteria:

• If you execute algokit init it will prompt you for a project name, or you can pass the name in using --name {name} or algokit init {name}
• When you execute the init command it will create a folder as a subfolder of the current directory with the name {name}
• In that folder it will initialise a new, empty Git repository

Adding an account through the goal proxy cmd fails

ben@Algo-Guidarelli:~/wiggly$ algokit goal account import
 Couldn't read response: EOF
 Please type your recovery mnemonic below, and hit return when you are done:
Error: Error executing goal; ensure the Sandbox is started by executing `algokit sandbox status

A user could still run algokit sandbox console and goal account import separately to add a new account

Beaker automated CI/CD

algorand-devrel/beaker#161

Check for minimum Docker Compose version

This helps ensure a stable base of Docker Compose functionality to ensure a good experience. Trying to balance likelihood the dev needs to update (friction) with stability of Docker Compose (bad UX). We determined that 2.5.0 is a good base to have as a minimum, which will be ~ 9 months old when we have public beta.

Acceptance Criteria:

• If the version of Docker Compose is < 2.5.0 and an algokit sandbox * command is executed then present an error to the user and provide them a link to give update instructions.

Investigate feature release version issue

There are some problems that have been identified in the release versioning implementation:

1. Error marking release branch releases as prerelease in Github e.g. this error

   • Cause: not finding the release to run gh release edit --prerelease "v$(poetry run semantic-release print-version --current)". The reason is the poetry run semantic-release print-version --current command returns (e.g.) 1.2.3 without the beta tag attached to it (expected: 1.2.3-beta.1)
   • This has been solved by looking for the last git tag instead of the branch name i.e. gh release edit --prerelease "$(git describe $(git rev-list --tags --max-count=1))"

2. Feature branches keep bumping the minor version and main versions were being bumped by it too, causing unexpectedly escalating version numbers. There are two suspected bugs in python-semantic-release causing this:
   a. Prerelease tag that isn't beta i.e. beta-branch has this weird behaviour of trying to bump the version every time
   b. When calculating a version from tags it's not grabbing tags in the current branch, but every tag in the whole repository thus leaking versions between branches

In order to fix 2, we have a workaround to limit the impact (already low since feature branches are an exception rather than a usual mode of operation) by specifying --patch on prerelease builds so at least it only bumps patch and not minor. In the meantime we will raise issues with the source repository and try and get the underlying bugs resolved.

Investigate AlgoKit tab completion

Nice-to-have, but worthwhile if we can invest a day and get it done. First step is a timeboxed investigation to see how easy/hard it will be to add. In an ideal world, we would be able to utilise click + pipx to get tab completion support in bash, zsh and powershell.

Set up pip/pipx installation

Acceptance Criteria:

• You can install AlgoKit CLI if you have access to the source repo via:

  > pipx install <source_repo_url>
  

• Once the installation completes, you should be able to run algokit, e.g.:

  > algokit -v
  AlgoKit CLI v0.1.0
  

• Installation works from Windows, Mac and Linux

algokit init - Wizard + Template base

Acceptance Criteria:

• Template = repository
• Allowlist of known, reviewed templates with: repository url, optional commit SHA
• Wizard options are able to be passed in via cmdline, but if any required options aren't then it will prompt you and receive via stdin
• You can skip the allowlist and pass in a repository url via --template-url, but it will warn you of the security risk and confirm via stdin that you are sure you want to do it
• algokit init
  • Name of project (--name, -n)
    • The template is initialised in a sub-folder of this name
    • Validation: /^[\w-.]+$/ and the directory doesn't exist already
  • Template (default: beaker-default) (--template, -t)
    • Validation: ID from allowlist
    • Have a link to the documentation for the templates
    • Nice to have: Scrolling list like create-remix template selection
  • Deployment language: TypeScript | Python (will be added in later story, --deployment-lang, -l, default: Python)
  • Install dependencies: y/n
    • If Y/y then install the Python dependencies
• Once the template is there output the commands to open the folder and open their IDE and a URL to the next steps documentation

Bootstrap and init documentation

Acceptance Criteria:

• Auto-generated API documentation (in Markdown) for all CLI commands
• How to create a template (re: algokit init) documentation

Notes:

• The Algorand dev rels will create a lot of the conversation / tutorial based documentation

Unexpected error checking dependency - docker-compose

Docker compose is correctly installed on my Mac

❯ docker-compose --version
docker-compose version 1.29.2, build 5becea4c

And running algokit doctor I get:

• timestamp: 2023-01-27T15:43:00+00:00
• AlgoKit: 0.2.0
• AlgoKit Python: 3.11.1 (main, Dec 23 2022, 09:25:23) [Clang 14.0.0 (clang-1400.0.29.202)] (location: /Users/samurai/.local/pipx/venvs/algokit)
• OS: macOS-12.5.1-arm64-arm-64bit
• docker: 20.10.11
• docker compose: Unexpected error checking dependency
  json.decoder.JSONDecodeError: Extra data: line 1 column 21 (char 20)
• git: 2.37.1
• python: 3.10.7 (location: /Users/samurai/.asdf/shims/python)
• python3: 3.10.7 (location: /Users/samurai/.asdf/shims/python3)
• pipx: 1.1.0
• poetry: Command not found!
  Poetry is required for some Python-based templates;
  install via algokit bootstrap within project directory, or via:
  https://python-poetry.org/docs/#installation
• node: 16.15.0
• npm: 8.5.5
• brew: 3.6.20

When running for example:

algokit sandbox start                                                                                                                                      
Unhandled JSONDecodeError: Extra data: line 1 column 21 (char 20)

Get this DecodeError. I assume its related with the docker-compose.

Releasing AlgoKit

Acceptance Criteria:

• When releasing AlgoKit it should create an associated GitHub release with release notes linking to GitHub issues / pull requests
• The version number should follow semantic versioning
• Creating a release should be an easy process driven by automation where possible
• There should be a CHANGELOG.md file which includes any breaking changes and is linked to from main README.md
• Creates package on PyPi (originally part of #17 )
  • On push to main, releases a (beta) pre-release package to PyPi
  • If the branch is not main then the branch name will be used as part of the pre-release tag
  • There is an ability for a product manager to trigger a production release, which will deploy a new non-pre-release package to PyPi and release notes to CHANGELOG.md

Error compiling "init" sample smart contracts

Hello all; please let me know if this is something I should take up with Beaker.

Command run

python -m smart_contracts

Error output

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/[~~REDACTED~~]/newtoast/smart_contracts/__main__.py", line 3, in <module>
    from smart_contracts.lab import my_lab
  File "/[~~REDACTED~~]/newtoast/smart_contracts/lab.py", line 29, in <module>
    apps=[HelloWorld()],
          ^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/beaker/application.py", line 241, in __init__
    self.compile()
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/beaker/application.py", line 280, in compile
    ) = self.router.compile_program(
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/ast/router.py", line 746, in compile_program
    ap_compiled = compileTeal(
                  ^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/compiler/compiler.py", line 279, in compileTeal
    compileSubroutine(
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/compiler/compiler.py", line 152, in compileSubroutine
    start, end = ast.__teal__(options)
                 ^^^^^^^^^^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/ast/cond.py", line 82, in __teal__
    condStart, condEnd = cond.__teal__(options)
                         ^^^^^^^^^^^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/ast/binaryexpr.py", line 39, in __teal__
    self.op.min_version,
    ^^^^^^^^^^^^^^^^^^^
  File "/[~~REDACTED~~]/newtoast/.venv/lib/python3.11/site-packages/pyteal/ir/ops.py", line 31, in min_version
    return self.value.min_version
           ^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'tuple' object has no attribute 'min_version'

Background

• I successfully installed the kit, and used the init command to generate a sample project.
• I ran the above command python -m smart_contracts in the project's root directory
• No modifications were made to the original init files.

Additional Notes

• I could not find a reference to a min_version in the Beaker Application class
• I may be doing something obviously wrong, but haven't found documentation (in Beaker, PyTeal, or the Algorand forum) that indicates this.
• Please add documentation that you are using Beaker. As a new user, it took me too long (and much frustration) to eventually discover that PyTeal and Beaker are different things.

AlgoKit local dev experience

Acceptance criteria:

• There should be clear instructions for how to get started developing/debugging AlgoKit CLI
• AlgoKit CLI can be developed cross-platform (Windows, Mac, Linux)
• There are automated scripts that can set up the key dependencies (python, poetry) for you if you want
• There should be IDE configuration in VS Code and IDEA that allows you to open the project and quickly start debugging with breakpoint debugging
• The linting, typing and formatting integration should be set up with the IDE so it just works
• There should be a way to quickly debug against an arbitrary command in a supported IDE

Agree on Sandbox approach

We need to decide on what Sandbox approach we will take for AlgoKit.

Key principles:

• Fast to start for local development and CI/CD
• Works cross-platform including on Windows

Initial options:

• https://github.com/MakerXStudio/algorand-sandbox-dev
• Lightweight sandbox client

Architecture decision for smart contract deployment

Initial conversation with Fabrice:
testnet - .env (unencrypted is fine as long as it's in .gitignore) or ci/cd or kmd
mainnet - default: deploy and immediately rekey, don't allow upgradeable by default, require an override if doing something insecure in mainnet, by default don't allow mainnet deployment via ci/cd or locally (maybe present txn for signing?), allow ci/cd with once-only deployment by default?

algokit goal

Acceptance Criteria:

• Executing algokit goal {args} will run goal {args} on the algod Sandbox container
• If the Sandbox is not running then indicate that the user should start it first with algokit sandbox start

Document AlgoKit principles

Acceptance Criteria:

• The principles behind AlgoKit are shown in the README of the main AlgoKit GitHub repository

Use native binaries rather than docker

This has been discussed on a couple of times, but I want to raise the topic again because I think there's an approach we can take that dramatically reduces the friction for the "first-touch" dev experience.

The main rationale for using docker is because of the postgres DB indexer needs. Having users install Postgres on bare-metal is unreasonable. The indexer, however, is not needed for smart contract development (only full Dapp development). As such, I think it would be reasonable for the default installation of sandnet to not include indexer. Without needing indexer we can then use native binaries.

The main sticking point with trying to use native binaries is not having Windows binaries. To alleviate this, we could have the Windows version of algokit use WSL when ran on Windows. The requirement for WSL is still not ideal, but it's better than WSL + Docker.

If a dev wants to eventually use Indexer, there can be an optional flag that creates a docker container on the host network that can communicate with the local algod. Eventually we can hopefully write a Conduit plugin that uses SQLite instead of Postgres and have everything native.

Beaker productionisation review

Capture template data when init'ing templates

Long term we want to support upgradeable / multiple templates. To support that we need to capture templates used and answers given. To avoid a future breaking change for AlgoKit users we should start capturing that information now.

Acceptance Criteria:

• Ensure that multiple templates can be executed in the same project in the future by putting the copier answers file in .algokit/.copier-answers.{templatename}.yml
• Add ability to upgrade template to latest version and check it works with beaker template

Gitpod installation - Doctor version parsing for docker compose

Running algokit doctor in a Gitpod where algokit has been installed (thanks @joe-p) throws the following error on docker combine version parsing:

Gitpod link:
https://gitpod.io/#https://github.com/algorand-devrel/docker-algorand-gitpod/tree/algokit/

Terminal input & output:

gitpod /workspace/docker-algorand-gitpod (algokit) $ algokit doctor
timestamp: 2023-01-28T14:14:35+00:00
AlgoKit: 0.2.0
AlgoKit Python: 3.10.7 (main, Jan 28 2023, 13:07:35) [GCC 9.4.0] (location: /home/gitpod/.local/pipx/venvs/algokit)
OS: Linux-5.15.0-47-generic-x86_64-with-glibc2.31
docker: 20.10.17
docker compose: 2.10.0-gitpod.0
  Failed to parse version from: "2.10.0-gitpod.0"
  Error: invalid literal for int() with base 10: '0-gitpod'
  Unable to check against minimum version of 2.5.0
git: 2.37.3
python: 3.10.7 (location: /home/gitpod/.pyenv/shims/python)
python3: 3.10.7 (location: /home/gitpod/.pyenv/shims/python3)
pipx: 1.1.0
poetry: 1.3.1
node: 16.19.0
npm: 8.19.3

algokit init doesn't use active python version with poetry + pyenv

If installing algokit on a system with pyenv, poetry will not detect the current active version of Python by default. This means the installation of the dependencies might occur on the incorrect version of Python.

To fix this, part of the init process could ask if pyenv should be configured with poetry config virtualenvs.prefer-active-python true to automatically detect the active version of Python

Set up Windows Chocolatey installation

Acceptance Criteria:

• Windows users can choco install algokit and get the latest production version of algokit installed to their machine
• If users don't have Python 3.10+ installed then it will be installed for them
• If users don't have pipx installed it will install that for them with pipx available on global path
• New releases are automatically released when a production release of algokit is issued
• Windows users can choco upgrade algokit to upgrade to latest available version
• Windows users can choco uninstall algokit to remove algokit cli from their system

algokit init - Python and VS Code configuration

Acceptance Criteria:

• When a new Python project (e.g. via default beaker template) is initialised a python project / venv will automatically be set up with:
  • Formatting using Black
  • Linting using Ruff
  • Type checking using mypy
  • Testing using pytest
  • Dependency and venv installation using Poetry
• If the user executes init with --no-venv then a virtual environment will not be created and the global version of python will be used We will only support poetry for now
• If the user executes init with --pip then requirements.txt will be used instead of Poetry
  • If there is no --no-venv or there is --venv then it will use virtualenv to set up the virtual environment
• If the user executes init with --no-formatting -a use_python_black no then the formatter won't be configured
• If the user executes init with --no-linting -a use_python_linter null then the linter won't be configured
• If the user executes init with --no-typing -a use_python_mypy no then the typing won't be configured
• When a new project is initialised opening it in VS Code will automatically set up:
  • Formatting (including format on save) using Black
  • Linting (including format on save) using Ruff
  • Type checking using mypy / Pylance (non-strict mode)
  • Breakpoint debugging of PyTEAL/Beaker execution on F5
  • Pytest runner integrated into VS Code test runner, including breakpoint debugging
  • Tasks to perform key tasks like starting the AlgoKit Sandbox
  • Extension recommendations for: Python, TOML, Algorand extensions