diff --git a/.gitmodules b/.gitmodules index db01fadc..5af39cad 100644 --- a/.gitmodules +++ b/.gitmodules @@ -13,3 +13,6 @@ [submodule "imports/repos/py-algorand-sdk"] path = imports/repos/py-algorand-sdk url = https://github.com/algorand/py-algorand-sdk +[submodule "imports/repos/algokit-cli"] + path = imports/repos/algokit-cli + url = https://github.com/algorandfoundation/algokit-cli diff --git a/astro.config.mjs b/astro.config.mjs index 2982204b..3b8ac5a4 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -392,40 +392,132 @@ export default defineConfig({ collapsed: false, items: [ { - label: 'Project Tools', - link: 'reference/algokit-cli/project-tools', + label: 'Overview', + link: 'reference/algokit-cli/overview', + }, + { + label: 'Compile', + link: 'reference/algokit-cli/compile', }, { - label: 'Configuration', + label: 'Completions', + link: 'reference/algokit-cli/completions', + }, + { + label: 'Config', link: 'reference/algokit-cli/config', }, { - label: 'App Compilation', - link: 'reference/algokit-cli/compilation', + label: 'TestNet Dispenser', + link: 'reference/algokit-cli/dispenser', + }, + { + label: 'Doctor', + link: 'reference/algokit-cli/doctor', }, { - label: 'Client Generation', - link: 'reference/algokit-cli/client-generation', + label: 'Explore', + link: 'reference/algokit-cli/explore', }, { - label: 'Testnet Funding', - link: 'reference/algokit-cli/testnet-funding', + label: 'Generate', + link: 'reference/algokit-cli/generate', }, { - label: 'Explorer', - link: 'reference/algokit-cli/explorer', + label: 'Goal', + link: 'reference/algokit-cli/goal', }, { - label: 'Node Operations', - link: 'reference/algokit-cli/node-ops', + label: 'Init', + link: 'reference/algokit-cli/init', + }, + { + label: 'Localnet', + link: 'reference/algokit-cli/localnet', + }, + { + label: 'Project', + collapsed: false, + items: [ + { + label: 'Overview', + link: 'reference/algokit-cli/project/overview', + }, + { + label: 'Bootstrap', + link: 'reference/algokit-cli/project/bootstrap', + }, + { + label: 'Deploy', + link: 'reference/algokit-cli/project/deploy', + }, + { + label: 'Link', + link: 'reference/algokit-cli/project/link', + }, + { + label: 'List', + link: 'reference/algokit-cli/project/list', + }, + { + label: 'Run', + link: 'reference/algokit-cli/project/run', + }, + ], }, { label: 'Tasks', - link: 'reference/algokit-cli/tasks', + collapsed: false, + items: [ + { + label: 'Overview', + link: 'reference/algokit-cli/tasks/overview', + }, + { + label: 'Analyze', + link: 'reference/algokit-cli/tasks/analyze', + }, + { + label: 'IPFS', + link: 'reference/algokit-cli/tasks/ipfs', + }, + { + label: 'Mint', + link: 'reference/algokit-cli/tasks/mint', + }, + { + label: 'NFD Lookup', + link: 'reference/algokit-cli/tasks/nfd', + }, + { + label: 'Asset opt-(in|out)', + link: 'reference/algokit-cli/tasks/opt', + }, + { + label: 'Send', + link: 'reference/algokit-cli/tasks/send', + }, + { + label: 'Sign', + link: 'reference/algokit-cli/tasks/sign', + }, + { + label: 'Transfer', + link: 'reference/algokit-cli/tasks/transfer', + }, + { + label: 'Vanity Adress', + link: 'reference/algokit-cli/tasks/vanity-adress', + }, + { + label: 'Wallet', + link: 'reference/algokit-cli/tasks/wallet', + }, + ], }, { - label: 'CLI Reference', - link: 'reference/algokit-cli/reference', + label: 'Algokit CLI Reference', + link: 'reference/algokit-cli/cli-reference', }, ], }, diff --git a/imports/build/python/Makefile b/imports/build/python/Makefile index b08ab0ee..91c84fb8 100644 --- a/imports/build/python/Makefile +++ b/imports/build/python/Makefile @@ -28,4 +28,4 @@ utils: clean export SPHINX_REPO=utils && \ $(FULL_SPHINX_COMMAND) && \ cp -r _build/starlight/apidocs/* "../../../src/content/docs/reference/algokit-utils-py/API Reference" - + \ No newline at end of file diff --git a/imports/build/python/conf.py b/imports/build/python/conf.py index 83a9904c..c019c7ea 100644 --- a/imports/build/python/conf.py +++ b/imports/build/python/conf.py @@ -48,8 +48,7 @@ "auto_mode": True, }, ] - - + else: raise ValueError( f"Invalid repo: {repo}. Make sure to set the SPHINX_REPO environment variable." diff --git a/imports/repos/algokit-cli b/imports/repos/algokit-cli new file mode 160000 index 00000000..ba91e82a --- /dev/null +++ b/imports/repos/algokit-cli @@ -0,0 +1 @@ +Subproject commit ba91e82a226867cb764bf36fc43654924ea5ba4c diff --git a/imports/scripts/algokit-cli.ts b/imports/scripts/algokit-cli.ts new file mode 100644 index 00000000..58c232a4 --- /dev/null +++ b/imports/scripts/algokit-cli.ts @@ -0,0 +1,176 @@ +import { readFile, writeFile, readdir, mkdir, rm, cp, mkdtemp } from 'fs/promises'; +import path from 'path'; + +type FileTransformer = (content: string) => string; + +interface DirectoryTransformation { + src: string; + transformations: FileTransformer[]; + dest: string; +} + +interface FileTransformation { + src: string; + transformations: FileTransformer[]; + dest: string; +} + +const convertH1ToFrontmatter: FileTransformer = (content: string) => { + const h1Match = content.match(/^#\s+(.+)$/m); + if (!h1Match) return content; + + const title = h1Match[1].trim(); + const newContent = content.replace(/^#\s+.+$/m, '').trim(); + + return `--- +title: ${title} +--- + +${newContent}`; +}; + +const correctTypo: FileTransformer = (content: string): string => { + return content + .replaceAll('immedately', 'immediately') + .replaceAll('lastest', 'latest') + .replaceAll('directy', 'directly'); +} + + +const stripLinkExtensions: FileTransformer = (content: string): string => { + return content.replaceAll('.md', ''); +}; +const changeFeatureLinks: FileTransformer = (content: string): string => { + return content.replaceAll('/features', ''); +}; + +const changeReferenceLinks: FileTransformer = (content: string): string => { + return content.replaceAll(/\.\.?\/cli\/index/g, 'cli-reference'); +}; + +const removeLine = (line: string): FileTransformer => { + return (content: string): string => { + return content.replaceAll(line, ''); + } +}; + +const removeToc: FileTransformer = (content: string): string => { + return content.replaceAll(/^ *- \[.+$/gm, ''); +} + +async function getAllFiles(directory: string, filePattern: string): Promise { + const files: string[] = []; + + async function scan(dir: string) { + const entries = await readdir(dir, { withFileTypes: true }); + + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + + if (entry.isDirectory()) { + await scan(fullPath); + } else if (entry.isFile() && entry.name.match(filePattern)) { + files.push(fullPath); + } + } + } + + await scan(directory); + return files; +} + +async function processDirectories(configs: DirectoryTransformation[]) { + try { + for (const config of configs) { + const tempDir = await mkdtemp('.tmp'); + + await cp(config.src, tempDir, { recursive: true }); + const files = await getAllFiles(tempDir, '\\.md$'); + + for (const file of files) { + const content = await readFile(file, 'utf-8'); + const transformedContent = config.transformations.reduce( + (currentContent, transform) => transform(currentContent), + content + ); + await writeFile(file, transformedContent, 'utf-8'); + } + + await rm(config.dest, { recursive: true, force: true }); + await mkdir(config.dest, { recursive: true }); + await cp(tempDir, config.dest, { recursive: true }); + await rm(tempDir, { recursive: true, force: true }); + + console.log(`Successfully processed files from ${config.src} to ${config.dest}`); + } + } catch (error) { + console.error('Error processing files:', error); + } +} + +async function processFile(configs: FileTransformation[]) { + try { + for (const config of configs) { + const content = await readFile(config.src, 'utf-8'); + const transformedContent = config.transformations.reduce( + (currentContent, transform) => transform(currentContent), + content + ); + + await mkdir(path.dirname(config.dest), { recursive: true }); + await writeFile(config.dest, transformedContent, 'utf-8'); + + console.log(`Successfully processed file from ${config.src} to ${config.dest}`); + } + } catch (error) { + console.error('Error processing file:', error); + } +} + +await processDirectories([ + { + src: './../repos/algokit-cli/docs/features', + transformations: [ + convertH1ToFrontmatter, + stripLinkExtensions, + changeFeatureLinks, + changeReferenceLinks, + correctTypo, + removeLine('> For details on executing `algokit localnet` without `docker` or `podman` refer to the [codespaces](#codespaces) section.') + ], + dest: './../../src/content/docs/reference/algokit-cli' + }, +]); +await processFile([ + { + src: './../repos/algokit-cli/docs/cli/index.md', + transformations: [ + convertH1ToFrontmatter, + stripLinkExtensions, + changeFeatureLinks, + changeReferenceLinks, + removeToc, + ], + dest: './../../src/content/docs/reference/algokit-cli/cli-reference.md' + }, + { + src: './../repos/algokit-cli/docs/algokit.md', + transformations: [ + convertH1ToFrontmatter, + stripLinkExtensions, + changeFeatureLinks, + changeReferenceLinks, + ], + dest: './../../src/content/docs/reference/algokit-cli/overview.md' + }, + { + src: './../../src/content/docs/reference/algokit-cli/project.md', + transformations: [], + dest: './../../src/content/docs/reference/algokit-cli/project/overview.md' + }, + { + src: './../../src/content/docs/reference/algokit-cli/tasks.md', + transformations: [], + dest: './../../src/content/docs/reference/algokit-cli/tasks/overview.md' + }, +]); diff --git a/src/content/docs/reference/algokit-cli/cli-reference.md b/src/content/docs/reference/algokit-cli/cli-reference.md new file mode 100644 index 00000000..d60ddd12 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/cli-reference.md @@ -0,0 +1,1253 @@ +--- +title: AlgoKit CLI Reference Documentation +--- + +# algokit + +AlgoKit is your one-stop shop to develop applications on the Algorand blockchain. + +If you are getting started, please see the quick start tutorial: [https://bit.ly/algokit-intro-tutorial](https://bit.ly/algokit-intro-tutorial). + +```shell +algokit [OPTIONS] COMMAND [ARGS]... +``` + +### Options + +### --version + +Show the version and exit. + +### -v, --verbose + +Enable logging of DEBUG messages to the console. + +### --color, --no-color + +Force enable or disable of console output styling. + +### --skip-version-check + +Skip version checking and prompting. + +## compile + +Compile smart contracts and smart signatures written in a supported high-level language +to a format deployable on the Algorand Virtual Machine (AVM). + +```shell +algokit compile [OPTIONS] COMMAND [ARGS]... +``` + +### Options + +### -v, --version + +The compiler version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the compiler is installed and runs the installed version. If the compiler is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. + +### py + +Compile Algorand Python contract(s) using the PuyaPy compiler. + +```shell +algokit compile py [OPTIONS] [PUYAPY_ARGS]... +``` + +### Arguments + +### PUYAPY_ARGS + +Optional argument(s) + +### python + +Compile Algorand Python contract(s) using the PuyaPy compiler. + +```shell +algokit compile python [OPTIONS] [PUYAPY_ARGS]... +``` + +### Arguments + +### PUYAPY_ARGS + +Optional argument(s) + +## completions + +Install and Uninstall AlgoKit shell integrations. + +```shell +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. + +```shell +algokit completions install [OPTIONS] +``` + +### Options + +### --shell + +Specify shell to install algokit completions for. + +- **Options** + + bash | zsh + +### uninstall + +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. + +```shell +algokit completions uninstall [OPTIONS] +``` + +### Options + +### --shell + +Specify shell to install algokit completions for. + +- **Options** + + bash | zsh + +## config + +Configure settings used by AlgoKit + +```shell +algokit config [OPTIONS] COMMAND [ARGS]... +``` + +### container-engine + +Set the default container engine for use by AlgoKit CLI to run LocalNet images. + +```shell +algokit config container-engine [OPTIONS] [[docker|podman]] +``` + +### Options + +### -f, --force + +Skip confirmation prompts. Defaults to 'yes' to all prompts. + +### Arguments + +### ENGINE + +Optional argument + +### version-prompt + +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. + +```shell +algokit config version-prompt [OPTIONS] [[enable|disable]] +``` + +### Arguments + +### ENABLE + +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 + +**Required** Address or alias of the receiver to fund with TestNet ALGOs. + +### -a, --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 + +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 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 + +**Required** Transaction ID of your refund operation. + +## doctor + +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. + +```shell +algokit doctor [OPTIONS] +``` + +### Options + +### -c, --copy-to-clipboard + +Copy the contents of the doctor message (in Markdown format) in your clipboard. + +## explore + +Explore the specified network using lora. + +```shell +algokit explore [OPTIONS] [[localnet|testnet|mainnet]] +``` + +### Arguments + +### NETWORK + +Optional argument + +## generate + +Generate code for an Algorand project. + +```shell +algokit generate [OPTIONS] COMMAND [ARGS]... +``` + +### client + +Create a typed ApplicationClient from an ARC-32/56 application.json + +Supply the path to an application specification file or a directory to recursively search +for "application.json" files + +```shell +algokit generate client [OPTIONS] APP_SPEC_PATH_OR_DIR +``` + +### Options + +### -o, --output + +Path to the output file. The following tokens can be used to substitute into the output path: {contract_name}, {app_spec_dir} + +### -l, --language + +Programming language of the generated client code + +- **Options** + + python | typescript + +### -v, --version + +The client generator version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the client generator is installed and runs the installed version. If the client generator is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. + +### Arguments + +### APP_SPEC_PATH_OR_DIR + +Required argument + +## goal + +Run the Algorand goal CLI against the AlgoKit LocalNet. + +Look at [https://developer.algorand.org/docs/clis/goal/goal/](https://developer.algorand.org/docs/clis/goal/goal/) for more information. + +```shell +algokit goal [OPTIONS] [GOAL_ARGS]... +``` + +### Options + +### --console + +Open a Bash console so you can execute multiple goal commands and/or interact with a filesystem. + +### --interactive + +Force running the goal command in interactive mode. + +### Arguments + +### GOAL_ARGS + +Optional argument(s) + +## init + +Initializes a new project from a template, including prompting +for template specific questions to be used in template rendering. + +Templates can be default templates shipped with AlgoKit, or custom +templates in public Git repositories. + +Includes ability to initialise Git repository, run algokit project bootstrap and +automatically open Visual Studio Code. + +This should be run in the parent directory that you want the project folder +created in. + +By default, the --workspace flag creates projects within a workspace structure or integrates them into an existing +one, promoting organized management of multiple projects. Alternatively, +to disable this behavior use the --no-workspace flag, which ensures +the new project is created in a standalone target directory. This is +suitable for isolated projects or when workspace integration is unnecessary. + +```shell +algokit init [OPTIONS] +``` + +### Options + +### -n, --name + +Name of the project / directory / repository to create. + +### -t, --template + +Name of an official template to use. To choose interactively, run this command with no arguments. + +- **Options** + + tealscript | python | react | fullstack | base + +### --template-url + +URL to a git repo with a custom project template. + +### --template-url-ref + +Specific tag, branch or commit to use on git repo specified with --template-url. Defaults to latest. + +### --UNSAFE-SECURITY-accept-template-url + +Accept the specified template URL, acknowledging the security implications of arbitrary code execution trusting an unofficial template. + +### --git, --no-git + +Initialise git repository in directory after creation. + +### --defaults + +Automatically choose default answers without asking when creating this template. + +### --bootstrap, --no-bootstrap + +Whether to run algokit project bootstrap to install and configure the new project's dependencies locally. + +### --ide, --no-ide + +Whether to open an IDE for you if the IDE and IDE config are detected. Supported IDEs: VS Code. + +### --workspace, --no-workspace + +Whether to prefer structuring standalone projects as part of a workspace. An AlgoKit workspace is a conventional project structure that allows managing multiple standalone projects in a monorepo. + +### -a, --answer + +Answers key/value pairs to pass to the template. + +## localnet + +Manage the AlgoKit LocalNet. + +```shell +algokit localnet [OPTIONS] COMMAND [ARGS]... +``` + +### codespace + +Manage the AlgoKit LocalNet in GitHub Codespaces. + +```shell +algokit localnet codespace [OPTIONS] +``` + +### Options + +### -m, --machine + +The GitHub Codespace machine type to use. Defaults to base tier. + +- **Options** + + basicLinux32gb | standardLinux32gb | premiumLinux | largePremiumLinux + +### -a, --algod-port + +The port for the Algorand daemon. Defaults to 4001. + +### -i, --indexer-port + +The port for the Algorand indexer. Defaults to 8980. + +### -k, --kmd-port + +The port for the Algorand kmd. Defaults to 4002. + +### -n, --codespace-name + +The name of the codespace. Defaults to 'algokit-localnet_timestamp'. + +### -r, --repo-url + +The URL of the repository. Defaults to algokit base template repo. + +### -t, --timeout + +Default max runtime timeout in minutes. Upon hitting the timeout a codespace will be shutdown to prevent accidental spending over GitHub Codespaces quota. Defaults to 4 hours. + +### -f, --force + +Force delete previously used codespaces with {CODESPACE_NAME_PREFIX}\* name prefix and skip prompts. Defaults to explicitly prompting for confirmation. + +### config + +Set the default container engine for use by AlgoKit CLI to run LocalNet images. + +```shell +algokit localnet config [OPTIONS] [[docker|podman]] +``` + +### Options + +### -f, --force + +Skip confirmation prompts. Defaults to 'yes' to all prompts. + +### Arguments + +### ENGINE + +Optional argument + +### console + +Run the Algorand goal CLI against the AlgoKit LocalNet via a Bash console so you can execute multiple goal commands and/or interact with a filesystem. + +```shell +algokit localnet console [OPTIONS] +``` + +### explore + +Explore the AlgoKit LocalNet using lora. + +```shell +algokit localnet explore [OPTIONS] +``` + +### logs + +See the output of the Docker containers. + +```shell +algokit localnet logs [OPTIONS] +``` + +### Options + +### --follow, -f + +Follow log output. + +### --tail + +Number of lines to show from the end of the logs for each container. + +- **Default** + + `all` + +### reset + +Reset the AlgoKit LocalNet. + +```shell +algokit localnet reset [OPTIONS] +``` + +### Options + +### --update, --no-update + +Enable or disable updating to the latest available LocalNet version, default: don't update + +### -P, --config-dir + +Specify the custom localnet configuration directory. + +### start + +Start the AlgoKit LocalNet. + +```shell +algokit localnet start [OPTIONS] +``` + +### Options + +### -n, --name + +Specify a name for a custom LocalNet instance. AlgoKit will not manage the configuration of named LocalNet instances, allowing developers to configure it in any way they need. Defaults to 'sandbox'. + +### -P, --config-dir + +Specify the custom localnet configuration directory. Defaults to '~/.config' on UNIX and 'C:\\Users\\USERNAME\\AppData\\Roaming' on Windows. + +### -d, --dev, --no-dev + +Control whether to launch 'algod' in developer mode or not. Defaults to 'yes'. + +### --force + +Ignore the prompt to stop the LocalNet if it's already running. + +### status + +Check the status of the AlgoKit LocalNet. + +```shell +algokit localnet status [OPTIONS] +``` + +### stop + +Stop the AlgoKit LocalNet. + +```shell +algokit localnet stop [OPTIONS] +``` + +## project + +Provides a suite of commands for managing your AlgoKit project. +This includes initializing project dependencies, deploying smart contracts, +and executing predefined or custom commands within your project environment. + +```shell +algokit project [OPTIONS] COMMAND [ARGS]... +``` + +### bootstrap + +Expedited initial setup for any developer by installing and configuring dependencies and other +key development environment setup activities. + +```shell +algokit project bootstrap [OPTIONS] COMMAND [ARGS]... +``` + +### Options + +### --force + +Continue even if minimum AlgoKit version is not met + +#### all + +Runs all bootstrap sub-commands in the current directory and immediate sub directories. + +```shell +algokit project bootstrap all [OPTIONS] +``` + +### Options + +### --interactive, --no-ci, --non-interactive, --ci + +Enable/disable interactive prompts. If the CI environment variable is set, defaults to non-interactive + +### -p, --project-name + +(Optional) Projects to execute the command on. Defaults to all projects found in the current directory. + +### -t, --type + +(Optional) Limit execution to specific project types if executing from workspace. + +- **Options** + + ProjectType.FRONTEND | ProjectType.CONTRACT | ProjectType.BACKEND + +#### env + +Copies .env.template file to .env in the current working directory and prompts for any unspecified values. + +```shell +algokit project bootstrap env [OPTIONS] +``` + +### Options + +### --interactive, --non-interactive, --ci + +Enable/disable interactive prompts. If the CI environment variable is set, defaults to non-interactive + +#### npm + +Runs npm install in the current working directory to install Node.js dependencies. + +```shell +algokit project bootstrap npm [OPTIONS] +``` + +### Options + +### --ci, --no-ci + +Run 'npm ci' instead of 'npm install' in CI mode (clean install). + +#### poetry + +Installs Python Poetry (if not present) and runs poetry install in the current working directory to install Python dependencies. + +```shell +algokit project bootstrap poetry [OPTIONS] +``` + +### deploy + +Deploy smart contracts from AlgoKit compliant repository. + +```shell +algokit project deploy [OPTIONS] [ENVIRONMENT_NAME] [EXTRA_ARGS]... +``` + +### Options + +### -C, -c, --command + +Custom deploy command. If not provided, will load the deploy command from .algokit.toml file. + +### --interactive, --non-interactive, --ci + +Enable/disable interactive prompts. Defaults to non-interactive if the CI environment variable is set. Interactive MainNet deployments prompt for confirmation. + +### -P, --path + +Specify the project directory. If not provided, current working directory will be used. + +### --deployer + +(Optional) Alias of the deployer account. Otherwise, will prompt the deployer mnemonic if specified in .algokit.toml file. + +### --dispenser + +(Optional) Alias of the dispenser account. Otherwise, will prompt the dispenser mnemonic if specified in .algokit.toml file. + +### -p, --project-name + +(Optional) Projects to execute the command on. Defaults to all projects found in the current directory. Option is mutually exclusive with command. + +### Arguments + +### ENVIRONMENT_NAME + +Optional argument + +### EXTRA_ARGS + +Optional argument(s) + +### link + +Automatically invoke 'algokit generate client' on contract projects available in the workspace. +Must be invoked from the root of a standalone 'frontend' typed project. + +```shell +algokit project link [OPTIONS] +``` + +### Options + +### -p, --project-name + +Specify contract projects for the command. Defaults to all in the current workspace. + +### -l, --language + +Programming language of the generated client code + +- **Options** + + python | typescript + +### -a, --all + +Link all contract projects with the frontend project Option is mutually exclusive with project_name. + +### -f, --fail-fast + +Exit immediately if at least one client generation process fails + +### -v, --version + +The client generator version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the client generator is installed and runs the installed version. If the client generator is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. + +### list + +List all projects in the workspace + +```shell +algokit project list [OPTIONS] [WORKSPACE_PATH] +``` + +### Arguments + +### WORKSPACE_PATH + +Optional argument + +### run + +Define custom commands and manage their execution in you projects. + +```shell +algokit project run [OPTIONS] COMMAND [ARGS]... +``` + +## task + +Collection of useful tasks to help you develop on Algorand. + +```shell +algokit task [OPTIONS] COMMAND [ARGS]... +``` + +### analyze + +Analyze TEAL programs for common vulnerabilities using Tealer. This task uses a third party tool to suggest improvements for your TEAL programs, but remember to always test your smart contracts code, follow modern software engineering practices and use the guidelines for smart contract development. This should not be used as a substitute for an actual audit. For full list of available detectors, please refer to [https://github.com/crytic/tealer?tab=readme-ov-file#detectors](https://github.com/crytic/tealer?tab=readme-ov-file#detectors) + +```shell +algokit task analyze [OPTIONS] INPUT_PATHS... +``` + +### Options + +### -r, --recursive + +Recursively search for all TEAL files within the provided directory. + +### --force + +Force verification without the disclaimer confirmation prompt. + +### --diff + +Exit with a non-zero code if differences are found between current and last reports. Reports are generated each run, but with this flag execution fails if the current report doesn't match the last report. Reports are stored in the .algokit/static-analysis/snapshots folder by default. Use --output for a custom path. + +### -o, --output + +Directory path where to store the results of the static analysis. Defaults to .algokit/static-analysis/snapshots. + +### -e, --exclude + +Exclude specific vulnerabilities from the analysis. Supports multiple exclusions in a single run. + +### Arguments + +### INPUT_PATHS + +Required argument(s) + +### ipfs + +Upload files to IPFS using Pinata provider. + +```shell +algokit task ipfs [OPTIONS] COMMAND [ARGS]... +``` + +#### login + +Login to Pinata ipfs provider. You will be prompted for your JWT. + +```shell +algokit task ipfs login [OPTIONS] +``` + +#### logout + +Logout of Pinata ipfs provider. + +```shell +algokit task ipfs logout [OPTIONS] +``` + +#### upload + +Upload a file to Pinata ipfs provider. Please note, max file size is 100MB. + +```shell +algokit task ipfs upload [OPTIONS] +``` + +### Options + +### -f, --file + +**Required** Path to the file to upload. + +### -n, --name + +Human readable name for this upload, for use in file listings. + +### mint + +Mint new fungible or non-fungible assets on Algorand. + +```shell +algokit task mint [OPTIONS] +``` + +### Options + +### --creator + +**Required** Address or alias of the asset creator. + +### --name + +Asset name. + +### -u, --unit + +**Required** Unit name of the asset. + +### -t, --total + +Total supply of the asset. Defaults to 1. + +### -d, --decimals + +Number of decimals. Defaults to 0. + +### --nft, --ft + +Whether the asset should be validated as NFT or FT. Refers to NFT by default and validates canonical +definitions of pure or fractional NFTs as per ARC3 standard. + +### -i, --image + +**Required** Path to the asset image file to be uploaded to IPFS. + +### -m, --metadata + +Path to the ARC19 compliant asset metadata file to be uploaded to IPFS. If not provided, +a default metadata object will be generated automatically based on asset-name, decimals and image. +For more details refer to [https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema](https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema). + +### --mutable, --immutable + +Whether the asset should be mutable or immutable. Refers to ARC19 by default. + +### -n, --network + +Network to use. Refers to localnet by default. + +- **Options** + + localnet | testnet | mainnet + +### nfd-lookup + +Perform a lookup via NFD domain or address, returning the associated address or domain respectively. + +```shell +algokit task nfd-lookup [OPTIONS] VALUE +``` + +### Options + +### -o, --output + +Output format for NFD API response. Defaults to address|domain resolved. + +- **Options** + + full | tiny | address + +### Arguments + +### VALUE + +Required argument + +### opt-in + +Opt-in to an asset(s). This is required before you can receive an asset. Use -n to specify localnet, testnet, or mainnet. To supply multiple asset IDs, separate them with a whitespace. + +```shell +algokit task opt-in [OPTIONS] ASSET_IDS... +``` + +### Options + +### -a, --account + +**Required** Address or alias of the signer account. + +### -n, --network + +Network to use. Refers to localnet by default. + +- **Options** + + localnet | testnet | mainnet + +### Arguments + +### ASSET_IDS + +Required argument(s) + +### opt-out + +opt-out of an asset(s). You can only opt out of an asset with a zero balance. Use -n to specify localnet, testnet, or mainnet. To supply multiple asset IDs, separate them with a whitespace. + +```shell +algokit task opt-out [OPTIONS] [ASSET_IDS]... +``` + +### Options + +### -a, --account + +**Required** Address or alias of the signer account. + +### --all + +Opt-out of all assets with zero balance. + +### -n, --network + +Network to use. Refers to localnet by default. + +- **Options** + + localnet | testnet | mainnet + +### Arguments + +### ASSET_IDS + +Optional argument(s) + +### send + +Send a signed transaction to the given network. + +```shell +algokit task send [OPTIONS] +``` + +### Options + +### -f, --file + +Single or multiple message pack encoded signed transactions from binary file to send. Option is mutually exclusive with transaction. + +### -t, --transaction + +Base64 encoded signed transaction to send. Option is mutually exclusive with file. + +### -n, --network + +Network to use. Refers to localnet by default. + +- **Options** + + localnet | testnet | mainnet + +### sign + +Sign goal clerk compatible Algorand transaction(s). + +```shell +algokit task sign [OPTIONS] +``` + +### Options + +### -a, --account + +**Required** Address or alias of the signer account. + +### -f, --file + +Single or multiple message pack encoded transactions from binary file to sign. Option is mutually exclusive with transaction. + +### -t, --transaction + +Single base64 encoded transaction object to sign. Option is mutually exclusive with file. + +### -o, --output + +The output file path to store signed transaction(s). + +### --force + +Force signing without confirmation. + +### transfer + +Transfer algos or assets from one account to another. + +```shell +algokit task transfer [OPTIONS] +``` + +### Options + +### -s, --sender + +**Required** Address or alias of the sender account. + +### -r, --receiver + +**Required** Address or alias to an account that will receive the asset(s). + +### --asset, --id + +Asset ID to transfer. Defaults to 0 (Algo). + +### -a, --amount + +**Required** Amount to transfer. + +### --whole-units + +Use whole units (Algos | ASAs) instead of smallest divisible units (for example, microAlgos). Disabled by default. + +### -n, --network + +Network to use. Refers to localnet by default. + +- **Options** + + localnet | testnet | mainnet + +### vanity-address + +Generate a vanity Algorand address. Your KEYWORD can only include letters A - Z and numbers 2 - 7. +Keeping your KEYWORD under 5 characters will usually result in faster generation. +Note: The longer the KEYWORD, the longer it may take to generate a matching address. +Please be patient if you choose a long keyword. + +```shell +algokit task vanity-address [OPTIONS] KEYWORD +``` + +### Options + +### -m, --match + +Location where the keyword will be included. Default is start. + +- **Options** + + start | anywhere | end + +### -o, --output + +How the output will be presented. + +- **Options** + + stdout | alias | file + +### -a, --alias + +Alias for the address. Required if output is "alias". + +### --file-path + +File path where to dump the output. Required if output is "file". + +### -f, --force + +Allow overwriting an aliases without confirmation, if output option is 'alias'. + +### Arguments + +### KEYWORD + +Required argument + +### wallet + +Create short aliases for your addresses and accounts on AlgoKit CLI. + +```shell +algokit task wallet [OPTIONS] COMMAND [ARGS]... +``` + +#### add + +Add an address or account to be stored against a named alias (at most 50 aliases). + +```shell +algokit task wallet add [OPTIONS] ALIAS_NAME +``` + +### Options + +### -a, --address
+ +**Required** The address of the account. + +### -m, --mnemonic + +If specified then prompt the user for a mnemonic phrase interactively using masked input. + +### -f, --force + +Allow overwriting an existing alias. + +### Arguments + +### ALIAS_NAME + +Required argument + +#### get + +Get an address or account stored against a named alias. + +```shell +algokit task wallet get [OPTIONS] ALIAS +``` + +### Arguments + +### ALIAS + +Required argument + +#### list + +List all addresses and accounts stored against a named alias. + +```shell +algokit task wallet list [OPTIONS] +``` + +#### remove + +Remove an address or account stored against a named alias. + +```shell +algokit task wallet remove [OPTIONS] ALIAS +``` + +### Options + +### -f, --force + +Allow removing an alias without confirmation. + +### Arguments + +### ALIAS + +Required argument + +#### reset + +Remove all aliases. + +```shell +algokit task wallet reset [OPTIONS] +``` + +### Options + +### -f, --force + +Allow removing all aliases without confirmation. diff --git a/src/content/docs/reference/algokit-cli/client-generation.mdx b/src/content/docs/reference/algokit-cli/client-generation.mdx deleted file mode 100644 index 20071997..00000000 --- a/src/content/docs/reference/algokit-cli/client-generation.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Client Generation ---- diff --git a/src/content/docs/reference/algokit-cli/compilation.mdx b/src/content/docs/reference/algokit-cli/compilation.mdx deleted file mode 100644 index ac0db524..00000000 --- a/src/content/docs/reference/algokit-cli/compilation.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: App Compilation ---- diff --git a/src/content/docs/reference/algokit-cli/compile.md b/src/content/docs/reference/algokit-cli/compile.md new file mode 100644 index 00000000..3b8a1ffb --- /dev/null +++ b/src/content/docs/reference/algokit-cli/compile.md @@ -0,0 +1,100 @@ +--- +title: AlgoKit Compile +--- + +The AlgoKit Compile feature enables you to compile smart contracts (apps) and smart signatures (logic signatures) written in a supported high-level language to a format deployable on the Algorand Virtual Machine (AVM). + +When running the compile command, AlgoKit will take care of working out which compiler you need and dynamically resolve it. Additionally, AlgoKit will detect if a matching compiler version is already installed globally on your machine or is included in your project and use that. + +## Prerequisites + +See [Compile Python - Prerequisites](#prerequisites-1) for details. + +## What is Algorand Python & PuyaPy? + +Algorand Python is 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). + +Algorand Python can be deployed to Algorand by using the PuyaPy optimising compiler, which takes Algorand Python and outputs [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032) application spec files (among other formats) which, [when deployed](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/generate#1-typed-clients), will result in AVM bytecode execution semantics that match the given Python code. + +If you want to learn more, check out the [PuyaPy docs](https://github.com/algorandfoundation/puya/blob/main/docs/index). + +Below is an example Algorand Python smart contract. + +```py +from algopy import ARC4Contract, arc4 + +class HelloWorldContract(ARC4Contract): + @arc4.abimethod + def hello(self, name: arc4.String) -> arc4.String: + return "Hello, " + name +``` + +For more complex examples, see the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) in the [PuyaPy repo](https://github.com/algorandfoundation/puya). + +## Usage + +Available commands and possible usage are as follows: + +``` +Usage: algokit compile [OPTIONS] COMMAND [ARGS]... + + Compile smart contracts and smart signatures written in a supported high-level language to a format deployable on + the Algorand Virtual Machine (AVM). + +Options: + -v, --version TEXT The compiler version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks + if the compiler is installed and runs the installed version. If the compiler is not installed, + AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed + version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. + -h, --help Show this message and exit. + +Commands: + py Compile Algorand Python contract(s) using the PuyaPy compiler. + python Compile Algorand Python contract(s) using the PuyaPy compiler. +``` + +### Compile Python + +The command `algokit compile python` or `algokit compile py` will run the [PuyaPy](https://github.com/algorandfoundation/puya) compiler against the supplied Algorand Python smart contract. + +All arguments supplied to the command are passed directly to PuyaPy, therefore this command supports all options supported by the PuyaPy compiler. + +Any errors detected by PuyaPy during the compilation process will be printed to the output. + +#### Prerequisites + +PuyaPy requires Python 3.12+, so please ensure your Python version satisfies this requirement. + +This command will attempt to resolve a matching installed PuyaPy compiler, either globally installed in the system or locally installed in your project (via [Poetry](https://python-poetry.org/)). If no appropriate match is found, the PuyaPy compiler will be dynamically run using [pipx](https://pipx.pypa.io/stable/). In this case pipx is also required. + +#### Examples + +To see a list of the supported PuyaPy options, run the following: + +```shell +algokit compile python -h +``` + +To determine the version of the PuyaPy compiler in use, execute the following command: + +```shell +algokit compile python --version +``` + +To compile a single Algorand Python smart contract and write the output to a specific location, run the following: + +```shell +algokit compile python hello_world/contract.py --out-dir hello_world/out +``` + +To compile multiple Algorand Python smart contracts and write the output to a specific location, run the following: + +```shell +algokit compile python hello_world/contract.py calculator/contract.py --out-dir my_contracts +``` + +To compile a directory of Algorand Python smart contracts and write the output to the default location, run the following: + +```shell +algokit compile python my_contracts +``` diff --git a/src/content/docs/reference/algokit-cli/completions.md b/src/content/docs/reference/algokit-cli/completions.md new file mode 100644 index 00000000..19bc1b47 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/completions.md @@ -0,0 +1,58 @@ +--- +title: AlgoKit Completions +--- + +AlgoKit supports shell completions for zsh and bash shells, e.g. + +**bash** + +``` +$ algokit +bootstrap completions config doctor explore goal init sandbox +``` + +**zsh** + +``` +$ ~ algokit +bootstrap -- Bootstrap AlgoKit project dependencies. +completions -- Install and Uninstall AlgoKit shell integration. +config -- Configure AlgoKit options. +doctor -- Run the Algorand doctor CLI. +explore -- Explore the specified network in the... +goal -- Run the Algorand goal CLI against the AlgoKit Sandbox. +init -- Initializes a new project. +sandbox -- Manage the AlgoKit sandbox. +``` + +## Installing + +To setup the completions, AlgoKit provides commands that will modify the current users interactive shell script (`.bashrc`/`.zshrc`). + +> **Note** +> If you would prefer AlgoKit to not modify your interactive shell scripts you can install the completions yourself by following the instructions [here](https://click.palletsprojects.com/en/8.1.x/shell-completion/). + +To [install](cli-reference#install) completions for the current shell execute `algokit completions install`. You should see output similar to below: + +``` +$ ~ algokit completions install +AlgoKit completions installed for zsh 🎉 +Restart shell or run `. ~/.zshrc` to enable completions +``` + +After installing the completions don't forget to restart the shell to begin using them! + +## Uninstalling + +To [uninstall](cli-reference#uninstall) completions for the current shell run `algokit completions uninstall`: + +``` +$ ~ algokit completions uninstall +AlgoKit completions uninstalled for zsh 🎉 +``` + +## Shell Option + +To install/uninstall the completions for a specific [shell](cli-reference#shell) the `--shell` option can be used e.g. `algokit completions install --shell bash`. + +To learn more about the `algokit completions` command, please refer to [completions](cli-reference#completions) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/config.md b/src/content/docs/reference/algokit-cli/config.md new file mode 100644 index 00000000..0f2b0052 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/config.md @@ -0,0 +1,39 @@ +--- +title: AlgoKit Config +--- + +The `algokit config` command allows you to manage various global settings used by AlgoKit CLI. This feature is essential for customizing your AlgoKit environment to suit your needs. + +## Usage + +This command group provides a set of subcommands to configure AlgoKit settings. +Subcommands + +- `version-prompt`: Configure the version prompt settings. +- `container-engine`: Configure the container engine settings. + +### Version Prompt Configuration + +```zsh +$ algokit config version-prompt [OPTIONS] +``` + +This command configures the version prompt settings for AlgoKit. + +- `--enable`: Enable the version prompt. +- `--disable`: Disable the version prompt. + +### Container Engine Configuration + +```zsh +$ algokit config container-engine [OPTIONS] +``` + +This command configures the container engine settings for AlgoKit. + +- `--engine`, -e: Specify the container engine to use (e.g., Docker, Podman). This option is required. +- `--path`, -p: Specify the path to the container engine executable. Optional. + +## Further Reading + +For in-depth details, visit the [configuration section](cli-reference#config) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/config.mdx b/src/content/docs/reference/algokit-cli/config.mdx deleted file mode 100644 index 460f7639..00000000 --- a/src/content/docs/reference/algokit-cli/config.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Configuration ---- diff --git a/src/content/docs/reference/algokit-cli/dispenser.md b/src/content/docs/reference/algokit-cli/dispenser.md new file mode 100644 index 00000000..f88c4ba7 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/dispenser.md @@ -0,0 +1,92 @@ +--- +title: 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) 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 [alias](./tasks/wallet#add) or 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. The receiver address of the transaction must be the same as the dispenser wallet address that you can obtain by observing a `sender` field of [`fund`](#fund) transaction. + +> Please note, performing a refund operation will not immediately 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-reference#dispenser) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/doctor.md b/src/content/docs/reference/algokit-cli/doctor.md new file mode 100644 index 00000000..5c2f7c79 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/doctor.md @@ -0,0 +1,55 @@ +--- +title: AlgoKit Doctor +--- + +The AlgoKit Doctor feature allows you to check your AlgoKit installation along with its dependencies. This is useful for diagnosing potential issues with using AlgoKit. + +## Functionality + +The AlgoKit Doctor allows you to make sure that your system has the correct dependencies installed and that they satisfy the minimum required versions. All passed checks will appear in your command line natural color while warnings will be in yellow (warning) and errors or missing critical services will be in red (error). The critical services that AlgoKit will check for (since they are [directly used by certain commands](../../README#prerequisites)): Docker, docker compose and git. + +Please run this command to if you are facing an issue running AlgoKit. It is recommended to run it before [submitting an issue to AlgoKit](https://github.com/algorandfoundation/algokit-cli/issues/new). You can copy the contents of the Doctor command message (in Markdown format) to your clipboard by providing the `-c` flag to the command as follows `algokit doctor -c`. + +# Examples + +For example, running `algokit doctor` with all prerequisites installed will result in output similar to the following: + +``` +$ ~ algokit doctor +timestamp: 2023-03-29T03:58:05+00:00 +AlgoKit: 0.6.0 +AlgoKit Python: 3.11.2 (main, Mar 24 2023, 00:16:47) [Clang 14.0.0 (clang-1400.0.29.202)] (location: /Users/algokit/.local/pipx/venvs/algokit) +OS: macOS-13.2.1-arm64-arm-64bit +docker: 20.10.22 +docker compose: 2.15.1 +git: 2.39.1 +python: 3.10.9 (location: /Users/algokit/.asdf/shims/python) +python3: 3.10.9 (location: /Users/algokit/.asdf/shims/python3) +pipx: 1.2.0 +poetry: 1.3.2 +node: 18.12.1 +npm: 8.19.2 +brew: 4.0.10-34-gb753315 + +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` +``` + +The doctor command will indicate if there is any issues to address, for example: + +If AlgoKit detects a newer version, this will be indicated next to the AlgoKit version + +``` +AlgoKit: 1.2.3 (latest: 4.5.6) +``` + +If the detected version of docker compose is unsupported, this will be shown: + +``` +docker compose: 2.1.3 + Docker Compose 2.5.0 required to run `algokit localnet command`; + install via https://docs.docker.com/compose/install/ +``` + +For more details about the `AlgoKit doctor` command, please refer to the [AlgoKit CLI reference documentation](cli-reference#doctor). diff --git a/src/content/docs/reference/algokit-cli/explore.md b/src/content/docs/reference/algokit-cli/explore.md new file mode 100644 index 00000000..a3a9d9b0 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/explore.md @@ -0,0 +1,23 @@ +--- +title: AlgoKit explore +--- + +AlgoKit provides a quick shortcut to [explore](cli-reference#explore) various Algorand networks using [lora](https://lora.algokit.io/) including [AlgoKit LocalNet](./localnet)! + +## LocalNet + +The following three commands are all equivalent and will open lora pointing to the local [AlgoKit LocalNet](./localnet) instance: + +- `algokit explore` +- `algokit explore localnet` +- `algokit localnet explore` + +## Testnet + +`algokit explore testnet` will open lora pointing to TestNet via the [node](https://algonode.io/api/). + +## Mainnet + +`algokit explore mainnet` will open lora pointing to MainNet via the [node](https://algonode.io/api/). + +To learn more about the `algokit explore` command, please refer to [explore](cli-reference#explore) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/explorer.mdx b/src/content/docs/reference/algokit-cli/explorer.mdx deleted file mode 100644 index 79a669aa..00000000 --- a/src/content/docs/reference/algokit-cli/explorer.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Explorer ---- diff --git a/src/content/docs/reference/algokit-cli/generate.md b/src/content/docs/reference/algokit-cli/generate.md new file mode 100644 index 00000000..ce15a7fe --- /dev/null +++ b/src/content/docs/reference/algokit-cli/generate.md @@ -0,0 +1,181 @@ +--- +title: AlgoKit Generate +--- + +The `algokit generate` [command](cli-reference#generate) is used to generate components used in an AlgoKit project. It also allows for custom generate commands which are loaded from the .algokit.toml file in your project directory. + +## 1. Typed clients + +The `algokit generate client` [command](cli-reference#client) can be used to generate a typed client from an [ARC-0032](https://arc.algorand.foundation/ARCs/arc-0032) or [ARC-0056](https://github.com/algorandfoundation/ARCs/pull/258) application specification with both Python and TypeScript available as target languages. + +### Prerequisites + +To generate Python clients an installation of pip and pipx is required. +To generate TypeScript clients an installation of Node.js and npx is also required. + +Each generated client will also have a dependency on `algokit-utils` libraries for the target language. + +### Input file / directory + +You can either specify a path to an ARC-0032 JSON file, an ARC-0056 JSON file or to a directory that is recursively scanned for `application.json`, `*.arc32.json`, `*.arc56.json` file(s). + +### Output tokens + +The output path is interpreted as relative to the current working directory, however an absolute path may also be specified e.g. +`algokit generate client application.json --output /absolute/path/to/client.py` + +There are two tokens available for use with the `-o`, `--output` [option](cli-reference#-o---output-): + +- `{contract_name}`: This will resolve to a name based on the ARC-0032/ARC-0056 contract name, formatted appropriately for the target language. +- `{app_spec_dir}`: This will resolve to the parent directory of the `application.json`, `*.arc32.json`, `*.arc56.json` file which can be useful to output a client relative to its source file. + +### Version Pinning + +If you want to ensure typed client output stability across different environments and additionally protect yourself from any potential breaking changes introduced in the client generator packages, you can specify a version you'd like to pin to. + +To make use of this feature, pass `-v`, `--version`, for example `algokit generate client --version 1.2.3 path/to/application.json`. + +Alternatively, you can achieve output stability by installing the underlying [Python](https://github.com/algorandfoundation/algokit-client-generator-py) or [TypeScript](https://github.com/algorandfoundation/algokit-client-generator-ts) client generator package either locally in your project (via `poetry` or `npm` respectively) or globally on your system (via `pipx` or `npm` respectively). AlgoKit will search for a matching installed version before dynamically resolving. + +### Usage + +Usage examples of using a generated client are below, typed clients allow your favourite IDE to provide better intellisense to provide better discoverability +of available operations and parameters. + +#### Python + +```python +# A similar working example can be seen in the algokit python template, when using Python deployment +from smart_contracts.artifacts.HelloWorldApp.client import ( + HelloWorldAppClient, +) + +app_client = HelloWorldAppClient( + algod_client, + creator=deployer, + indexer_client=indexer_client, +) +deploy_response = app_client.deploy( + on_schema_break=OnSchemaBreak.ReplaceApp, + on_update=OnUpdate.UpdateApp, + allow_delete=True, + allow_update=True, +) + +response = app_client.hello(name="World") +``` + +#### TypeScript + +```typescript +// A similar working example can be seen in the algokit python template with typescript deployer, when using TypeScript deployment +import { HelloWorldAppClient } from './artifacts/HelloWorldApp/client'; + +const appClient = new HelloWorldAppClient( + { + resolveBy: 'creatorAndName', + findExistingUsing: indexer, + sender: deployer, + creatorAddress: deployer.addr, + }, + algod, +); +const app = await appClient.deploy({ + allowDelete: isLocal, + allowUpdate: isLocal, + onSchemaBreak: isLocal ? 'replace' : 'fail', + onUpdate: isLocal ? 'update' : 'fail', +}); +const response = await appClient.hello({ name: 'world' }); +``` + +### Examples + +To output a single application.json to a python typed client: +`algokit generate client path/to/application.json --output client.py` + +To process multiple application.json in a directory structure and output to a typescript client for each in the current directory: +`algokit generate client smart_contracts/artifacts --output {contract_name}.ts` + +To process multiple application.json in a directory structure and output to a python client alongside each application.json: +`algokit generate client smart_contracts/artifacts --output {app_spec_path}/client.py` + +## 2. Using Custom Generate Commands + +Custom generate commands are defined in the `.algokit.toml` file within the project directory, typically supplied by community template builders or official AlgoKit templates. These commands are specified under the `generate` key and serve to execute a generator at a designated path with provided answer key/value pairs. + +### Understanding `Generators` + +A `generator` is essentially a compact, self-sufficient `copier` template. This template can optionally be defined within the primary `algokit templates` to offer supplementary functionality after a project is initialized from the template. For instance, the official [`algokit-python-template`](https://github.com/algorandfoundation/algokit-python-template/tree/main/template_content) provides a generator within the `.algokit/generators` directory. This generator can be employed for executing extra tasks on AlgoKit projects that have been initiated from this template, such as adding new smart contracts to an existing project. For a comprehensive explanation, please refer to the [`architecture decision record`](../architecture-decisions/2023-07-19_advanced_generate_command). + +### Requirements + +To utilize custom generate commands, you must have `copier` installed. This installation is included by default in the AlgoKit CLI. Therefore, no additional installation is necessary if you have already installed the `algokit cli`. + +### How to Use + +A custom command can be defined in the `.algokit.toml` as shown: + +```toml +[generate.my_generator] +path = "path/to/my_generator" +description = "A brief description of the function of my_generator" +``` + +Following this, you can execute the command as follows: + +`algokit generate my_generator --answer key value --path path/to/my_generator` + +If no `path` is given, the command will use the path specified in the `.algokit.toml`. If no `answer` is provided, the command will initiate an interactive `copier` prompt to request answers (similar to `algokit init`). + +The custom command employs the `copier` library to duplicate the files from the generator's path to the current working directory, substituting any values from the `answers` dictionary. + +### Examples + +As an example, let's use the `smart-contract` generator from the `algokit-python-template` to add new contract to an existing project based on that template. The `smart-contract` generator is defined as follows: + +```toml +[algokit] +min_version = "v1.3.1" + +... # other keys + +[generate.smart_contract] +description = "Adds a new smart contract to the existing project" +path = ".algokit/generators/create_contract" +``` + +To execute this generator, ensure that you are operating from the same directory as the `.algokit.toml` file, and then run: + +```bash +$ algokit generate + +# The output will be as follows: +# Note how algokit dynamically injects a new `smart-contract` command based +# on the `.algokit.toml` file + +Usage: algokit generate [OPTIONS] COMMAND [ARGS]... + + Generate code for an Algorand project. + +Options: + -h, --help Show this message and exit. + +Commands: + client Create a typed ApplicationClient from an ARC-32 application.json + smart-contract Adds a new smart contract to the existing project +``` + +To execute the `smart-contract` generator, run: + +```bash +$ algokit generate smart-contract + +# or + +$ algokit generate smart-contract -a contract_name "MyCoolContract" +``` + +#### Third Party Generators + +It is important to understand that by default, AlgoKit will always prompt you before executing a generator to ensure it's from a trusted source. If you are confident about the source of the generator, you can use the `--force` or `-f` option to execute the generator without this confirmation prompt. Be cautious while using this option and ensure the generator is from a trusted source. At the moment, a trusted source for a generator is defined as _a generator that is included in the official AlgoKit templates (e.g. `smart-contract` generator in `algokit-python-template`)_ diff --git a/src/content/docs/reference/algokit-cli/goal.md b/src/content/docs/reference/algokit-cli/goal.md new file mode 100644 index 00000000..1f74fc18 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/goal.md @@ -0,0 +1,141 @@ +--- +title: AlgoKit goal +--- + +AlgoKit goal command provides the user with a mechanism to run [goal cli](https://developer.algorand.org/docs/clis/goal/goal/) commands against the current [AlgoKit LocalNet](./localnet). + +You can explore all possible goal commands by running `algokit goal` e.g.: + +``` +$ ~ algokit goal + GOAL is the CLI for interacting Algorand software instance. The binary 'goal' is installed alongside the algod binary and is considered an integral part of the complete installation. The binaries should be used in tandem - you should not try to use a version of goal with a different version of algod. + + Usage: + goal [flags] + goal [command] + + Available Commands: + account Control and manage Algorand accounts + app Manage applications + asset Manage assets + clerk Provides the tools to control transactions + completion Shell completion helper + help Help about any command + kmd Interact with kmd, the key management daemon + ledger Access ledger-related details + license Display license information + logging Control and manage Algorand logging + network Create and manage private, multi-node, locally-hosted networks + node Manage a specified algorand node + protocols + report + version The current version of the Algorand daemon (algod) + wallet Manage wallets: encrypted collections of Algorand account keys + + Flags: + -d, --datadir stringArray Data directory for the node + -h, --help help for goal + -k, --kmddir string Data directory for kmd + -v, --version Display and write current build version and exit + + Use "goal [command] --help" for more information about a command. +``` + +For instance, running `algokit goal report` would result in output like: + +``` +$ ~ algokit goal report + 12885688322 + 3.12.2.dev [rel/stable] (commit #181490e3) + go-algorand is licensed with AGPLv3.0 + source code available at https://github.com/algorand/go-algorand + + Linux ff7828f2da17 5.15.49-linuxkit #1 SMP PREEMPT Tue Sep 13 07:51:32 UTC 2022 aarch64 GNU/Linux + + Genesis ID from genesis.json: sandnet-v1 + + Last committed block: 0 + Time since last block: 0.0s + Sync Time: 0.0s + Last consensus protocol: future + Next consensus protocol: future + Round for next consensus protocol: 1 + Next consensus protocol supported: true + Last Catchpoint: + Genesis ID: sandnet-v1 + Genesis hash: vEg1NCh6SSXwS6O5HAfjYCCNAs4ug328s3RYMr9syBg= +``` + +If the AlgoKit Sandbox `algod` docker container is not present or not running, the command will fail with a clear error, e.g.: + +``` +$ ~ algokit goal + Error: No such container: algokit_algod + Error: Error executing goal; ensure the Sandbox is started by executing `algokit sandbox status` +``` + +``` +$ ~ algokit goal + Error response from daemon: Container 5a73961536e2c98e371465739053d174066c40d00647c8742f2bb39eb793ed7e is not running + Error: Error executing goal; ensure the Sandbox is started by executing `algokit sandbox status` +``` + +## Working with Files in the Container + +When interacting with the container, especially if you're using tools like goal, you might need to reference files or directories. Here's how to efficiently deal with files and directories: + +### Automatic File Mounting + +When you specify a file or directory path in your `goal` command, the system will automatically mount that path from your local filesystem into the container. This way, you don't need to copy files manually each time. + +For instance, if you want to compile a `teal` file: + +``` +algokit goal clerk compile /Path/to/inputfile/approval.teal -o /Path/to/outputfile/approval.compiled +``` + +Here, `/Path/to/inputfile/approval.teal` and `/Path/to/outputfile/approval.compiled` are paths on your local file system, and they will be automatically accessible to the `goal` command inside the container. + +### Manual Copying of Files + +In case you want to manually copy files into the container, you can do so using `docker cp`: + +``` +docker cp foo.txt algokit_algod:/root +``` + +This command copies the `foo.txt` from your local system into the root directory of the `algokit_algod` container. + +Note: Manual copying is optional and generally only necessary if you have specific reasons for doing so since the system will auto-mount paths specified in commands. + +## Running multiple commands + +If you want to run multiple commands or interact with the filesystem you can execute `algokit goal --console`. This will open a [Bash](https://www.gnu.org/software/bash/) shell session on the `algod` Docker container and from there you can execute goal directly, e.g.: + +```bash +$ algokit goal --console +Opening Bash console on the algod node; execute `exit` to return to original console +root@82d41336608a:~# goal account list +[online] C62QEFC7MJBPHAUDMGVXGZ7WRWFAF3XYPBU3KZKOFHYVUYDGU5GNWS4NWU C62QEFC7MJBPHAUDMGVXGZ7WRWFAF3XYPBU3KZKOFHYVUYDGU5GNWS4NWU 4000000000000000 microAlgos +[online] DVPJVKODAVEKWQHB4G7N6QA3EP7HKAHTLTZNWMV4IVERJQPNGKADGURU7Y DVPJVKODAVEKWQHB4G7N6QA3EP7HKAHTLTZNWMV4IVERJQPNGKADGURU7Y 4000000000000000 microAlgos +[online] 4BH5IKMDDHEJEOZ7T5LLT4I7EVIH5XCOTX3TPVQB3HY5TUBVT4MYXJOZVA 4BH5IKMDDHEJEOZ7T5LLT4I7EVIH5XCOTX3TPVQB3HY5TUBVT4MYXJOZVA 2000000000000000 microAlgos +``` + +## Interactive Mode + +Some `goal` commands require interactive input from the user. By default, AlgoKit will attempt to run commands in non-interactive mode first, and automatically switch to interactive mode if needed. You can force a command to run in interactive mode by using the `--interactive` flag: + +```bash +$ algokit goal --interactive wallet new algodev +Please choose a password for wallet 'algodev': +Please confirm the password: +Creating wallet... +Created wallet 'algodev' +Your new wallet has a backup phrase that can be used for recovery. +Keeping this backup phrase safe is extremely important. +Would you like to see it now? (Y/n): n +``` + +This is particularly useful when you know a command will require user input, such as creating new accounts, importing keys, or signing transactions. + +For more details about the `AlgoKit goal` command, please refer to the [AlgoKit CLI reference documentation](cli-reference#goal). diff --git a/src/content/docs/reference/algokit-cli/init.md b/src/content/docs/reference/algokit-cli/init.md new file mode 100644 index 00000000..f1e64666 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/init.md @@ -0,0 +1,124 @@ +--- +title: AlgoKit Init +--- + +The `algokit init` [command](cli-reference#init) is used to quickly initialize new projects using official Algorand Templates or community provided templates. It supports a fully guided command line wizard experience, as well as fully scriptable / non-interactive functionality via command options. + +## Quick start + +For a quick start template with all of the defaults you can run: `algokit init` which will interactively guide you through picking the right stack to build your AlgoKit project. Afterwards, you should immediately be able to hit F5 to compile the hello world smart contract to the `smart_contracts/artifacts` folder (with breakpoint debugging - try setting a breakpoint in `smart_contracts/helloworld.py`) and open the `smart_contracts/helloworld.py` file and get linting, automatic formatting and syntax highlighting. + +## Prerequisites + +Git is a prerequisite for the init command as it is used to clone templates and initialize git repos. Please consult the [README](../../README#prerequisites) for installation instructions. + +## Functionality + +As outlined in [quick start](#quick-start), the simplest use of the command is to just run `algokit init` and you will then be guided through selecting a template and configuring options for that template. e.g. + +``` +$ ~ algokit init +? Which of these options best describes the project you want to start? `Smart Contract` | `Dapp Frontend` | `Smart Contract & Dapp Frontend` | `Custom` +? Name of project / directory to create the project in: my-cool-app +``` + +Once above 2 questions are answered, the `cli` will start instantiating the project and will start asking questions specific to the template you are instantiating. By default official templates such as `python`, `fullstack`, `react`, `python` include a notion of a `preset`. If you want to skip all questions and let the tool preset the answers tailored for a starter project you can pick `Starter`, for a more advanced project that includes unit tests, CI automation and other advanced features, pick `Production`. Lastly, if you prefer to modify the experience and tailor the template to your needs, pick the `Custom` preset. + +If you want to accept the default for each option simply hit [enter] or alternatively to speed things up you can run `algokit init --defaults` and they will be auto-accepted. + +### Workspaces vs Standalone Projects + +AlgoKit supports two distinct project structures: Workspaces and Standalone Projects. This flexibility allows developers to choose the most suitable approach for their project's needs. + +To initialize a project within a workspace, use the `--workspace` flag. If a workspace does not already exist, AlgoKit will create one for you by default (unless you disable it via `--no-workspace` flag). Once established, new projects can be added to this workspace, allowing for centralized management. + +To create a standalone project, use the `--no-workspace` flag during initialization. This instructs AlgoKit to bypass the workspace structure and set up the project as an isolated entity. + +For more details on workspaces and standalone projects, refer to the [AlgoKit Project documentation](./project#workspaces-vs-standalone-projects). + +## Bootstrapping + +You will also be prompted if you wish to run the [bootstrap](cli-reference#bootstrap) command, this is useful if you plan to immediately begin developing in the new project. If you passed in `--defaults` or `--bootstrap` then it will automatically run bootstrapping unless you passed in `--no-bootstrap`. + +``` + +? Do you want to run `algokit bootstrap` to bootstrap dependencies for this new project so it can be run immediately? Yes +Installing Python dependencies and setting up Python virtual environment via Poetry +poetry: Creating virtualenv my-smart-contract in /Users/algokit/algokit-init/my-smart-contract/.venv +poetry: Updating dependencies +poetry: Resolving dependencies... +poetry: +poetry: Writing lock file +poetry: +poetry: Package operations: 53 installs, 0 updates, 0 removals +poetry: +poetry: • Installing pycparser (2.21) + +---- other output omitted for brevity ---- + +poetry: • Installing ruff (0.0.171) +Copying /Users/algokit/algokit-init/my-smart-contract/smart_contracts/.env.template to /Users/algokit/algokit-init/my-smart-contract/smart_contracts/.env and prompting for empty values +? Would you like to initialise a git repository and perform an initial commit? Yes +🎉 Performed initial git commit successfully! 🎉 +🙌 Project initialized at `my-smart-contract`! For template specific next steps, consult the documentation of your selected template 🧐 +Your selected template comes from: +➡️ https://github.com/algorandfoundation/algokit-python-template +As a suggestion, if you wanted to open the project in VS Code you could execute: + +> cd my-smart-contract && code . + +``` + +After bootstrapping you are also given the opportunity to initialize a git repo, upon successful completion of the init command the project is ready to be used. If you pass in `--git` it will automatically initialise the git repository and if you pass in `--no-git` it won't. + +> Please note, when using `--no-workspaces`, algokit init will assume a max lookup depth of 1 for a fresh template based project. Otherwise it will assume a max depth of 2, since default algokit workspace structure is at most 2 levels deep. + +## Options + +There are a number of options that can be used to provide answers to the template prompts. Some of the options requiring further explanation are detailed below, but consult the CLI reference for all available [options](cli-reference#init). + +## Community Templates + +As well as the official Algorand templates shown when running the init command, community templates can also be provided by providing a URL via the prompt or the `--template-url` option. + +e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-python-template` (that being the url of the official python template, the same as `algokit init -t python`). + +The `--template-url` option can be combined with `--template-url-ref` to specify a specific commit, branch or tag + +e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-python-template --template-url-ref 0232bb68a2f5628e910ee52f62bf13ded93fe672` + +If the URL is not an official template there is a potential security risk and so to continue you must either acknowledge this prompt, or if you are in a non-interactive environment you can pass the `--UNSAFE-SECURITY-accept-template-url` option (but we generally don't recommend this option so users can review the warning message first) e.g. + +``` + +Community templates have not been reviewed, and can execute arbitrary code. +Please inspect the template repository, and pay particular attention to the values of \_tasks, \_migrations and \_jinja_extensions in copier.yml +? Continue anyway? Yes + +``` + +If you want to create a community template, you can use the [AlgoKit guidelines on template building](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/tutorials/algokit-template#creating-algokit-templates) and [Copier documentation](https://copier.readthedocs.io/en/stable/) as a starting point. + +## Template Answers + +Answers to specific template prompts can be provided with the `--answer {key} {value}` option, which can be used multiple times for each prompt. Quotes can be used for values with spaces e.g. `--answer author_name "Algorand Foundation"`. + +To find out the key for a specific answer you can either look at `.algokit/.copier-answers.yml` in the root folder of a project created via `algokit init` or in the `copier.yaml` file of a template repo e.g. for the [python template](https://github.com/algorandfoundation/algokit-python-template/blob/main/copier.yaml). + +## Non-interactive project initialization + +By combining a number of options, it is possible to initialize a new project without any interaction. For example, to create a project named `my-smart-contract` using the `python` template with no git, no bootstrapping, the author name of `Algorand Foundation`, and defaults for all other values, you could execute the following: + +``` + +$ ~ algokit init -n my-smart-contract -t python --no-git --no-bootstrap --answer author_name "Algorand Foundation" --defaults +🙌 Project initialized at `my-smart-contract`! For template specific next steps, consult the documentation of your selected template 🧐 +Your selected template comes from: +➡️ https://github.com/algorandfoundation/algokit-python-template +As a suggestion, if you wanted to open the project in VS Code you could execute: + +> cd my-smart-contract && code . + +``` + +For more details about the `AlgoKit init` command, please refer to the [AlgoKit CLI reference documentation](cli-reference#init). diff --git a/src/content/docs/reference/algokit-cli/localnet.md b/src/content/docs/reference/algokit-cli/localnet.md new file mode 100644 index 00000000..23086625 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/localnet.md @@ -0,0 +1,191 @@ +--- +title: AlgoKit LocalNet +--- + +The AlgoKit LocalNet feature allows you to manage (start, stop, reset, manage) a locally sandboxed private Algorand network. This allows you to interact and deploy changes against your own Algorand network without needing to worry about funding TestNet accounts, information you submit being publicly visible or being connected to an active Internet connection (once the network has been started). + +AlgoKit LocalNet uses Docker images that are optimised for a great dev experience. This means the Docker images are small and start fast. It also means that features suited to developers are enabled such as KMD (so you can programmatically get faucet private keys). + +The philosophy we take with AlgoKit LocalNet is that you should treat it as an ephemeral network. This means assume it could be reset at any time - don't store data on there that you can't recover / recreate. We have optimised the AlgoKit LocalNet experience to minimise situations where the network will get reset to improve the experience, but it can and will still happen in a number of situations. + +## Prerequisites + +AlgoKit LocalNet relies on Docker and Docker Compose being present and running on your system. Alternatively, you can use Podman as a replacement for Docker see [Podman support](#podman-support). + +You can install Docker by following the [official installation instructions](https://docs.docker.com/get-docker/). Most of the time this will also install Docker Compose, but if not you can [follow the instructions](https://docs.docker.com/compose/install/) for that too. + +If you are on Windows then you will need WSL 2 installed first, for which you can find the [official installation instructions](https://learn.microsoft.com/en-us/windows/wsl/install). If you are using Windows 10 then ensure you are on the latest version to reduce likelihood of installation problems. + +Alternatively, the Windows 10/11 Pro+ supported [Hyper-V backend](https://docs.docker.com/desktop/install/windows-install/) for Docker can be used instead of the WSL 2 backend. + +### Podman support + +If you prefer to use [Podman](https://podman.io/) as your container engine, make sure to install and configure Podman first. Then you can set the default container engine that AlgoKit will use, by running: `algokit config container-engine podman`. See [Container-based LocalNet](#container-based-localnet) for more details. + +## Known issues + +The AlgoKit LocalNet is built with 30,000 participation keys generated and after 30,000 rounds is reached it will no longer be able to add rounds. At this point you can simply reset the LocalNet to continue development. Participation keys are slow to generate hence why they are pre-generated to improve experience. + +## Supported operating environments + +We rely on the official Algorand docker images for Indexer, Conduit and Algod, which means that AlgoKit LocalNet is supported on Windows, Linux and Mac on Intel and AMD chipsets (including Apple Silicon). + +## Container-based LocalNet + +AlgoKit cli supports both [Docker](https://www.docker.com/) and [Podman](https://podman.io/) as container engines. While `docker` is used by default, executing the below: + +``` +algokit config container-engine +# or +algokit config container-engine podman|docker +``` + +Will set the default container engine to use when executing `localnet` related commands via `subprocess`. + +### Creating / Starting the LocalNet + +To create / start your AlgoKit LocalNet instance you can run `algokit localnet start`. This will: + +- Detect if you have Docker and Docker Compose installed +- Detect if you have the Docker engine running +- Create a new Docker Compose deployment for AlgoKit LocalNet if it doesn't already exist +- (Re-)Start the containers + +You can also specify additional options: + +- `--name`: Specify a name for a custom LocalNet instance. This allows you to have multiple LocalNet configurations. Refer to [Named LocalNet Configuration Directory](#named-localnet-configuration-directory) for more details. +- `--config-dir`: Specify a custom configuration directory for the LocalNet. +- `--dev/--no-dev`: Control whether to launch 'algod' in developer mode or not. Defaults to 'yes' (developer mode enabled). + +If it's the first time running it on your machine then it will download the following images from DockerHub: + +- [`algorand/algod`](https://hub.docker.com/r/algorand/algod) (~500 MB) +- [`algorand/indexer`](https://hub.docker.com/r/algorand/indexer) (~96 MB) +- [`algorand/conduit`](https://hub.docker.com/r/algorand/conduit) (~98 MB) +- [`postgres:13-alpine`](https://hub.docker.com/_/postgres) (~80 MB) + +Once they have downloaded, it won't try and re-download images unless you perform a `algokit localnet reset`. + +Once the LocalNet has started, the following endpoints will be available: + +- [algod](https://developer.algorand.org/docs/rest-apis/algod/v2/): + - address: + - token: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` +- [kmd](https://developer.algorand.org/docs/rest-apis/kmd/): + - address: + - token: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` +- [indexer](https://developer.algorand.org/docs/rest-apis/indexer/): + - address: +- tealdbg port: + - address: + +### Creating / Starting a Named LocalNet + +AlgoKit manages the default LocalNet environment and automatically keeps the configuration updated with any upstream changes. As a result, configuration changes are reset automatically by AlgoKit, so that developers always have access to a known good LocalNet configuration. This works well for the majority of scenarios, however sometimes developers need the control to make specific configuration changes for specific scenarios. + +When you want more control, named LocalNet instances can be used by running `algokit localnet start --name {name}`. This command will set up and run a named LocalNet environment (based off the default), however AlgoKit will not update the environment or configuration automatically. From here developers are able to modify their named environment in any way they like, for example setting `DevMode: false` in `algod_network_template.json`. + +Once you have a named LocalNet running, the AlgoKit LocalNet commands will target this instance. +If at any point you'd like to switch back to the default LocalNet, simply run `algokit localnet start`. + +### Specifying a custom LocalNet configuration directory + +You can specify a custom LocalNet configuration directory by using the `--config-dir` option or by setting the `ALGOKIT_LOCALNET_CONFIG_DIR` environment variable. This allows you to have multiple LocalNet instances with different configurations in different directories, which is useful in 'CI/CD' scenarios where you can save your custom localnet in your version control and then run `algokit localnet start --config-dir /path/to/custom/config` to use it within your pipeline. + +For example, to create a LocalNet instance with a custom configuration directory, you can run: + +``` +algokit localnet start --config-dir /path/to/custom/config +``` + +### Named LocalNet Configuration Directory + +When running `algokit localnet start --name {name}`, AlgoKit stores configuration files in a specific directory on your system. The location of this directory depends on your operating system: + +- **Windows**: We use the value of the `APPDATA` environment variable to determine the directory to store the configuration files. This is usually `C:\Users\USERNAME\AppData\Roaming`. +- **Linux or Mac**: We use the value of the `XDG_CONFIG_HOME` environment variable to determine the directory to store the configuration files. If `XDG_CONFIG_HOME` is not set, the default location is `~/.config`. + +Assuming you have previously used a default LocalNet, the path `./algokit/sandbox/` will exist inside the configuration directory, containing the configuration settings for the default LocalNet instance. Additionally, for each named LocalNet instance you have created, the path `./algokit/sandbox_{name}/` will exist, containing the configuration settings for the respective named LocalNet instances. + +It is important to note that only the configuration files for a named LocalNet instance should be changed. Any changes made to the default LocalNet instance will be reverted by AlgoKit. + +You can use `--name` flag along with `--config-dir` option to specify a custom path for the LocalNet configuration directory. This allows you to manage multiple LocalNet instances with different configurations in different directories on your system. + +### Controlling Algod Developer Mode + +By default, AlgoKit LocalNet starts algod in developer mode. This mode enables certain features that are useful for development but may not reflect the behavior of a production network. You can control this setting using the `--dev/--no-dev` flag when starting the LocalNet: + +```bash +algokit localnet start --no-dev # Starts algod without developer mode +algokit localnet start --dev # Starts algod with developer mode (default) +``` + +If you change this setting for an existing LocalNet instance, AlgoKit will prompt you to restart the LocalNet to apply the changes. + +### Stopping and Resetting the LocalNet + +To stop the LocalNet you can execute `algokit localnet stop`. This will turn off the containers, but keep them ready to be started again in the same state by executing `algokit localnet start`. + +To reset the LocalNet you can execute `algokit localnet reset`, which will tear down the existing containers, refresh the container definition from the latest stored within AlgoKit and update to the latest Docker images. If you want to keep the same container spec and versions as you currently have, but quickly tear down and start a new instance then run `algokit localnet reset --no-update`. + +### Viewing transactions in the LocalNet + +You can see a web-based user interface of the current state of your LocalNet including all transactions by using the [AlgoKit Explore](./explore) feature, e.g. by executing `algokit localnet explore`. + +### Executing goal commands against AlgoKit LocalNet + +See the [AlgoKit Goal](./goal) feature. You can also execute `algokit localnet console` to open a [Bash shell which allows you to run the goal commandline](./goal#running-multiple-commands). + +Note: if you want to copy files into the container so you can access them via goal then you can use the following: + +``` +docker cp foo.txt algokit_algod:/root +``` + +### Getting access to the private key of the faucet account + +If you want to use the LocalNet then you need to get the private key of the initial wallet so you can transfer ALGOs out of it to other accounts you create. + +There are two ways to do this: + +**Option 1: Manually via goal** + +``` +algokit goal account list +algokit goal account export -a {address_from_an_online_account_from_above_command_output} +``` + +**Option 2: Automatically via kmd API** + +Needing to do this manual step every time you spin up a new development environment or reset your LocalNet is frustrating. Instead, it's useful to have code that uses the Sandbox APIs to automatically retrieve the private key of the default account. + +AlgoKit Utils provides methods to help you do this: + +- TypeScript - [`ensureFunded`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer#ensurefunded) and [`getDispenserAccount`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer#dispenser) +- Python - [`ensure_funded`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.ensure_funded) and [`get_dispenser_account`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.get_dispenser_account) + +For more details about the `AlgoKit localnet` command, please refer to the [AlgoKit CLI reference documentation](cli-reference#localnet). + +## GitHub Codespaces-based LocalNet + +The AlgoKit LocalNet feature also supports running the LocalNet in a GitHub Codespace with port forwarding by utilizing the [GitHub CLI](https://github.com/cli/gh). This allows you to run the LocalNet without the need to use Docker. This is especially useful for scenarios where certain hardware or software limitations may prevent you from being able to run Docker. + +To run the LocalNet in a GitHub Codespace, you can use the `algokit localnet codespace` command. +By default without `--force` flag it will prompt you to delete stale codespaces created earlier (if any). Upon termination it will also prompt to delete the codespace that was used prior to termination. + +Running an interactive session ensures that you have control over the lifecycle of your Codespace, preventing unnecessary usage and potential costs. GitHub Codespaces offers a free tier with certain limits, which you can review in the [GitHub Codespaces documentation](https://docs.github.com/en/codespaces/overview#pricing). + +### Options + +- `-m`, `--machine`: Specifies the GitHub Codespace machine type to use. Defaults to `basicLinux32gb`. Available options are `basicLinux32gb`, `standardLinux32gb`, `premiumLinux`, and `largePremiumLinux`. Refer to [GitHub Codespaces documentation](https://docs.github.com/en/codespaces/overview/machine-types) for more details. +- `-a`, `--algod-port`: Sets the port for the Algorand daemon. Defaults to `4001`. +- `-i`, `--indexer-port`: Sets the port for the Algorand indexer. Defaults to `8980`. +- `-k`, `--kmd-port`: Sets the port for the Algorand kmd. Defaults to `4002`. +- `-n`, `--codespace-name`: Specifies the name of the codespace. Defaults to a random name with a timestamp. +- `-t`, `--timeout`: Max duration for running the port forwarding process. Defaults to 1 hour. This timeout ensures the codespace **will automatically shut down** after the specified duration to prevent accidental overspending of free quota on GitHub Codespaces. [More details](https://docs.github.com/en/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). +- `-r`, `--repo-url`: The URL of the repository to use. Defaults to the AlgoKit base template repository (`algorandfoundation/algokit-base-template`). The reason why algokit-base-template is used by default is due to [.devcontainer.json](https://github.com/algorandfoundation/algokit-base-template/blob/main/template_content/.devcontainer.json) which defines the scripts that take care of setting up AlgoKit CLI during container start. You can use any custom repo as a base, however it's important to ensure the reference [.devcontainer.json](https://github.com/algorandfoundation/algokit-base-template/blob/main/template_content/.devcontainer.json) file exists in your repository **otherwise there will be no ports to forward from the codespace**. +- `--force`, `-f`: Force deletes stale codespaces and skips confirmation prompts. Defaults to explicitly prompting for confirmation. + +For more details about managing LocalNet in GitHub Codespaces, please refer to the [AlgoKit CLI reference documentation](cli-reference#codespace). + +> Tip: By specifying alternative port values it is possible to have several LocalNet instances running where one is using default ports via `algokit localnet start` with Docker | Podman and the other relies on port forwarding via `algokit localnet codespace`. diff --git a/src/content/docs/reference/algokit-cli/node-ops.mdx b/src/content/docs/reference/algokit-cli/node-ops.mdx deleted file mode 100644 index b81126e0..00000000 --- a/src/content/docs/reference/algokit-cli/node-ops.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Node Operations ---- diff --git a/src/content/docs/reference/algokit-cli/overview.md b/src/content/docs/reference/algokit-cli/overview.md new file mode 100644 index 00000000..13ea42d3 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/overview.md @@ -0,0 +1,54 @@ +--- +title: AlgoKit +--- + +The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the Algorand network. The goal of AlgoKit is to help developers build and launch secure, automated production-ready applications rapidly. + +## AlgoKit CLI commands + +For details on how to use individual features see the following + +- [Bootstrap](./project/bootstrap) - Bootstrap AlgoKit project dependencies +- [Compile](./compile) - Compile Algorand Python code +- [Completions](./completions) - Install shell completions for AlgoKit +- [Deploy](./project/deploy) - Deploy your smart contracts effortlessly to various networks +- [Dispenser](./dispenser) - Fund your TestNet account with ALGOs from the AlgoKit TestNet Dispenser +- [Doctor](./doctor) - Check AlgoKit installation and dependencies +- [Explore](./explore) - Explore Algorand Blockchains using lora +- [Generate](./generate) - Generate code for an Algorand project +- [Goal](./goal) - Run the Algorand goal CLI against the AlgoKit Sandbox +- [Init](./init) - Quickly initialize new projects using official Algorand Templates or community provided templates +- [LocalNet](./localnet) - Manage a locally sandboxed private Algorand network +- [Project](./project) - Manage an AlgoKit project workspace on your file system +- [Tasks](./tasks) - Perform a variety of useful operations on the Algorand blockchain + +## Common AlgoKit CLI options + +AlgoKit has a number of global options that can impact all commands. Note: these global options must be appended to `algokit` and appear before a command, e.g. `algokit -v localnet start`, but not `algokit localnet start -v`. The exception to this is `-h`, which can be appended to any command or sub-command to see contextual help information. + +- `-h, --help` The help option can be used on any command to get details on any command, its sub-commands and options. +- `-v, --verbose` Enables DEBUG logging, useful when troubleshooting or if you want to peek under the covers and learn what AlgoKit CLI is doing. +- `--color / --no-color` Enables or disables output of console styling, we also support the [NO_COLOR](https://no-color.org) environment variable. +- `--skip-version-check` Skips updated AlgoKit version checking and prompting for that execution, this can also be disabled [permanently on a given machine](cli-reference#version-prompt) with `algokit config version-prompt disable`. + +See also the [AlgoKit CLI Reference](cli-reference), which details every command, sub-command and option. + +## AlgoKit Tutorials + +The following tutorials guide you through various scenarios: + +- [AlgoKit quick start](./tutorials/intro) +- [Creating AlgoKit templates](./tutorials/algokit-template) + +## Guiding Principles + +AlgoKit is guided by the following solution principles which flow through to the applications created by developers. + +1. **Cohesive developer tool suite**: Using AlgoKit should feel professional and cohesive, like it was designed to work together, for the developer; not against them. Developers are guided towards delivering end-to-end, high quality outcomes on MainNet so they and Algorand are more likely to be successful. +2. **Seamless onramp**: New developers have a seamless experience to get started and they are guided into a pit of success with best practices, supported by great training collateral; you should be able to go from nothing to debugging code in 5 minutes. +3. **Leverage existing ecosystem**: AlgoKit functionality gets into the hands of Algorand developers quickly by building on top of the existing ecosystem wherever possible and aligned to these principles. +4. **Sustainable**: AlgoKit should be built in a flexible fashion with long-term maintenance in mind. Updates to latest patches in dependencies, Algorand protocol development updates, and community contributions and feedback will all feed in to the evolution of the software. +5. **Secure by default**: Include defaults, patterns and tooling that help developers write secure code and reduce the likelihood of security incidents in the Algorand ecosystem. This solution should help Algorand be the most secure Blockchain ecosystem. +6. **Extensible**: Be extensible for community contribution rather than stifling innovation, bottle-necking all changes through the Algorand Foundation and preventing the opportunity for other ecosystems being represented (e.g. Go, Rust, etc.). This helps make developers feel welcome and is part of the developer experience, plus it makes it easier to add features sustainably. +7. **Meet developers where they are**: Make Blockchain development mainstream by giving all developers an idiomatic development experience in the operating system, IDE and language they are comfortable with so they can dive in quickly and have less they need to learn before being productive. +8. **Modular components**: Solution components should be modular and loosely coupled to facilitate efficient parallel development by small, effective teams, reduced architectural complexity and allowing developers to pick and choose the specific tools and capabilities they want to use based on their needs and what they are comfortable with. diff --git a/src/content/docs/reference/algokit-cli/overview.mdx b/src/content/docs/reference/algokit-cli/overview.mdx deleted file mode 100644 index 8c44e093..00000000 --- a/src/content/docs/reference/algokit-cli/overview.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: AlgoKit CLI ---- diff --git a/src/content/docs/reference/algokit-cli/project-tools.mdx b/src/content/docs/reference/algokit-cli/project-tools.mdx deleted file mode 100644 index c62b71fb..00000000 --- a/src/content/docs/reference/algokit-cli/project-tools.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Project Tools ---- diff --git a/src/content/docs/reference/algokit-cli/project.md b/src/content/docs/reference/algokit-cli/project.md new file mode 100644 index 00000000..8f9c27ad --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project.md @@ -0,0 +1,97 @@ +--- +title: AlgoKit Project +--- + +`algokit project` is a collection of commands and command groups useful for managing algokit compliant [project workspaces](./init#workspaces). + +## Overview + +The `algokit project` command group is designed to simplify the management of AlgoKit projects. It provides a suite of tools to initialize, deploy, link, list, and run various components within a project workspace. This command group ensures that developers can efficiently handle the lifecycle of their projects, from bootstrapping to deployment and beyond. + +### What is a Project? + +In the context of AlgoKit, a "project" refers to a structured standalone or monorepo workspace that includes all the necessary components for developing, testing, and deploying Algorand applications. This may include smart contracts, frontend applications, and any associated configurations. In the context of the CLI, the `algokit project` commands help manage these components cohesively. + +The orchestration between workspaces, standalone projects, and custom commands is designed to provide a seamless development experience. Below is a high-level overview of how these components interact within the AlgoKit ecosystem. + +```mermaid +graph TD; +A[`algokit project` command group] --> B["Workspace (.algokit.toml)"]; +A --> C["Standalone Project (.algokit.toml)"]; +B --> D["Sub-Project 1 (.algokit.toml)"]; +B --> E["Sub-Project 2 (.algokit.toml)"]; +C --> F["Custom Commands defined in .algokit.toml"]; +D --> F; +E --> F; +``` + +- **AlgoKit Project**: The root command that encompasses all project-related functionalities. +- **Workspace**: A root folder that is managing multiple related sub-projects. +- **Standalone Project**: An isolated project structure for simpler applications. +- **Custom Commands**: Commands defined by the user in the `.algokit.toml` and automatically injected into the `algokit project run` command group. + +### Workspaces vs Standalone Projects + +As mentioned, AlgoKit supports two distinct project structures: Workspaces and Standalone Projects. This flexibility allows developers to choose the most suitable approach for their project's needs. + +### Workspaces + +Workspaces are designed for managing multiple related projects under a single root directory. This approach is beneficial for complex applications that consist of multiple sub-projects, such as a smart contract and a corresponding frontend application. Workspaces help in organizing these sub-projects in a structured manner, making it easier to manage dependencies and shared configurations. + +To initialize a project within a workspace, use the `--workspace` flag. If a workspace does not already exist, AlgoKit will create one for you by default (unless you disable it via `--no-workspace` flag). Once established, new projects can be added to this workspace, allowing for centralized management. + +To mark your project as `workspace` fill in the following in your `.algokit.toml` file: + +```toml +[project] +type = 'workspace' # type specifying if the project is a workspace or standalone +projects_root_path = 'projects' # path to the root folder containing all sub-projects in the workspace +``` + +#### VSCode optimizations + +AlgoKit has a set of minor optimizations for VSCode users that are useful to be aware of: + +- Templates created with the `--workspace` flag automatically include a VSCode code-workspace file. New projects added to an AlgoKit workspace are also integrated into an existing VSCode workspace. +- Using the `--ide` flag with `init` triggers automatic prompts to open the project and, if available, the code workspace in VSCode. + +#### Handling of the `.github` Folder + +A key aspect of using the `--workspace` flag is how the `.github` folder is managed. This folder, which contains GitHub-specific configurations such as workflows and issue templates, is moved from the project directory to the root of the workspace. This move is necessary because GitHub does not recognize workflows located in subdirectories. + +Here's a simplified overview of what happens: + +1. If a `.github` folder is found in your project, its contents are transferred to the workspace's root `.github` folder. +2. Files with matching names in the destination are not overwritten; they're skipped. +3. The original `.github` folder is removed if it's left empty after the move. +4. A notification is displayed, advising you to review the moved `.github` contents to ensure everything is in order. + +This process ensures that your GitHub configurations are properly recognized at the workspace level, allowing you to utilize GitHub Actions and other features seamlessly across your projects. + +### Standalone Projects + +Standalone projects are suitable for simpler applications or when working on a single component. This structure is straightforward, with each project residing in its own directory, independent of others. Standalone projects are ideal for developers who prefer simplicity or are focusing on a single aspect of their application and are sure that they will not need to add more sub-projects in the future. + +To create a standalone project, use the `--no-workspace` flag during initialization. This instructs AlgoKit to bypass the workspace structure and set up the project as an isolated entity. + +Both workspaces and standalone projects are fully supported by AlgoKit's suite of tools, ensuring developers can choose the structure that best fits their workflow without compromising on functionality. + +To mark your project as a standalone project fill in the following in your `.algokit.toml` file: + +```toml +[project] +type = {'backend' | 'contract' | 'frontend'} # currently support 3 generic categories for standalone projects +name = 'my-project' # unique name for the project inside workspace +``` + +> We recommend using workspaces for most projects (hence enabled by default), as it provides a more organized and scalable approach to managing multiple sub-projects. However, standalone projects are a great choice for simple applications or when you are certain that you will not need to add more sub-projects in the future, for such cases simply append `--no-workspace` when using `algokit init` command. For more details on init command please refer to [init](./init) command docs. + +## Features + +Dive into the features of the `algokit project` command group: + +- [bootstrap](./project/bootstrap) - Bootstrap your project with AlgoKit. +- [deploy](./project/deploy) - Deploy your smart contracts effortlessly to various networks. +- [link](./project/link) - Powerful feature designed to streamline the integration between `frontend` and `contract` projects +- [list](./project/list) - Enumerate all projects within an AlgoKit workspace. +- [run](./project/run) - Define custom commands and manage their execution via `algokit` cli. diff --git a/src/content/docs/reference/algokit-cli/project/bootstrap.md b/src/content/docs/reference/algokit-cli/project/bootstrap.md new file mode 100644 index 00000000..3113971f --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/bootstrap.md @@ -0,0 +1,130 @@ +--- +title: AlgoKit Project Bootstrap +--- + +The AlgoKit Project Bootstrap feature allows you to bootstrap different project dependencies by looking up specific files in your current directory and immediate sub directories by convention. + +This is useful to allow for expedited initial setup for each developer e.g. when they clone a repository for the first time. It's also useful to provide a quick getting started experience when initialising a new project via [AlgoKit Init](./init) and meeting our goal of "nothing to debugging code in 5 minutes". + +It can bootstrap one or all of the following (with other options potentially being added in the future): + +- Python Poetry projects - Installs Poetry via pipx if its not present and then runs `poetry install` +- Node.js project - Checks if npm is installed and runs `npm install` +- dotenv (.env) file - Checks for `.env.template` files, copies them to `.env` (which should be in `.gitignore` so developers can safely make local specific changes) and prompts for any blank values (so the developer has an easy chance to fill in their initial values where there isn't a clear default). + +> **Note**: Invoking bootstrap from `algokit bootstrap` is not recommended. Please prefer using `algokit project bootstrap` instead. + +## Usage + +Available commands and possible usage as follows: + +``` +$ ~ algokit project bootstrap +Usage: algokit project bootstrap [OPTIONS] COMMAND [ARGS]... + +Options: + -h, --help Show this message and exit. + +Commands: + all Bootstrap all aspects of the current directory and immediate sub directories by convention. + env Bootstrap .env file in the current working directory. + npm Bootstrap Node.js project in the current working directory. + poetry Bootstrap Python Poetry and install in the current working directory. +``` + +## Functionality + +### Bootstrap .env file + +The command `algokit project bootstrap env` runs two main tasks in the current directory: + +- Searching for `.env.template` file in the current directory and use it as template to create a new `.env` file in the same directory. +- Prompting the user to enter a value for any empty token values in the `env.` including printing the comments above that empty token + +For instance, a sample `.env.template` file as follows: + +``` +SERVER_URL=https://myserver.com +# This is a mandatory field to run the server, please enter a value +# For example: 5000 +SERVER_PORT= +``` + +Running the `algokit project bootstrap env` command while the above `.env.template` file in the current directory will result in the following: + +``` +$ ~ algokit project bootstrap env +Copying /Users/me/my-project/.env.template to /Users/me/my-project/.env and prompting for empty values +# This is a mandatory field to run the server, please enter a value value +# For example: 5000 + +? Please provide a value for SERVER_PORT: +``` + +And when the user enters a value for `SERVER_PORT`, a new `.env` file will be created as follows (e.g. if they entered `4000` as the value): + +``` +SERVER_URL=https://myserver.com +# This is a mandatory field to run the server, please enter a value +# For example: 5000 +SERVER_PORT=4000 +``` + +### Bootstrap Node.js project + +The command `algokit project bootstrap npm` installs Node.js project dependencies if there is a `package.json` file in the current directory by running `npm install` command to install all node modules specified in that file. However, when running in CI mode **with** present `package-lock.json` file (either by setting the `CI` environment variable or using the `--ci` flag), it will run `npm ci` instead, which provides a cleaner and more deterministic installation. If `package-lock.json` is missing, it will show a clear error message and resolution instructions. If you don't have `npm` available it will show a clear error message and resolution instructions. + +Here is an example outcome of running `algokit project bootstrap npm` command: + +``` +$ ~ algokit project bootstrap npm +Installing npm dependencies +npm: +npm: added 17 packages, and audited 18 packages in 3s +npm: +npm: 2 packages are looking for funding +npm: run `npm fund` for details +npm: +npm: found 0 vulnerabilities +``` + +### Bootstrap Python poetry project + +The command `algokit project bootstrap poetry` does two main actions: + +- Checking for Poetry version by running `poetry --version` and upgrades it if required +- Installing Python dependencies and setting up Python virtual environment via Poetry in the current directory by running `poetry install`. + +Here is an example of running `algokit project bootstrap poetry` command: + +``` +$ ~ algokit project bootstrap poetry +Installing Python dependencies and setting up Python virtual environment via Poetry +poetry: +poetry: Installing dependencies from lock file +poetry: +poetry: Package operations: 1 installs, 1 update, 0 removals +poetry: +poetry: • Installing pytz (2022.7) +poetry: • Updating copier (7.0.1 -> 7.1.0a0) +poetry: +poetry: Installing the current project: algokit (0.1.0) +``` + +### Bootstrap all + +Execute `algokit project bootstrap all` to initiate `algokit project bootstrap env`, `algokit project bootstrap npm`, and `algokit project bootstrap poetry` commands within the current directory and all its immediate sub-directories. This comprehensive command is automatically triggered following the initialization of a new project through the [AlgoKit Init](./init) command. + +#### Filtering Options + +The `algokit project bootstrap all` command includes flags for more granular control over the bootstrapping process within [AlgoKit workspaces](../init#workspaces): + +- `--project-name`: This flag allows you to specify one or more project names to bootstrap. Only projects matching the provided names will be bootstrapped. This is particularly useful in monorepos or when working with multiple projects in the same directory structure. + +- `--type`: Use this flag to limit the bootstrapping process to projects of a specific type (e.g., `frontend`, `backend`, `contract`). This option streamlines the setup process by focusing on relevant project types, reducing the overall bootstrapping time. + +These new flags enhance the flexibility and efficiency of the bootstrapping process, enabling developers to tailor the setup according to project-specific needs. + +## Further Reading + +To learn more about the `algokit project bootstrap` command, please refer to [bootstrap](../cli-reference#bootstrap) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/project/deploy.md b/src/content/docs/reference/algokit-cli/project/deploy.md new file mode 100644 index 00000000..e606aa05 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/deploy.md @@ -0,0 +1,213 @@ +--- +title: AlgoKit Project Deploy +--- + +Deploy your smart contracts effortlessly to various networks with the algokit project deploy feature. This feature is essential for automation in CI/CD pipelines and for seamless deployment to various Algorand network environments. + +> **Note**: Invoking deploy from `algokit deploy` is not recommended. Please prefer using `algokit project deploy` instead. + +## Usage + +```sh +$ algokit project deploy [OPTIONS] [ENVIRONMENT_NAME] [EXTRA_ARGS] +``` + +This command deploys smart contracts from an AlgoKit compliant repository to the specified network. + +### Options + +- `--command, -C TEXT`: Specifies a custom deploy command. If this option is not provided, the deploy command will be loaded from the `.algokit.toml` file. +- `--interactive / --non-interactive, --ci`: Enables or disables the interactive prompt for mnemonics. When the CI environment variable is set, it defaults to non-interactive. +- `--path, -P DIRECTORY`: Specifies the project directory. If not provided, the current working directory will be used. +- `--deployer`: Specifies the deployer alias. If not provided and if the deployer is specified in `.algokit.toml` file its mnemonic will be prompted. +- `--dispenser`: Specifies the dispenser alias. If not provided and if the dispenser is specified in `.algokit.toml` file its mnemonic will be prompted. +- `-p, --project-name`: (Optional) Projects to execute the command on. Defaults to all projects found in + the current directory. Option is mutually exclusive with `--command`. +- `-h, --help`: Show this message and exit. +- `[EXTRA_ARGS]...`: Additional arguments to pass to the deploy command. For instance, `algokit project deploy -- {custom args}`. This will ensure that the extra arguments are passed to the deploy command specified in the `.algokit.toml` file or directly via `--command` option. + +## Environment files + +AlgoKit `deploy` employs both a general and network-specific environment file strategy. This allows you to set environment variables that are applicable across all networks and others that are specific to a given network. + +The general environment file (`.env`) should be placed at the root of your project. This file will be used to load environment variables that are common across deployments to all networks. + +For each network you're deploying to, you can optionally have a corresponding `.env.[network_name]` file. This file should contain environment variables specific to that network. Network-specific environment variables take precedence over general environment variables. + +The directory layout would look like this: + +```md +. +├── ... (your project files and directories) +├── .algokit.toml # Configuration file for AlgoKit +├── .env # (OPTIONAL) General environment variables common across all deployments +└── .env.[{mainnet|testnet|localnet|betanet|custom}] # (OPTIONAL) Environment variables specific to deployments to a network +``` + +> ⚠️ Please note that creating `.env` and `.env.[network_name]` files is only necessary if you're deploying to a custom network or if you want to override the default network configurations provided by AlgoKit. AlgoKit comes with predefined configurations for popular networks like `TestNet`, `MainNet`, `BetaNet`, or AlgoKit's `LocalNet`. + +The logic for loading environment variables is as follows: + +- If a `.env` file exists, the environment variables contained in it are loaded first. +- If a `.env.[network_name]` file exists, the environment variables in it are loaded, overriding any previously loaded values from the `.env` file for the same variables. + +### Default Network Configurations + +The `deploy` command assumes default configurations for `mainnet`, `localnet`, and `testnet` environments. If you're deploying to one of these networks and haven't provided specific environment variables, AlgoKit will use these default values: + +- **Localnet**: + + - `ALGOD_TOKEN`: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + - `ALGOD_SERVER`: "http://localhost" + - `ALGOD_PORT`: "4001" + - `INDEXER_TOKEN`: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + - `INDEXER_SERVER`: "http://localhost" + - `INDEXER_PORT`: "8980" + +- **Mainnet**: + + - `ALGOD_SERVER`: "https://mainnet-api.algonode.cloud" + - `INDEXER_SERVER`: "https://mainnet-idx.algonode.cloud" + +- **Testnet**: + - `ALGOD_SERVER`: "https://testnet-api.algonode.cloud" + - `INDEXER_SERVER`: "https://testnet-idx.algonode.cloud" + +These default values are used when no specific `.env.[network_name]` file is present and the corresponding environment variables are not set. This feature simplifies the deployment process for these common networks, reducing the need for manual configuration in many cases. + +If you need to override these defaults or add additional configuration for these networks, you can still do so by creating the appropriate `.env.[network_name]` file or setting the environment variables explicitly or via generic `.env` file. + +## AlgoKit Configuration File + +AlgoKit uses a configuration file called `.algokit.toml` in the root of your project. The configuration file can be created using the `algokit init` command. This file will define the deployment commands for the various network environments that you want to target. + +Here's an example of what the `.algokit.toml` file might look like. When deploying it will prompt for the `DEPLOYER_MNEMONIC` secret unless it is already defined as an environment variable or is deploying to localnet. + +```toml +[algokit] +min_version = "v{latest_version}" + +[project] + +... # project configuration and custom commands + +[project.deploy] +command = "poetry run python -m smart_contracts deploy" +environment_secrets = [ + "DEPLOYER_MNEMONIC", +] + +[project.deploy.localnet] +environment_secrets = [] +``` + +The `command` key under each `[project.deploy.{network_name}]` section should contain a string that represents the deployment command for that particular network. If a `command` key is not provided in a network-specific section, the command from the general `[project.deploy]` section will be used. + +The `environment_secrets` key should contain a list of names of environment variables that should be treated as secrets. This can be defined in the general `[project.deploy]` section, as well as in the network-specific sections. The environment-specific secrets will be added to the general secrets during deployment. + +The `[algokit]` section with the `min_version` key allows you to specify the minimum version of AlgoKit that the project requires. + +This way, you can define common deployment logic and environment secrets in the `[project.deploy]` section, and provide overrides or additions for specific environments in the `[project.deploy.{environment_name}]` sections. + +## Deploying to a Specific Network + +The command requires a `ENVIRONMENT` argument, which specifies the network environment to which the smart contracts will be deployed. Please note, the `environment` argument is case-sensitive. + +Example: + +```sh +$ algokit project deploy testnet +``` + +This command deploys the smart contracts to the testnet. + +## Deploying to a Specific Network from a workspace with project name filter + +The command requires a `ENVIRONMENT` argument, which specifies the network environment to which the smart contracts will be deployed. Please note, the `environment` argument is case-sensitive. + +Example: + +Root `.algokit.toml`: + +```toml +[project] +type = "workspace" +projects_root_dir = 'projects' +``` + +Contract project `.algokit.toml`: + +```toml +[project] +type = "contract" +name = "myproject" + +[project.deploy] +command = "{custom_deploy_command}" +``` + +```bash +$ algokit project deploy testnet --project-name myproject +``` + +This command deploys the smart contracts to TestNet from a sub project named 'myproject', which is available within the current workspace. All `.env` loading logic described in [Environment files](#environment-files) is applicable, execution from the workspace root orchestrates invoking the deploy command from the working directory of each applicable sub project. + +## Custom Project Directory + +By default, the deploy command looks for the `.algokit.toml` file in the current working directory. You can specify a custom project directory using the `--project-dir` option. + +Example: + +```sh +$ algokit project deploy testnet --project-dir="path/to/project" +``` + +## Custom Deploy Command + +You can provide a custom deploy command using the `--custom-deploy-command` option. If this option is not provided, the deploy command will be loaded from the `.algokit.toml` file. + +Example: + +```sh +$ algokit project deploy testnet --custom-deploy-command="your-custom-command" +``` + +> ⚠️ Please note, chaining multiple commands with `&&` is **not** currently supported. If you need to run multiple commands, you can defer to a custom script. Refer to [run](../project/run#custom-command-injection) for scenarios where multiple sub-command invocations are required. + +## CI Mode + +By using the `--ci` or `--non-interactive` flag, you can skip the interactive prompt for mnemonics. + +This is useful in CI/CD environments where user interaction is not possible. When using this flag, you need to make sure that the mnemonics are set as environment variables. + +Example: + +```sh +$ algokit project deploy testnet --ci +``` + +## Passing Extra Arguments + +You can pass additional arguments to the deploy command. These extra arguments will be appended to the end of the deploy command specified in your `.algokit.toml` file or to the command specified directly via `--command` option. + +To pass extra arguments, use `--` after the AlgoKit command and options to mark the distinction between arguments used by the CLI and arguments to be passed as extras to the deploy command/script. + +Example: + +```sh +$ algokit project deploy testnet -- my_contract_name --some_contract_related_param +``` + +In this example, `my_contract_name` and `--some_contract_related_param` are extra arguments that can be utilized by the custom deploy command invocation, for instance, to filter the deployment to a specific contract or modify deployment behavior. + +## Example of a Full Deployment + +```sh +$ algokit project deploy testnet --custom-deploy-command="your-custom-command" +``` + +This example shows how to deploy smart contracts to the testnet using a custom deploy command. This also assumes that .algokit.toml file is present in the current working directory, and .env.testnet file is present in the current working directory and contains the required environment variables for deploying to TestNet environment. + +## Further Reading + +For in-depth details, visit the [deploy](../cli-reference#deploy) section in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/project/link.md b/src/content/docs/reference/algokit-cli/project/link.md new file mode 100644 index 00000000..956ebe3a --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/link.md @@ -0,0 +1,69 @@ +--- +title: AlgoKit Project Link Command +--- + +The `algokit project link` command is a powerful feature designed to streamline the integration between `frontend` and `contract` typed projects within the AlgoKit ecosystem. This command facilitates the automatic path resolution and invocation of [`algokit generate client`](../generate#1-typed-clients) on `contract` projects available in the workspace, making it easier to integrate smart contracts with frontend applications. + +## Usage + +To use the `link` command, navigate to the root directory of your standalone frontend project and execute: + +```sh +$ algokit project link [OPTIONS] +``` + +This command must be invoked from the root of a standalone 'frontend' typed project. + +## Options + +- `--project-name`, `-p`: Specify one or more contract projects for the command. If not provided, the command defaults to all contract projects in the current workspace. This option can be repeated to specify multiple projects. + +- `--language`, `-l`: Set the programming language of the generated client code. The default is `typescript`, but you can specify other supported languages as well. + +- `--all`, `-a`: Link all contract projects with the frontend project. This option is mutually exclusive with `--project-name`. + +- `--fail-fast`, `-f`: Exit immediately if at least one client generation process fails. This is useful for CI/CD pipelines where you want to ensure all clients are correctly generated before proceeding. + +- `--version`, `-v`: Allows specifying the version of the client generator to use when generating client code for contract projects. This can be particularly useful for ensuring consistency across different environments or when a specific version of the client generator includes features or fixes that are necessary for your project. + +## How It Works + +Below is a visual representation of the `algokit project link` command in action: + +```mermaid +graph LR + F[Frontend Project] -->|algokit generate client| C1[Contract Project 1] + F -->|algokit generate client| C2[Contract Project 2] + F -->|algokit generate client| CN[Contract Project N] + + C1 -->|algokit generate client| F + C2 -->|algokit generate client| F + CN -->|algokit generate client| F + + classDef frontend fill:#f9f,stroke:#333,stroke-width:4px; + classDef contract fill:#bbf,stroke:#333,stroke-width:2px; + class F frontend; + class C1,C2,CN contract; +``` + +1. **Project Type Verification**: The command first verifies that it is being executed within a standalone frontend project by checking the project's type in the `.algokit.toml` configuration file. + +2. **Contract Project Selection**: Based on the provided options, it selects the contract projects to link. This can be all contract projects within the workspace, a subset specified by name, or a single project selected interactively. + +3. **Client Code Generation**: For each selected contract project, it generates typed client code using the specified language. The generated code is placed in the frontend project's directory specified for contract clients. + +4. **Feedback**: The command provides feedback for each contract project it processes, indicating success or failure in generating the client code. + +## Example + +Linking all contract projects with a frontend project and generating TypeScript clients: + +```sh +$ algokit project link --all -l typescript +``` + +This command will generate TypeScript clients for all contract projects and place them in the specified directory within the frontend project. + +## Further Reading + +To learn more about the `algokit project link` command, please refer to [link](../cli-reference#link) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/project/list.md b/src/content/docs/reference/algokit-cli/project/list.md new file mode 100644 index 00000000..dc2ea44e --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/list.md @@ -0,0 +1,45 @@ +--- +title: AlgoKit Project List Command +--- + +The `algokit project list` command is designed to enumerate all projects within an AlgoKit workspace. This command is particularly useful in workspace environments where multiple projects are managed under a single root directory. It provides a straightforward way to view all the projects that are part of the workspace. + +## Usage + +To use the `list` command, execute the following **anywhere** within an AlgoKit workspace: + +```sh +$ algokit project list [OPTIONS] [WORKSPACE_PATH] +``` + +- `WORKSPACE_PATH` is an optional argument that specifies the path to the workspace. If not provided, the current directory (`.`) is used as the default workspace path. + +## How It Works + +1. **Workspace Verification**: Initially, the command checks if the specified directory (or the current directory by default) is an AlgoKit workspace. This is determined by looking for a `.algokit.toml` configuration file and verifying if the `project.type` is set to `workspace`. + +2. **Project Enumeration**: If the directory is confirmed as a workspace, the command proceeds to enumerate all projects within the workspace. This is achieved by scanning the workspace's subdirectories for `.algokit.toml` files and extracting project names. + +3. **Output**: The names of all discovered projects are printed to the console. If the `-v` or `--verbose` option is used, additional details about each project are displayed. + +## Example Output + +```sh +workspace: {path_to_workspace} 📁 + - myapp ({path_to_myapp}) 📜 + - myproject-app ({path_to_myproject_app}) 🖥️ +``` + +## Error Handling + +If the command is executed in a directory that is not recognized as an AlgoKit workspace, it will issue a warning: + +```sh +WARNING: No AlgoKit workspace found. Check [project.type] definition at .algokit.toml +``` + +This message indicates that either the current directory does not contain a `.algokit.toml` file or the `project.type` within the file is not set to `workspace`. + +## Further Reading + +To learn more about the `algokit project list` command, please refer to [list](../cli-reference#list) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/project/overview.md b/src/content/docs/reference/algokit-cli/project/overview.md new file mode 100644 index 00000000..8f9c27ad --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/overview.md @@ -0,0 +1,97 @@ +--- +title: AlgoKit Project +--- + +`algokit project` is a collection of commands and command groups useful for managing algokit compliant [project workspaces](./init#workspaces). + +## Overview + +The `algokit project` command group is designed to simplify the management of AlgoKit projects. It provides a suite of tools to initialize, deploy, link, list, and run various components within a project workspace. This command group ensures that developers can efficiently handle the lifecycle of their projects, from bootstrapping to deployment and beyond. + +### What is a Project? + +In the context of AlgoKit, a "project" refers to a structured standalone or monorepo workspace that includes all the necessary components for developing, testing, and deploying Algorand applications. This may include smart contracts, frontend applications, and any associated configurations. In the context of the CLI, the `algokit project` commands help manage these components cohesively. + +The orchestration between workspaces, standalone projects, and custom commands is designed to provide a seamless development experience. Below is a high-level overview of how these components interact within the AlgoKit ecosystem. + +```mermaid +graph TD; +A[`algokit project` command group] --> B["Workspace (.algokit.toml)"]; +A --> C["Standalone Project (.algokit.toml)"]; +B --> D["Sub-Project 1 (.algokit.toml)"]; +B --> E["Sub-Project 2 (.algokit.toml)"]; +C --> F["Custom Commands defined in .algokit.toml"]; +D --> F; +E --> F; +``` + +- **AlgoKit Project**: The root command that encompasses all project-related functionalities. +- **Workspace**: A root folder that is managing multiple related sub-projects. +- **Standalone Project**: An isolated project structure for simpler applications. +- **Custom Commands**: Commands defined by the user in the `.algokit.toml` and automatically injected into the `algokit project run` command group. + +### Workspaces vs Standalone Projects + +As mentioned, AlgoKit supports two distinct project structures: Workspaces and Standalone Projects. This flexibility allows developers to choose the most suitable approach for their project's needs. + +### Workspaces + +Workspaces are designed for managing multiple related projects under a single root directory. This approach is beneficial for complex applications that consist of multiple sub-projects, such as a smart contract and a corresponding frontend application. Workspaces help in organizing these sub-projects in a structured manner, making it easier to manage dependencies and shared configurations. + +To initialize a project within a workspace, use the `--workspace` flag. If a workspace does not already exist, AlgoKit will create one for you by default (unless you disable it via `--no-workspace` flag). Once established, new projects can be added to this workspace, allowing for centralized management. + +To mark your project as `workspace` fill in the following in your `.algokit.toml` file: + +```toml +[project] +type = 'workspace' # type specifying if the project is a workspace or standalone +projects_root_path = 'projects' # path to the root folder containing all sub-projects in the workspace +``` + +#### VSCode optimizations + +AlgoKit has a set of minor optimizations for VSCode users that are useful to be aware of: + +- Templates created with the `--workspace` flag automatically include a VSCode code-workspace file. New projects added to an AlgoKit workspace are also integrated into an existing VSCode workspace. +- Using the `--ide` flag with `init` triggers automatic prompts to open the project and, if available, the code workspace in VSCode. + +#### Handling of the `.github` Folder + +A key aspect of using the `--workspace` flag is how the `.github` folder is managed. This folder, which contains GitHub-specific configurations such as workflows and issue templates, is moved from the project directory to the root of the workspace. This move is necessary because GitHub does not recognize workflows located in subdirectories. + +Here's a simplified overview of what happens: + +1. If a `.github` folder is found in your project, its contents are transferred to the workspace's root `.github` folder. +2. Files with matching names in the destination are not overwritten; they're skipped. +3. The original `.github` folder is removed if it's left empty after the move. +4. A notification is displayed, advising you to review the moved `.github` contents to ensure everything is in order. + +This process ensures that your GitHub configurations are properly recognized at the workspace level, allowing you to utilize GitHub Actions and other features seamlessly across your projects. + +### Standalone Projects + +Standalone projects are suitable for simpler applications or when working on a single component. This structure is straightforward, with each project residing in its own directory, independent of others. Standalone projects are ideal for developers who prefer simplicity or are focusing on a single aspect of their application and are sure that they will not need to add more sub-projects in the future. + +To create a standalone project, use the `--no-workspace` flag during initialization. This instructs AlgoKit to bypass the workspace structure and set up the project as an isolated entity. + +Both workspaces and standalone projects are fully supported by AlgoKit's suite of tools, ensuring developers can choose the structure that best fits their workflow without compromising on functionality. + +To mark your project as a standalone project fill in the following in your `.algokit.toml` file: + +```toml +[project] +type = {'backend' | 'contract' | 'frontend'} # currently support 3 generic categories for standalone projects +name = 'my-project' # unique name for the project inside workspace +``` + +> We recommend using workspaces for most projects (hence enabled by default), as it provides a more organized and scalable approach to managing multiple sub-projects. However, standalone projects are a great choice for simple applications or when you are certain that you will not need to add more sub-projects in the future, for such cases simply append `--no-workspace` when using `algokit init` command. For more details on init command please refer to [init](./init) command docs. + +## Features + +Dive into the features of the `algokit project` command group: + +- [bootstrap](./project/bootstrap) - Bootstrap your project with AlgoKit. +- [deploy](./project/deploy) - Deploy your smart contracts effortlessly to various networks. +- [link](./project/link) - Powerful feature designed to streamline the integration between `frontend` and `contract` projects +- [list](./project/list) - Enumerate all projects within an AlgoKit workspace. +- [run](./project/run) - Define custom commands and manage their execution via `algokit` cli. diff --git a/src/content/docs/reference/algokit-cli/project/run.md b/src/content/docs/reference/algokit-cli/project/run.md new file mode 100644 index 00000000..8a8df8fb --- /dev/null +++ b/src/content/docs/reference/algokit-cli/project/run.md @@ -0,0 +1,186 @@ +--- +title: AlgoKit Project Run +--- + +The `algokit project run` command allows defining custom commands to execute at standalone project level or being orchestrated from a workspace containing multiple standalone projects. + +## Usage + +```sh +$ algokit project run [OPTIONS] COMMAND [ARGS] +``` + +This command executes a custom command defined in the `.algokit.toml` file of the current project or workspace. + +### Options + +- `-l, --list`: List all projects associated with the workspace command. (Optional) +- `-p, --project-name`: Execute the command on specified projects. Defaults to all projects in the current directory. (Optional) +- `-t, --type`: Limit execution to specific project types if executing from workspace. (Optional) +- `-s, --sequential`: Execute workspace commands sequentially, for cases where you do not have a preference on the execution order, but want to disable concurrency. (Optional, defaults to concurrent) +- `[ARGS]...`: Additional arguments to pass to the custom command. These will be appended to the end of the command specified in the `.algokit.toml` file. + +To get detailed help on the above options, execute: + +```bash +algokit project run {name_of_your_command} --help +``` + +### Workspace vs Standalone Projects + +AlgoKit supports two main types of project structures: Workspaces and Standalone Projects. This flexibility caters to the diverse needs of developers, whether managing multiple related projects or focusing on a single application. + +- **Workspaces**: Ideal for complex applications comprising multiple sub-projects. Workspaces facilitate organized management of these sub-projects under a single root directory, streamlining dependency management and shared configurations. + +- **Standalone Projects**: Suited for simpler applications or when working on a single component. This structure offers straightforward project management, with each project residing in its own directory, independent of others. + +> Please note, instantiating a workspace inside a workspace (aka 'workspace nesting') is not supported and not recommended. When you want to add a new project into existing workspace make sure to run `algokit init` **from the root of the workspace** + +### Custom Command Injection + +AlgoKit enhances project automation by allowing the injection of custom commands into the `.algokit.toml` configuration file. This feature enables developers to tailor the project setup to their specific needs, automating tasks such as deploying to different network environments or integrating with CI/CD pipelines. + +## How It Works + +The orchestration between workspaces, standalone projects, and custom commands is designed to provide a seamless development experience. Below is a high-level overview of how these components interact within the AlgoKit ecosystem. + +```mermaid +graph TD; +A[AlgoKit Project] --> B["Workspace (.algokit.toml)"]; +A --> C["Standalone Project (.algokit.toml)"]; +B --> D["Sub-Project 1 (.algokit.toml)"]; +B --> E["Sub-Project 2 (.algokit.toml)"]; +C --> F["Custom Commands defined in .algokit.toml"]; +D --> F; +E --> F; +``` + +- **AlgoKit Project**: The root command that encompasses all project-related functionalities. +- **Workspace**: A root folder that is managing multiple related sub-projects. +- **Standalone Project**: An isolated project structure for simpler applications. +- **Custom Commands**: Commands defined by the user in the `.algokit.toml` and automatically injected into the `algokit project run` command group. + +### Workspace cli options + +Below is only visible and available when running from a workspace root. + +- `-l, --list`: List all projects associated with the workspace command. (Optional) +- `-p, --project-name`: Execute the command on specified projects. Defaults to all projects in the current directory. (Optional) +- `-t, --type`: Limit execution to specific project types if executing from workspace. (Optional) + To get a detailed help on the above commands execute: + +```bash +algokit project run {name_of_your_command} --help +``` + +## Examples + +Assume you have a default workspace with the following structure: + +```bash +my_workspace +├── .algokit.toml +├── projects +│ ├── project1 +│ │ └── .algokit.toml +│ └── project2 +│ └── .algokit.toml +``` + +The workspace configuration file is defined as follows: + +```toml +# ... other non [project.run] related metadata +[project] +type = 'workspace' +projects_root_path = 'projects' +# ... other non [project.run] related metadata +``` + +Standalone configuration files are defined as follows: + +```toml +# ... other non [project.run] related metadata + +[project] +type = 'contract' +name = 'project_a' + +[project.run] +hello = { commands = ['echo hello'], description = 'Prints hello' } + +# ... other non [project.run] related metadata +``` + +```toml +# ... other non [project.run] related metadata + +[project] +type = 'frontend' +name = 'project_b' + +[project.run] +hello = { commands = ['echo hello'], description = 'Prints hello' } + +# ... other non [project.run] related metadata +``` + +Executing `algokit project run hello` from the root of the workspace will concurrently execute `echo hello` in both `project_a` and `project_b` directories. + +Executing `algokit project run hello` from the root of `project_(a|b)` will execute `echo hello` in the `project_(a|b)` directory. + +### Controlling Execution Order + +Customize the execution order of commands in workspaces for precise control: + +1. Define order in `.algokit.toml`: + + ```yaml + [project] + type = 'workspace' + projects_root_path = 'projects' + + [project.run] + hello = ['project_a', 'project_b'] + ``` + +2. Execution behavior: + - Projects are executed in the specified order + - Invalid project names are skipped + - Partial project lists: Specified projects run first, others follow + +> Note: Explicit order always triggers sequential execution. + +### Controlling Concurrency + +You can control whether commands are executed concurrently or sequentially: + +1. Use command-line options: + + ```sh + $ algokit project run hello -s # or --sequential + $ algokit project run hello -c # or --concurrent + ``` + +2. Behavior: + - Default: Concurrent execution + - Sequential: Use `-s` or `--sequential` flag + - Concurrent: Use `-c` or `--concurrent` flag or omit the flag (defaults to concurrent) + +> Note: When an explicit order is specified in `.algokit.toml`, execution is always sequential regardless of these flags. + +### Passing Extra Arguments + +You can pass additional arguments to the custom command. These extra arguments will be appended to the end of the command specified in your `.algokit.toml` file. + +Example: + +```sh +$ algokit project run hello -- world +``` + +In this example, if the `hello` command in `.algokit.toml` is defined as `echo "Hello"`, the actual command executed will be `echo "Hello" world`. + +## Further Reading + +To learn more about the `algokit project run` command, please refer to [run](../cli-reference#run) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/reference.mdx b/src/content/docs/reference/algokit-cli/reference.mdx deleted file mode 100644 index ce1e5eac..00000000 --- a/src/content/docs/reference/algokit-cli/reference.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: CLI Reference ---- diff --git a/src/content/docs/reference/algokit-cli/tasks.md b/src/content/docs/reference/algokit-cli/tasks.md new file mode 100644 index 00000000..efe5b15b --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks.md @@ -0,0 +1,18 @@ +--- +title: AlgoKit Tasks +--- + +AlgoKit Tasks are a collection of handy tasks that can be used to perform various operations on Algorand blockchain. + +## Features + +- [Wallet Aliasing](./tasks/wallet) - Manage your Algorand addresses and accounts effortlessly with the AlgoKit Wallet feature. This feature allows you to create short aliases for your addresses and accounts on AlgoKit CLI. +- [Vanity Address Generation](./tasks/vanity_address) - Generate vanity addresses for your Algorand accounts with the AlgoKit Vanity feature. This feature allows you to generate Algorand addresses which contains a specific keyword of your choice. +- [Transfer Assets or Algos](./tasks/transfer) - Transfer Algos or Assets from one account to another with the AlgoKit Transfer feature. This feature allows you to transfer Algos or Assets from one account to another on Algorand blockchain. +- [Opt-(in|out) Assets](./tasks/opt) - Opt-in or opt-out of Algorand Asset(s). Supports single or multiple assets. +- [Signing transactions](./tasks/sign) - Sign goal clerk compatible Algorand transactions. +- [Sending transactions](./tasks/send) - Send signed goal clerk compatible Algorand transactions. +- [NFD lookups](./tasks/nfd) - Perform a lookup via NFD domain or address, returning the associated address or domain respectively using the AlgoKit CLI. +- [IPFS uploads](./tasks/ipfs) - Upload files to IPFS. +- [Asset minting](./tasks/mint) - Mint new fungible or non-fungible assets on Algorand. +- [Analyze TEAL code](./tasks/analyze) - Analyze TEAL code using [`tealer`](https://github.com/crytic/tealer) integration for common vulnerabilities. diff --git a/src/content/docs/reference/algokit-cli/tasks.mdx b/src/content/docs/reference/algokit-cli/tasks.mdx deleted file mode 100644 index 9e496589..00000000 --- a/src/content/docs/reference/algokit-cli/tasks.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Tasks ---- diff --git a/src/content/docs/reference/algokit-cli/tasks/analyze.md b/src/content/docs/reference/algokit-cli/tasks/analyze.md new file mode 100644 index 00000000..e2912d09 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/analyze.md @@ -0,0 +1,35 @@ +--- +title: AlgoKit Task Analyze +--- + +The `analyze` task is a command-line utility that analyzes TEAL programs for common vulnerabilities using [Tealer](https://github.com/crytic/tealer) integration. It allows you to detect a range of common vulnerabilities in code written in TEAL. For full list of vulnerability detectors refer to [Tealer documentation](https://github.com/crytic/tealer?tab=readme-ov-file#detectors). + +## Usage + +```bash +algokit task analyze INPUT_PATHS [OPTIONS] +``` + +### Arguments + +- `INPUT_PATHS`: Paths to the TEAL files or directories containing TEAL files to be analyzed. This argument is required. + +### Options + +- `-r, --recursive`: Recursively search for all TEAL files within any provided directories. +- `--force`: Force verification without the disclaimer confirmation prompt. +- `--diff`: Exit with a non-zero code if differences are found between current and last reports. +- `-o, --output OUTPUT_PATH`: Directory path where to store the reports of the static analysis. +- `-e, --exclude DETECTORS`: Exclude specific vulnerabilities from the analysis. Supports multiple exclusions in a single run. + +## Example + +```bash +algokit task analyze ./contracts -r --exclude rekey-to --exclude missing-fee-check +``` + +This command will recursively analyze all TEAL files in the `contracts` directory and exclude the `missing-fee-check` vulnerability from the analysis. + +## Security considerations + +This task uses [`tealer`](https://github.com/crytic/tealer), a third-party tool, to suggest improvements for your TEAL programs, but remember to always test your smart contracts code, follow modern software engineering practices and use the [guidelines for smart contract development](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/guidelines/). This should not be used as a substitute for an actual audit. diff --git a/src/content/docs/reference/algokit-cli/tasks/ipfs.md b/src/content/docs/reference/algokit-cli/tasks/ipfs.md new file mode 100644 index 00000000..6da80c64 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/ipfs.md @@ -0,0 +1,68 @@ +--- +title: AlgoKit Task IPFS +--- + +The AlgoKit IPFS feature allows you to interact with the IPFS [InterPlanetary File System](https://ipfs.tech/) using the [Piñata provider](https://www.pinata.cloud/). This feature supports logging in and out of the Piñata provider, and uploading files to IPFS. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task ipfs +Usage: algokit task ipfs [OPTIONS] + +Upload files to IPFS using Pinata provider. + +Options: + -f, --file PATH Path to the file to upload. [required] + -n, --name TEXT Human readable name for this upload, for use in file listings. + -h, --help Show this message and exit. +``` + +## Options + +- `--file, -f PATH`: Specifies the path to the file to upload. This option is required. +- `--name, -n TEXT`: Specifies a human readable name for this upload, for use in file listings. + +## Prerequisites + +Before you can use this feature, you need to ensure that you have signed up for a Piñata account and have a JWT. You can sign up for a Piñata account by reading [quickstart](https://docs.pinata.cloud/docs/getting-started). + +## Login + +Please note, you need to login to the Piñata provider before you can upload files. You can do this using the `login` command: + +```bash +$ algokit task ipfs login +``` + +This will prompt you to enter your Piñata JWT. Once you are logged in, you can upload files to IPFS. + +## Upload + +To upload a file to IPFS, you can use the `ipfs` command as follows: + +```bash +$ algokit task ipfs --file {PATH_TO_YOUR_FILE} +``` + +This will upload the file to IPFS using the Piñata provider and return the CID (Content Identifier) of the uploaded file. + +## Logout + +If you want to logout from the Piñata provider, you can use the `logout` command: + +```bash +$ algokit task ipfs logout +``` + +This will remove your Piñata JWT from the keyring. + +## File Size Limit + +Please note, the maximum file size that can be uploaded is 100MB. If you try to upload a file larger than this, you will receive an error. + +## Further Reading + +For in-depth details, visit the [ipfs section](../cli-reference#ipfs) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/mint.md b/src/content/docs/reference/algokit-cli/tasks/mint.md new file mode 100644 index 00000000..27d006cc --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/mint.md @@ -0,0 +1,72 @@ +--- +title: AlgoKit Task Mint +--- + +The AlgoKit Mint feature allows you to mint new fungible or non-fungible assets on the Algorand blockchain. This feature supports the creation of assets, validation of asset parameters, and uploading of asset metadata and image to IPFS using the Piñata provider. Immutable assets are compliant with [ARC3](https://arc.algorand.foundation/ARCs/arc-0003), while mutable are based using [ARC19](https://arc.algorand.foundation/ARCs/arc-0019) standard. + +## Usage + +Available commands and possible usage as follows: + +```bash +Usage: algokit task mint [OPTIONS] + + Mint new fungible or non-fungible assets on Algorand. + +Options: + --creator TEXT Address or alias of the asset creator. [required] + -n, --name TEXT Asset name. [required] + -u, --unit TEXT Unit name of the asset. [required] + -t, --total INTEGER Total supply of the asset. Defaults to 1. + -d, --decimals INTEGER Number of decimals. Defaults to 0. + -i, --image FILE Path to the asset image file to be uploaded to IPFS. [required] + -m, --metadata FILE Path to the ARC19 compliant asset metadata file to be uploaded to IPFS. If not + provided, a default metadata object will be generated automatically based on asset- + name, decimals and image. For more details refer to + https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema. + --mutable / --immutable Whether the asset should be mutable or immutable. Refers to `ARC19` by default. + --nft / --ft Whether the asset should be validated as NFT or FT. Refers to NFT by default and + validates canonical definitions of pure or fractional NFTs as per ARC3 standard. + -n, --network [localnet|testnet|mainnet] + Network to use. Refers to `localnet` by default. + -h, --help Show this message and exit. +``` + +## Options + +- `--creator TEXT`: Specifies the address or alias of the asset creator. This option is required. +- `-n, --name TEXT`: Specifies the asset name. This option is required. +- `-u, --unit TEXT`: Specifies the unit name of the asset. This option is required. +- `-t, --total INTEGER`: Specifies the total supply of the asset. Defaults to 1. +- `-d, --decimals INTEGER`: Specifies the number of decimals. Defaults to 0. +- `-i, --image PATH`: Specifies the path to the asset image file to be uploaded to IPFS. This option is required. +- `-m, --metadata PATH`: Specifies the path to the ARC19 compliant asset metadata file to be uploaded to IPFS. If not provided, a default metadata object will be generated automatically based on asset-name, decimals and image. +- `--mutable / --immutable`: Specifies whether the asset should be mutable or immutable. Refers to `ARC19` by default. +- `--nft / --ft`: Specifies whether the asset should be validated as NFT or FT. Refers to NFT by default and validates canonical definitions of pure or fractional NFTs as per ARC3 standard. +- `-n, --network [localnet|testnet|mainnet]`: Specifies the network to use. Refers to `localnet` by default. + +## Example + +To mint a new asset in interactive mode, you can use the mint command as follows: + +```bash +$ algokit task mint +``` + +This will interactively prompt you for the required information, upload the asset image and metadata to IPFS using the Piñata provider and mint a new asset on the Algorand blockchain. The [asset's metadata](https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema) will be generated automatically based on the provided asset name, decimals, and image. + +If you want to provide a custom metadata file, you can use the --metadata flag: + +```bash +$ algokit task mint --metadata {PATH_TO_METADATA} +``` + +If the minting process is successful, the asset ID and transaction ID will be output to the console. + +For non interactive mode, refer to usage section above for available options. + +> Please note, creator account must have at least 0.2 Algos available to cover minimum balance requirements. + +## Further Reading + +For in-depth details, visit the [mint section](../cli-reference#mint) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/nfd.md b/src/content/docs/reference/algokit-cli/tasks/nfd.md new file mode 100644 index 00000000..c4d8f643 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/nfd.md @@ -0,0 +1,47 @@ +--- +title: AlgoKit Task NFD Lookup +--- + +The AlgoKit NFD Lookup feature allows you to perform a lookup via NFD domain or address, returning the associated address or domain respectively using the AlgoKit CLI. The feature is powered by [NFDomains MainNet API](https://api-docs.nf.domains/). + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task nfd-lookup +Usage: algokit task nfd-lookup [OPTIONS] VALUE + +Perform a lookup via NFD domain or address, returning the associated address or domain respectively. + +Options: +-o, --output [full|tiny|address] Output format for NFD API response. Defaults to address|domain resolved. +-h, --help Show this message and exit. +``` + +## Options + +- `VALUE`: Specifies the NFD domain or Algorand address to lookup. This argument is required. +- `--output, -o [full|tiny|address]`: Specifies the output format for NFD API response. Defaults to address|domain resolved. + +> When using the `full` and `tiny` output formats, please be aware that these match the [views in get requests of the NFD API](https://api-docs.nf.domains/quick-start#views-in-get-requests). The `address` output format, which is used by default, refers to the respective domain name or address resolved and outputs it as a string (if found). + +## Example + +To perform a lookup, you can use the nfd-lookup command as follows: + +```bash +$ algokit task nfd-lookup {NFD_DOMAIN_OR_ALGORAND_ADDRESS} +``` + +This will perform a lookup and return the associated address or domain. If you want to specify the output format, you can use the --output flag: + +```bash +$ algokit task nfd-lookup {NFD_DOMAIN_OR_ALGORAND_ADDRESS} --output full +``` + +If the lookup is successful, the result will be output to the console in a JSON format. + +## Further Reading + +For in-depth details, visit the [nfd-lookup section](../cli-reference#nfd-lookup) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/opt.md b/src/content/docs/reference/algokit-cli/tasks/opt.md new file mode 100644 index 00000000..210f4b1e --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/opt.md @@ -0,0 +1,73 @@ +--- +title: AlgoKit Task Asset opt-(in|out) +--- + +AlgoKit Task Asset opt-(in|out) allows you to opt-in or opt-out of Algorand Asset(s). This task supports single or multiple assets. + +## Usage + +Available commands and possible usage as follows: + +### Opt-in + +```bash +Usage: algokit task opt-in [OPTIONS] ASSET_IDS... + + Opt-in to an asset(s). This is required before you can receive an asset. + Use -n to specify localnet, testnet, or mainnet. To supply multiple asset IDs, separate them with a whitespace. + +Options: + --account, -a TEXT Address or alias of the signer account. [required] + -n, --network [localnet|testnet|mainnet] + Network to use. Refers to `localnet` by default. +``` + +### Opt-out + +```bash +Usage: algokit task opt-out [OPTIONS] [ASSET_IDS]... + + Opt-out of an asset(s). You can only opt out of an asset with a zero balance. + Use -n to specify localnet, testnet, or mainnet. To supply multiple asset IDs, separate them with a whitespace. + +Options: + --account, -a TEXT Address or alias of the signer account. [required] + --all Opt-out of all assets with zero balance. + -n, --network [localnet|testnet|mainnet] + Network to use. Refers to `localnet` by default. +``` + +## Options + +- `ASSET_IDS`: Specifies the asset IDs to opt-in or opt-out. To supply multiple asset IDs, separate them with a whitespace. +- `--account`, `-a` TEXT: Specifies the address or alias of the signer account. This option is required. +- `--all`: Specifies to opt-out of all assets with zero balance. +- `-n`, `--network` [localnet|testnet|mainnet]: Specifies the network to use. Refers to localnet by default. + +## Example + +Example + +To opt-in to an asset(s), you can use the opt-in command as follows: + +```bash +$ algokit task opt-in --account {YOUR_ACCOUNT} {ASSET_ID_1} {ASSET_ID_2} {ASSET_ID_3} ... +``` + +To opt-out of an asset(s), you can use the opt-out command as follows: + +```bash +$ algokit task opt-out --account {YOUR_ACCOUNT} {ASSET_ID_1} {ASSET_ID_2} ... +``` + +To opt-out of all assets with zero balance, you can use the opt-out command with the `--all` flag: + +```bash +$ algokit task opt-out --account {YOUR_ACCOUNT} --all +``` + +> Please note, the account must have sufficient balance to cover the transaction fees. + +## Further Reading + +For in-depth details, visit the [opt-in](../cli-reference#opt-in) and [opt-out](../cli-reference#opt-out) sections in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/overview.md b/src/content/docs/reference/algokit-cli/tasks/overview.md new file mode 100644 index 00000000..efe5b15b --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/overview.md @@ -0,0 +1,18 @@ +--- +title: AlgoKit Tasks +--- + +AlgoKit Tasks are a collection of handy tasks that can be used to perform various operations on Algorand blockchain. + +## Features + +- [Wallet Aliasing](./tasks/wallet) - Manage your Algorand addresses and accounts effortlessly with the AlgoKit Wallet feature. This feature allows you to create short aliases for your addresses and accounts on AlgoKit CLI. +- [Vanity Address Generation](./tasks/vanity_address) - Generate vanity addresses for your Algorand accounts with the AlgoKit Vanity feature. This feature allows you to generate Algorand addresses which contains a specific keyword of your choice. +- [Transfer Assets or Algos](./tasks/transfer) - Transfer Algos or Assets from one account to another with the AlgoKit Transfer feature. This feature allows you to transfer Algos or Assets from one account to another on Algorand blockchain. +- [Opt-(in|out) Assets](./tasks/opt) - Opt-in or opt-out of Algorand Asset(s). Supports single or multiple assets. +- [Signing transactions](./tasks/sign) - Sign goal clerk compatible Algorand transactions. +- [Sending transactions](./tasks/send) - Send signed goal clerk compatible Algorand transactions. +- [NFD lookups](./tasks/nfd) - Perform a lookup via NFD domain or address, returning the associated address or domain respectively using the AlgoKit CLI. +- [IPFS uploads](./tasks/ipfs) - Upload files to IPFS. +- [Asset minting](./tasks/mint) - Mint new fungible or non-fungible assets on Algorand. +- [Analyze TEAL code](./tasks/analyze) - Analyze TEAL code using [`tealer`](https://github.com/crytic/tealer) integration for common vulnerabilities. diff --git a/src/content/docs/reference/algokit-cli/tasks/send.md b/src/content/docs/reference/algokit-cli/tasks/send.md new file mode 100644 index 00000000..28fa0fb5 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/send.md @@ -0,0 +1,62 @@ +--- +title: AlgoKit Task Send +--- + +The AlgoKit Send feature allows you to send signed Algorand transaction(s) to a specified network using the AlgoKit CLI. This feature supports sending single or multiple transactions, either provided directly as a base64 encoded string or from a binary file. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task send +Usage: algokit task send [OPTIONS] + + Send a signed transaction to the given network. + +Options: + -f, --file FILE Single or multiple message pack encoded signed transactions from binary file to + send. Option is mutually exclusive with transaction. + -t, --transaction TEXT Base64 encoded signed transaction to send. Option is mutually exclusive with file. + -n, --network [localnet|testnet|mainnet] + Network to use. Refers to `localnet` by default. + -h, --help Show this message and exit. +``` + +## Options + +- `--file, -f PATH`: Specifies the path to a binary file containing single or multiple message pack encoded signed transactions to send. Mutually exclusive with `--transaction` option. +- `--transaction, -t TEXT`: Specifies a single base64 encoded signed transaction to send. Mutually exclusive with `--file` option. +- `--network, -n [localnet|testnet|mainnet]`: Specifies the network to which the transactions will be sent. Refers to `localnet` by default. + +> Please note, `--transaction` flag only supports sending a single transaction. If you want to send multiple transactions, you can use the `--file` flag to specify a binary file containing multiple transactions. + +## Example + +To send a transaction, you can use the `send` command as follows: + +```bash +$ algokit task send --file {PATH_TO_BINARY_FILE_CONTAINING_SIGNED_TRANSACTIONS} +``` + +This will send the transactions to the default `localnet` network. If you want to send the transactions to a different network, you can use the `--network` flag: + +```bash +$ algokit task send --transaction {YOUR_BASE64_ENCODED_SIGNED_TRANSACTION} --network testnet +``` + +You can also pipe in the `stdout` of `algokit sign` command: + +```bash +$ algokit task sign --account {YOUR_ACCOUNT_ALIAS OR YOUR_ADDRESS} --file {PATH_TO_BINARY_FILE_CONTAINING_TRANSACTIONS} --force | algokit task send --network {network_name} +``` + +If the transaction is successfully sent, the transaction ID (txid) will be output to the console. You can check the transaction status at the provided transaction explorer URL. + +## Goal Compatibility + +Please note, at the moment this feature only supports [`goal clerk`](https://developer.algorand.org/docs/clis/goal/clerk/clerk/) compatible transaction objects. + +## Further Reading + +For in-depth details, visit the [send section](../cli-reference#send) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/sign.md b/src/content/docs/reference/algokit-cli/tasks/sign.md new file mode 100644 index 00000000..8b8e527a --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/sign.md @@ -0,0 +1,94 @@ +--- +title: AlgoKit Task Sign +--- + +The AlgoKit Sign feature allows you to sign Algorand transaction(s) using the AlgoKit CLI. This feature supports signing single or multiple transactions, either provided directly as a base64 encoded string or from a binary file. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task sign +Usage: algokit task sign [OPTIONS] + +Sign goal clerk compatible Algorand transaction(s). + +Options: +-a, --account TEXT Address or alias of the signer account. [required] +-f, --file PATH Single or multiple message pack encoded transactions from binary file to sign. +-t, --transaction TEXT Single base64 encoded transaction object to sign. +-o, --output PATH The output file path to store signed transaction(s). +--force Force signing without confirmation. +-h, --help Show this message and exit. +``` + +## Options + +- `--account, -a TEXT`: Specifies the address or alias of the signer account. This option is required. +- `--file, -f PATH`: Specifies the path to a binary file containing single or multiple message pack encoded transactions to sign. Mutually exclusive with `--transaction` option. +- `--transaction, -t TEXT`: Specifies a single base64 encoded transaction object to sign. Mutually exclusive with `--file` option. +- `--output, -o PATH`: Specifies the output file path to store signed transaction(s). +- `--force`: If specified, it allows signing without interactive confirmation prompt. + +> Please note, `--transaction` flag only supports signing a single transaction. If you want to sign multiple transactions, you can use the `--file` flag to specify a binary file containing multiple transactions. + +## Example + +To sign a transaction, you can use the `sign` command as follows: + +```bash +$ algokit task sign --account {YOUR_ACCOUNT_ALIAS OR YOUR_ADDRESS} --file {PATH_TO_BINARY_FILE_CONTAINING_TRANSACTIONS} +``` + +This will prompt you to confirm the transaction details before signing. If you want to bypass the confirmation, you can use the `--force` flag: + +```bash +$ algokit task sign --account {YOUR_ACCOUNT_ALIAS OR YOUR_ADDRESS} --transaction {YOUR_BASE64_ENCODED_TRANSACTION} --force +``` + +If the transaction is successfully signed, the signed transaction will be output to the console in a JSON format. If you want to write the signed transaction to a file, you can use the `--output` option: + +```bash +$ algokit task sign --account {YOUR_ACCOUNT_ALIAS OR YOUR_ADDRESS} --transaction {YOUR_BASE64_ENCODED_TRANSACTION} --output /path/to/output/file +``` + +This will write the signed transaction to the specified file. + +## Goal Compatibility + +Please note, at the moment this feature only supports [`goal clerk`](https://developer.algorand.org/docs/clis/goal/clerk/clerk/) compatible transaction objects. + +When `--output` option is not specified, the signed transaction(s) will be output to the console in a following JSON format: + +``` +[ + {transaction_id: "TRANSACTION_ID", content: "BASE64_ENCODED_SIGNED_TRANSACTION"}, +] +``` + +On the other hand, when `--output` option is specified, the signed transaction(s) will be stored to a file as a message pack encoded binary file. + +### Encoding transactins for signing + +Algorand provides a set of options in [py-algorand-sdk](https://github.com/algorand/py-algorand-sdk) and [js-algorand-sdk](https://github.com/algorand/js-algorand-sdk) to encode transactions for signing. + +Encoding simple txn object in python: + +```py +# Encoding single transaction as a base64 encoded string +algosdk.encoding.msgpack_encode({"txn": {YOUR_TXN_OBJECT}.dictify()}) # Resulting string can be passed directly to algokit task sign with --transaction flag + +# Encoding multiple transactions as a message pack encoded binary file +algosdk.transaction.write_to_file([{YOUR_TXN_OBJECT}], "some_file.txn") # Resulting file path can be passed directly to algokit sign with --file flag +``` + +Encoding simple txn object in javascript: + +```ts +Buffer.from(algosdk.encodeObj({ txn: txn.get_obj_for_encoding() })).toString('base64'); // Resulting string can be passed directly to algokit task sign with --transaction flag +``` + +## Further Reading + +For in-depth details, visit the [sign section](../cli-reference#sign) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/transfer.md b/src/content/docs/reference/algokit-cli/tasks/transfer.md new file mode 100644 index 00000000..4f20f961 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/transfer.md @@ -0,0 +1,56 @@ +--- +title: AlgoKit Task Transfer +--- + +The AlgoKit Transfer feature allows you to transfer algos and assets between two accounts. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task transfer +Usage: algokit task transfer [OPTIONS] + +Transfer algos or assets from one account to another. + +Options: + -s, --sender TEXT Address or alias of the sender account [required] + -r, --receiver TEXT Address or alias to an account that will receive the asset(s) [required] + --asset, --id INTEGER ASA asset id to transfer + -a, --amount INTEGER Amount to transfer [required] + --whole-units Use whole units (Algos | ASAs) instead of smallest divisible units (for example, + microAlgos). Disabled by default. + -n, --network [localnet|testnet|mainnet] + Network to use. Refers to `localnet` by default. + -h, --help Show this message and exit. +``` + +> Note: If you use a wallet address for the `sender` argument, you'll be asked for the mnemonic phrase. To use a wallet alias instead, see the [wallet aliasing](wallet) task. For wallet aliases, the sender must have a stored `private key`, but the receiver doesn't need one. This is because the sender signs and sends the transfer transaction, while the receiver reference only needs a valid Algorand address. + +## Examples + +### Transfer algo between accounts on LocalNet + +```bash +$ ~ algokit task transfer -s {SENDER_ALIAS OR SENDER_ADDRESS} -r {RECEIVER_ALIAS OR RECEIVER_ADDRESS} -a {AMOUNT} +``` + +By default: + +- the `amount` is in microAlgos. To use whole units, use the `--whole-units` flag. +- the `network` is `localnet`. + +### Transfer asset between accounts on TestNet + +```bash +$ ~ algokit task transfer -s {SENDER_ALIAS OR SENDER_ADDRESS} -r {RECEIVER_ALIAS OR RECEIVER_ADDRESS} -a {AMOUNT} --id {ASSET_ID} --network testnet +``` + +By default: + +- the `amount` is smallest divisible unit of supplied `ASSET_ID`. To use whole units, use the `--whole-units` flag. + +## Further Reading + +For in-depth details, visit the [transfer section](../cli-reference#transfer) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/vanity_address.md b/src/content/docs/reference/algokit-cli/tasks/vanity_address.md new file mode 100644 index 00000000..344e383f --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/vanity_address.md @@ -0,0 +1,58 @@ +--- +title: AlgoKit Task Vanity Address +--- + +The AlgoKit Vanity Address feature allows you to generate a vanity Algorand address. A vanity address is an address that contains a specific keyword in it. The keyword can only include uppercase letters A-Z and numbers 2-7. The longer the keyword, the longer it may take to generate a matching address. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task vanity-address +Usage: algokit task vanity-address [OPTIONS] KEYWORD + + Generate a vanity Algorand address. Your KEYWORD can only include letters A - Z and numbers 2 - 7. Keeping your + KEYWORD under 5 characters will usually result in faster generation. Note: The longer the KEYWORD, the longer it may + take to generate a matching address. Please be patient if you choose a long keyword. + +Options: + -m, --match [start|anywhere|end] + Location where the keyword will be included. Default is start. + -o, --output [stdout|alias|file] + How the output will be presented. + -a, --alias TEXT Alias for the address. Required if output is "alias". + --file-path PATH File path where to dump the output. Required if output is "file". + -f, --force Allow overwriting an aliases without confirmation, if output option is 'alias'. + -h, --help Show this message and exit. +``` + +## Examples + +Generate a vanity address with the keyword "ALGO" at the start of the address with default output to `stdout`: + +```bash +$ ~ algokit task vanity-address ALGO +``` + +Generate a vanity address with the keyword "ALGO" at the start of the address with output to a file: + +```bash +$ ~ algokit task vanity-address ALGO -o file -f vanity-address.txt +``` + +Generate a vanity address with the keyword "ALGO" anywhere in the address with output to a file: + +```bash +$ ~ algokit task vanity-address ALGO -m anywhere -o file -f vanity-address.txt +``` + +Generate a vanity address with the keyword "ALGO" at the start of the address and store into a [wallet alias](wallet): + +```bash +$ ~ algokit task vanity-address ALGO -o alias -a my-vanity-address +``` + +## Further Reading + +For in-depth details, visit the [vanity-address section](../cli-reference#vanity-address) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/tasks/wallet.md b/src/content/docs/reference/algokit-cli/tasks/wallet.md new file mode 100644 index 00000000..a933cbf6 --- /dev/null +++ b/src/content/docs/reference/algokit-cli/tasks/wallet.md @@ -0,0 +1,99 @@ +--- +title: AlgoKit Task Wallet +--- + +Manage your Algorand addresses and accounts effortlessly with the AlgoKit Wallet feature. This feature allows you to create short aliases for your addresses and accounts on AlgoKit CLI. + +## Usage + +Available commands and possible usage as follows: + +```bash +$ ~ algokit task wallet +Usage: algokit task wallet [OPTIONS] COMMAND [ARGS]... + +Create short aliases for your addresses and accounts on AlgoKit CLI. + +Options: +-h, --help Show this message and exit. + +Commands: +add Add an address or account to be stored against a named alias. +get Get an address or account stored against a named alias. +list List all addresses and accounts stored against a named alias. +remove Remove an address or account stored against a named alias. +reset Remove all aliases. +``` + +## Commands + +### Add + +This command adds an address or account to be stored against a named alias. If the `--mnemonic` flag is used, it will prompt the user for a mnemonic phrase interactively using masked input. If the `--force` flag is used, it will allow overwriting an existing alias. Maximum number of aliases that can be stored at a time is 50. + +```bash +algokit wallet add [OPTIONS] ALIAS_NAME +``` + +> Please note, the command is not designed to be used in CI scope, there is no option to skip interactive masked input of the mnemonic, if you want to alias an `Account` (both private and public key) entity. + +#### Options + +- `--address, -a TEXT`: Specifies the address of the account. This option is required. +- `--mnemonic, -m`: If specified, it prompts the user for a mnemonic phrase interactively using masked input. +- `--force, -f`: If specified, it allows overwriting an existing alias without interactive confirmation prompt. + +### Get + +This command retrieves an address or account stored against a named alias. + +```bash +algokit wallet get ALIAS +``` + +### List + +This command lists all addresses and accounts stored against a named alias. If a record contains a `private_key` it will show a boolean flag indicating whether it exists, actual private key values are never exposed. As a user you can obtain the content of the stored aliases by navigating to your dedicated password manager (see [keyring details](https://pypi.org/project/keyring/)). + +```bash +algokit wallet list +``` + +### Remove + +This command removes an address or account stored against a named alias. +You must confirm the prompt interactively or pass `--force` | `-f` flag to ignore the prompt. + +```bash +algokit wallet remove ALIAS [--force | -f] +``` + +### Reset + +This command removes all aliases. You must confirm the prompt interactively or pass `--force` | `-f` flag to ignore the prompt. + +```bash +algokit wallet reset [--force | -f] +``` + +## Keyring + +AlgoKit relies on the [keyring](https://pypi.org/project/keyring/) library, which provides an easy way to interact with the operating system's password manager. This abstraction allows AlgoKit to securely manage sensitive information such as mnemonics and private keys. + +When you use AlgoKit to store a mnemonic, it is never printed or exposed directly in the console. Instead, the mnemonic is converted and stored as a private key in the password manager. This ensures that your sensitive information is kept secure. + +To retrieve the stored mnemonic, you will need to manually navigate to your operating system's password manager. The keyring library supports a variety of password managers across different operating systems. Here are some examples: + +- On macOS, it uses the Keychain Access app. +- On Windows, it uses the Credential Manager. +- On Linux, it can use Secret Service API, KWallet, or an in-memory store depending on your setup. + +> Remember, AlgoKit is designed to keep your sensitive information secure however your storage is only as secure as the device on which it is stored. Always ensure to maintain good security practices on your device, especially when dealing with mnemonics that are to be used on MainNet. + +### Keyring on WSL2 + +WSL2 environments don't have a keyring backend installed by default. If you want to leverage this feature, you'll need to install one yourself. See [this GitHub issue for info](https://github.com/jaraco/keyring/issues/566#issuecomment-1792544475). + +## Further Reading + +For in-depth details, visit the [wallet section](../cli-reference#wallet) in the AlgoKit CLI reference documentation. diff --git a/src/content/docs/reference/algokit-cli/testnet-funding.mdx b/src/content/docs/reference/algokit-cli/testnet-funding.mdx deleted file mode 100644 index 5a02755a..00000000 --- a/src/content/docs/reference/algokit-cli/testnet-funding.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Testnet Funding ----