chore: added list command and updated docs

lempira · lempira · commit 2864a42f89d3 · 2025-05-14T14:32:00.000-04:00
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -90,11 +90,13 @@
     - [--workspace, --no-workspace](#--workspace---no-workspace)
     - [-a, --answer  ](#-a---answer--)
     - [example](#example)
+    - [Options](#options-13)
+    - [-l, --list](#-l---list)
     - [Arguments](#arguments-9)
     - [EXAMPLE_ID](#example_id)
   - [localnet](#localnet)
     - [codespace](#codespace)
-    - [Options](#options-13)
+    - [Options](#options-14)
     - [-m, --machine ](#-m---machine-)
     - [-a, --algod-port ](#-a---algod-port-)
     - [-i, --indexer-port ](#-i---indexer-port-)
@@ -104,22 +106,22 @@
     - [-t, --timeout ](#-t---timeout-)
     - [-f, --force](#-f---force-1)
     - [config](#config-1)
-    - [Options](#options-14)
+    - [Options](#options-15)
     - [-f, --force](#-f---force-2)
     - [Arguments](#arguments-10)
     - [ENGINE](#engine-1)
     - [console](#console)
     - [explore](#explore-1)
     - [logs](#logs)
-    - [Options](#options-15)
+    - [Options](#options-16)
     - [--follow, -f](#--follow--f)
     - [--tail ](#--tail-)
     - [reset](#reset)
-    - [Options](#options-16)
+    - [Options](#options-17)
     - [--update, --no-update](#--update---no-update)
     - [-P, --config-dir ](#-p---config-dir-)
     - [start](#start)
-    - [Options](#options-17)
+    - [Options](#options-18)
     - [-n, --name ](#-n---name--1)
     - [-P, --config-dir ](#-p---config-dir--1)
     - [-d, --dev, --no-dev](#-d---dev---no-dev)
@@ -128,18 +130,18 @@
     - [stop](#stop)
   - [project](#project)
     - [bootstrap](#bootstrap)
-    - [Options](#options-18)
-    - [--force](#--force-1)
     - [Options](#options-19)
+    - [--force](#--force-1)
+    - [Options](#options-20)
     - [--interactive, --no-ci, --non-interactive, --ci](#--interactive---no-ci---non-interactive---ci)
     - [-p, --project-name ](#-p---project-name-)
     - [-t, --type ](#-t---type-)
-    - [Options](#options-20)
-    - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci)
     - [Options](#options-21)
+    - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci)
+    - [Options](#options-22)
     - [--ci, --no-ci](#--ci---no-ci)
     - [deploy](#deploy)
-    - [Options](#options-22)
+    - [Options](#options-23)
     - [-C, -c, --command ](#-c--c---command-)
     - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci-1)
     - [-P, --path ](#-p---path-)
@@ -150,7 +152,7 @@
     - [ENVIRONMENT_NAME](#environment_name)
     - [EXTRA_ARGS](#extra_args)
     - [link](#link)
-    - [Options](#options-23)
+    - [Options](#options-24)
     - [-p, --project-name ](#-p---project-name--2)
     - [-l, --language ](#-l---language--1)
     - [-a, --all](#-a---all)
@@ -162,7 +164,7 @@
     - [run](#run)
   - [task](#task)
     - [analyze](#analyze)
-    - [Options](#options-24)
+    - [Options](#options-25)
     - [-r, --recursive](#-r---recursive)
     - [--force](#--force-2)
     - [--diff](#--diff)
@@ -171,11 +173,11 @@
     - [Arguments](#arguments-13)
     - [INPUT_PATHS](#input_paths)
     - [ipfs](#ipfs)
-    - [Options](#options-25)
+    - [Options](#options-26)
     - [-f, --file ](#-f---file--1)
     - [-n, --name ](#-n---name--2)
     - [mint](#mint)
-    - [Options](#options-26)
+    - [Options](#options-27)
     - [--creator ](#--creator-)
     - [--name ](#--name-)
     - [-u, --unit ](#-u---unit-)
@@ -187,45 +189,45 @@
     - [--mutable, --immutable](#--mutable---immutable)
     - [-n, --network ](#-n---network-)
     - [nfd-lookup](#nfd-lookup)
-    - [Options](#options-27)
+    - [Options](#options-28)
     - [-o, --output ](#-o---output--3)
     - [Arguments](#arguments-14)
     - [VALUE](#value)
     - [opt-in](#opt-in)
-    - [Options](#options-28)
+    - [Options](#options-29)
     - [-a, --account ](#-a---account-)
     - [-n, --network ](#-n---network--1)
     - [Arguments](#arguments-15)
     - [ASSET_IDS](#asset_ids)
     - [opt-out](#opt-out)
-    - [Options](#options-29)
+    - [Options](#options-30)
     - [-a, --account ](#-a---account--1)
     - [--all](#--all)
     - [-n, --network ](#-n---network--2)
     - [Arguments](#arguments-16)
     - [ASSET_IDS](#asset_ids-1)
     - [send](#send)
-    - [Options](#options-30)
+    - [Options](#options-31)
     - [-f, --file ](#-f---file--2)
     - [-t, --transaction ](#-t---transaction-)
     - [-n, --network ](#-n---network--3)
     - [sign](#sign)
-    - [Options](#options-31)
+    - [Options](#options-32)
     - [-a, --account ](#-a---account--2)
     - [-f, --file ](#-f---file--3)
     - [-t, --transaction ](#-t---transaction--1)
     - [-o, --output ](#-o---output--4)
     - [--force](#--force-3)
     - [transfer](#transfer)
-    - [Options](#options-32)
+    - [Options](#options-33)
     - [-s, --sender ](#-s---sender-)
     - [-r, --receiver ](#-r---receiver--1)
     - [--asset, --id ](#--asset---id-)
     - [-a, --amount ](#-a---amount--1)
     - [--whole-units](#--whole-units-2)
     - [-n, --network ](#-n---network--4)
     - [vanity-address](#vanity-address)
-    - [Options](#options-33)
+    - [Options](#options-34)
     - [-m, --match ](#-m---match-)
     - [-o, --output ](#-o---output--5)
     - [-a, --alias ](#-a---alias-)
@@ -234,19 +236,19 @@
     - [Arguments](#arguments-17)
     - [KEYWORD](#keyword)
     - [wallet](#wallet)
-    - [Options](#options-34)
+    - [Options](#options-35)
     - [-a, --address ](#-a---address-)
     - [-m, --mnemonic](#-m---mnemonic)
     - [-f, --force](#-f---force-4)
     - [Arguments](#arguments-18)
     - [ALIAS_NAME](#alias_name)
     - [Arguments](#arguments-19)
     - [ALIAS](#alias)
-    - [Options](#options-35)
+    - [Options](#options-36)
     - [-f, --force](#-f---force-5)
     - [Arguments](#arguments-20)
     - [ALIAS](#alias-1)
-    - [Options](#options-36)
+    - [Options](#options-37)
     - [-f, --force](#-f---force-6)
 
 # algokit
@@ -729,6 +731,12 @@ The example will be copied to a new directory in your current location.
 algokit init example [OPTIONS] [EXAMPLE_ID]
 ```
 
+### Options
+
+
+### -l, --list
+List all available examples
+
 ### Arguments
 
 
diff --git a/docs/features/init.md b/docs/features/init.md
@@ -119,4 +119,42 @@ As a suggestion, if you wanted to open the project in VS Code you could execute:
 
 ```
 
+## Initializing Examples
+
+AlgoKit provides a collection of pre-built example projects that you can use to quickly start development. These examples demonstrate various use cases and best practices for Algorand development.
+
+### Using the Example Command
+
+You can initialize a new project from an example using the `algokit init example` command:
+
+```bash
+# List and select from available examples interactively
+algokit init example
+
+#List the available examples
+algokit init example -l/--list
+
+# Initialize a specific example directly
+algokit init example <example_id>
+```
+
+When run without an example ID, the command launches an interactive selector that displays available examples with their descriptions and categories. Examples are copied to a new directory in your current location, named after the example ID.
+
+### Available Examples
+
+Examples are organized in the AlgoKit templates repository and cover various use cases including:
+
+- Smart contract examples
+- dApp frontend examples
+- Full-stack applications
+- Integration samples
+
+Each example comes with all necessary files and configurations to get started immediately. After initialization, you can navigate to the example directory and begin development.
+
+### Exploring Example Code
+
+To explore what examples are available before initializing, you can run the interactive selector and browse through the options. Examples include a name and type to help you select the most appropriate one for your needs.
+
+After initializing an example, AlgoKit automatically attempts to open the project in your default IDE to help you quickly start exploring and modifying the code.
+
 For more details about the `AlgoKit init` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#init).
diff --git a/src/algokit/cli/init/example.py b/src/algokit/cli/init/example.py
@@ -15,7 +15,8 @@
 
 @click.command("example")
 @click.argument("example_id", required=False)
-def example_command(example_id: str) -> None:
+@click.option("-l", "--list", "list_examples", is_flag=True, help="List all available examples")
+def example_command(example_id: str, *, list_examples: bool) -> None:
     """Initialize a new project from an example template.
 
     Allows you to quickly create a new project by copying one of the official AlgoKit example templates.
@@ -24,14 +25,22 @@ def example_command(example_id: str) -> None:
 
     _manage_templates_repository()
 
+    examples_config_path = Path.home() / ALGOKIT_USER_DIR / ALGOKIT_TEMPLATES_DIR / "examples" / "examples.yml"
+
+    if list_examples:
+        examples = _load_algokit_examples(str(examples_config_path.absolute()))
+        click.echo("Available examples:")
+        for example in examples:
+            click.echo(f"  {example['id']} - {example.get('name', '')}")
+        return
+
     if not example_id:
         app = ExampleSelector()
         app.run()
         example_id = app.user_answers.get("example_id", "")
         if not example_id:
             return
 
-    examples_config_path = Path.home() / ALGOKIT_USER_DIR / ALGOKIT_TEMPLATES_DIR / "examples" / "examples.yml"
     source_dir = Path.home() / ALGOKIT_USER_DIR / ALGOKIT_TEMPLATES_DIR / "examples" / example_id
     target_dir = Path.cwd() / example_id
 
diff --git a/src/algokit/core/init.py b/src/algokit/core/init.py
@@ -204,7 +204,6 @@ def _open_ide(project_path: Path, readme_path: Path | None = None, *, open_ide:
         logger.info(f"Your template includes a {readme_path.name} file, you might want to review that as a next step.")
 
 
-
 def _load_algokit_examples(examples_config_path: str) -> list[dict]:
     """
     Load and parse the examples from a YAML configuration file.
diff --git a/tests/init/example/test_example.py b/tests/init/example/test_example.py
@@ -259,3 +259,32 @@ def test_example_command_tui_select_valid_but_source_missing(mocker: MockerFixtu
     mock_copytree.assert_not_called()
     mock_open_ide.assert_not_called()
     verify(result.output)
+
+
+def test_example_command_list_option(mocker: MockerFixture, cwd: Path) -> None:
+    """Test that the --list option displays all available examples."""
+
+    mock_copytree = mocker.patch("algokit.cli.init.example.shutil.copytree")
+    mock_open_ide = mocker.patch("algokit.cli.init.example._open_ide")
+
+    # Test with short flag
+    result = invoke(["init", "example", "-l"], cwd=cwd)
+
+    assert result.exit_code == 0
+    assert "Available examples:" in result.output
+    for example in MOCK_EXAMPLES:
+        assert f"  {example['id']} - {example.get('name', '')}" in result.output
+    mock_copytree.assert_not_called()
+    mock_open_ide.assert_not_called()
+    verify(result.output)
+
+    # Test with long flag
+    result = invoke(["init", "example", "--list"], cwd=cwd)
+
+    assert result.exit_code == 0
+    assert "Available examples:" in result.output
+    for example in MOCK_EXAMPLES:
+        assert f"  {example['id']} - {example.get('name', '')}" in result.output
+    mock_copytree.assert_not_called()
+    mock_open_ide.assert_not_called()
+    verify(result.output)
diff --git a/tests/init/example/test_example.test_example_command_help.approved.txt b/tests/init/example/test_example.test_example_command_help.approved.txt
@@ -8,4 +8,5 @@ Usage: algokit init example [OPTIONS] [EXAMPLE_ID]
   copied to a new directory in your current location.
 
 Options:
+  -l, --list  List all available examples
   -h, --help  Show this message and exit.
diff --git a/tests/init/example/test_example.test_example_command_list_option.approved.txt b/tests/init/example/test_example.test_example_command_list_option.approved.txt
@@ -0,0 +1,3 @@
+Available examples:
+  react-vite - React Vite
+  python-smart-contract - Python Smart Contract

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Available examples:`
	`2`	`+ react-vite - React Vite`
	`3`	`+ python-smart-contract - Python Smart Contract`