feat: algokit dispenser

.github/workflows/check-python.yaml

@@ -27,11 +27,11 @@ jobs:
           # audit non dev dependencies, no exclusions
           poetry export --without=dev > requirements.txt && poetry run pip-audit -r requirements.txt
 
-          # audit all dependencies, with exclusions. 
+          # audit all dependencies, with exclusions.
           # If a vulnerability is found in a dev dependency without an available fix,
           # it can be temporarily ignored by adding --ignore-vuln e.g.
           # --ignore-vuln "GHSA-hcpj-qp55-gfph" # GitPython vulnerability, dev only dependency
-          poetry run pip-audit
+          poetry run pip-audit --ignore-vuln "GHSA-wfm5-v35h-vwf4" --ignore-vuln "GHSA-cwvm-v4w8-q58c"
 
       - name: Check formatting with Black
         run: |

.gitignore

@@ -173,3 +173,6 @@ cython_debug/
 #Sphinx
 .doctrees/
 docs/cli/temp.md
+
+# Miscellaneous
+ci_token.txt

docs/cli/index.md

@@ -36,26 +36,44 @@
     - [-P, --path ](#-p---path-)
     - [Arguments](#arguments-1)
     - [ENVIRONMENT_NAME](#environment_name)
-  - [doctor](#doctor)
+  - [dispenser](#dispenser)
+    - [fund](#fund)
     - [Options](#options-7)
+    - [-r, --receiver ](#-r---receiver-)
+    - [-a, --amount ](#-a---amount-)
+    - [--whole-units](#--whole-units)
+    - [limit](#limit)
+    - [Options](#options-8)
+    - [--whole-units](#--whole-units-1)
+    - [login](#login)
+    - [Options](#options-9)
+    - [--ci](#--ci)
+    - [-o, --output ](#-o---output-)
+    - [-f, --file ](#-f---file-)
+    - [logout](#logout)
+    - [refund](#refund)
+    - [Options](#options-10)
+    - [-t, --txID ](#-t---txid-)
+  - [doctor](#doctor)
+    - [Options](#options-11)
     - [-c, --copy-to-clipboard](#-c---copy-to-clipboard)
   - [explore](#explore)
     - [Arguments](#arguments-2)
     - [NETWORK](#network)
   - [generate](#generate)
     - [client](#client)
-    - [Options](#options-8)
-    - [-o, --output ](#-o---output-)
+    - [Options](#options-12)
+    - [-o, --output ](#-o---output--1)
     - [-l, --language ](#-l---language-)
     - [Arguments](#arguments-3)
     - [APP_SPEC_PATH_OR_DIR](#app_spec_path_or_dir)
   - [goal](#goal)
-    - [Options](#options-9)
+    - [Options](#options-13)
     - [--console](#--console)
     - [Arguments](#arguments-4)
     - [GOAL_ARGS](#goal_args)
   - [init](#init)
-    - [Options](#options-10)
+    - [Options](#options-14)
     - [-n, --name ](#-n---name-)
     - [-t, --template ](#-t---template-)
     - [--template-url ](#--template-url-)
@@ -70,11 +88,11 @@
     - [console](#console)
     - [explore](#explore-1)
     - [logs](#logs)
-    - [Options](#options-11)
+    - [Options](#options-15)
     - [--follow, -f](#--follow--f)
     - [--tail ](#--tail-)
     - [reset](#reset)
-    - [Options](#options-12)
+    - [Options](#options-16)
     - [--update, --no-update](#--update---no-update)
     - [start](#start)
     - [status](#status)
@@ -178,7 +196,7 @@ algokit completions [OPTIONS] COMMAND [ARGS]...
 ### install
 
 Install shell completions, this command will attempt to update the interactive profile script
-for the current shell to support algokit completions. To specify a specific shell use –shell.
+for the current shell to support algokit completions. To specify a specific shell use --shell.
 
 ```shell
 algokit completions install [OPTIONS]
@@ -200,7 +218,7 @@ Specify shell to install algokit completions for.
 
 Uninstall shell completions, this command will attempt to update the interactive profile script
 for the current shell to remove any algokit completions that have been added.
-To specify a specific shell use –shell.
+To specify a specific shell use --shell.
 
 ```shell
 algokit completions uninstall [OPTIONS]
@@ -232,7 +250,7 @@ Controls whether AlgoKit checks and prompts for new versions.
 Set to [disable] to prevent AlgoKit performing this check permanently, or [enable] to resume checking.
 If no argument is provided then outputs current setting.
 
-Also see –skip-version-check which can be used to disable check for a single command.
+Also see --skip-version-check which can be used to disable check for a single command.
 
 ```shell
 algokit config version-prompt [OPTIONS] [[enable|disable]]
@@ -272,9 +290,103 @@ Specify the project directory. If not provided, current working directory will b
 ### ENVIRONMENT_NAME
 Optional argument
 
+## dispenser
+
+Interact with the AlgoKit TestNet Dispenser.
+
+```shell
+algokit dispenser [OPTIONS] COMMAND [ARGS]...
+```
+
+### fund
+
+Fund your wallet address with TestNet ALGOs.
+
+```shell
+algokit dispenser fund [OPTIONS]
+```
+
+### Options
+
+
+### -r, --receiver <receiver>
+**Required** Receiver address to fund with TestNet ALGOs.
+
+
+### -a, --amount <amount>
+**Required** Amount to fund. Defaults to microAlgos.
+
+
+### --whole-units
+Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default.
+
+### limit
+
+Get information about current fund limit on your account. Resets daily.
+
+```shell
+algokit dispenser limit [OPTIONS]
+```
+
+### Options
+
+
+### --whole-units
+Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default.
+
+### login
+
+Login to your Dispenser API account.
+
+```shell
+algokit dispenser login [OPTIONS]
+```
+
+### Options
+
+
+### --ci
+Generate an access token for CI. Issued for 30 days.
+
+
+### -o, --output <output_mode>
+Choose the output method for the access token. Defaults to stdout. Only applicable when --ci flag is set.
+
+
+* **Options**
+
+    stdout | file
+
+
+
+### -f, --file <output_filename>
+Output filename where you want to store the generated access token.Defaults to algokit_ci_token.txt. Only applicable when --ci flag is set and --output mode is file.
+
+### logout
+
+Logout of your Dispenser API account.
+
+```shell
+algokit dispenser logout [OPTIONS]
+```
+
+### refund
+
+Refund ALGOs back to the dispenser wallet address.
+
+```shell
+algokit dispenser refund [OPTIONS]
+```
+
+### Options
+
+
+### -t, --txID <tx_id>
+**Required** Transaction ID of your refund operation.
+
 ## doctor
 
-Diagnose potential environment issues that may affect AlgoKit
+Diagnose potential environment issues that may affect AlgoKit.
 
 Will search the system for AlgoKit dependencies and show their versions, as well as identifying any
 potential issues.
@@ -316,7 +428,7 @@ algokit generate [OPTIONS] COMMAND [ARGS]...
 Create a typed ApplicationClient from an ARC-32 application.json
 
 Supply the path to an application specification file or a directory to recursively search
-for “application.json” files
+for "application.json" files
 
 ```shell
 algokit generate client [OPTIONS] APP_SPEC_PATH_OR_DIR
@@ -406,7 +518,7 @@ URL to a git repo with a custom project template.
 
 
 ### --template-url-ref <URL>
-Specific tag, branch or commit to use on git repo specified with –template-url. Defaults to latest.
+Specific tag, branch or commit to use on git repo specified with --template-url. Defaults to latest.
 
 
 ### --UNSAFE-SECURITY-accept-template-url
@@ -422,7 +534,7 @@ Automatically choose default answers without asking when creating this template.
 
 
 ### --bootstrap, --no-bootstrap
-Whether to run algokit bootstrap to install and configure the new project’s dependencies locally.
+Whether to run algokit bootstrap to install and configure the new project's dependencies locally.
 
 
 ### --ide, --no-ide
@@ -492,7 +604,7 @@ algokit localnet reset [OPTIONS]
 
 
 ### --update, --no-update
-Enable or disable updating to the latest available LocalNet version, default: don’t update
+Enable or disable updating to the latest available LocalNet version, default: don't update
 
 ### start
 

docs/features/dispenser.md

@@ -0,0 +1,90 @@
+# AlgoKit TestNet Dispenser
+
+The AlgoKit Dispenser feature allows you to interact with the AlgoKit TestNet Dispenser. This feature is essential for funding your wallet with TestNet ALGOs, refunding ALGOs back to the dispenser wallet, and getting information about current fund limits on your account.
+
+## Usage
+
+```zsh
+$ algokit dispenser [OPTIONS] COMMAND [ARGS]...
+```
+
+This command provides a set of subcommands to interact with the AlgoKit TestNet Dispenser.
+Subcommands
+
+- `login`: Login to your Dispenser API account.
+- `logout`: Logout of your Dispenser API account.
+- `fund`: Fund your wallet address with TestNet ALGOs.
+- `refund`: Refund ALGOs back to the dispenser wallet address.
+- `limit`: Get information about current fund limits on your account.
+
+### API Documentation
+
+For detailed API documentation, visit the [AlgoKit Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md) documentation.
+
+### CI Access Token
+
+All dispenser commands can work in CI mode by using a CI access token that can be generated by passing `--ci` flag to `login` command. Once a token is obtained, setting the value to the following environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN` will enable CI mode for all dispenser commands. If both a user mode and CI mode access token is available, the CI mode will take precedence.
+
+## Login
+
+```zsh
+$ algokit dispenser login [OPTIONS]
+```
+
+This command logs you into your Dispenser API account if you are not already logged in.
+Options
+
+- `--ci`: Generate an access token for CI. Issued for 30 days.
+- `--output`, -o: Output mode where you want to store the generated access token. Defaults to stdout. Only applicable when --ci flag is set.
+- `--file`, -f: Output filename where you want to store the generated access token. Defaults to `ci_token.txt`. Only applicable when --ci flag is set and --output mode is `file`.
+
+> Please note, algokit relies on [keyring](https://pypi.org/project/keyring/) for storing your API credentials. This implies that your credentials are stored in your system's keychain. By default it will prompt for entering your system password unless you have set it up to always allow access for `algokit-cli` to obtain API credentials.
+
+## Logout
+
+```zsh
+$ algokit dispenser logout
+```
+
+This command logs you out of your Dispenser API account if you are logged in.
+
+## Fund
+
+```zsh
+$ algokit dispenser fund [OPTIONS]
+```
+
+This command funds your wallet address with TestNet ALGOs.
+Options
+
+- `--receiver`, -r: Receiver address to fund with TestNet ALGOs. This option is required.
+- `--amount`, -a: Amount to fund. Defaults to microAlgos. This option is required.
+- `--whole-units`: Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default.
+
+## Refund
+
+```zsh
+$ algokit dispenser refund [OPTIONS]
+```
+
+This command refunds ALGOs back to the dispenser wallet address.
+Options
+
+- `--txID`, -t: Transaction ID of your refund operation. This option is required.
+
+> Please note, performing a refund operation will not immedately change your daily fund limit. Your daily fund limit is reset daily at midnigth UTC. If you have reached your daily fund limit, you will not be able to perform a refund operation until your daily fund limit is reset.
+
+## Limit
+
+```zsh
+$ algokit dispenser limit [OPTIONS]
+```
+
+This command gets information about current fund limits on your account. The limits reset daily.
+Options
+
+- `--whole-units`: Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default.
+
+## Further Reading
+
+For in-depth details, visit the [dispenser section](../cli/index.md#dispenser) in the AlgoKit CLI reference documentation.

docs/sphinx/conf.py

@@ -16,3 +16,4 @@
 extensions = ["sphinx_click"]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+smartquotes = False