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

$ 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:

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.

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:

algokit project run {name_of_your_command} --help

Examples

Assume you have a default workspace with the following structure:

my_workspace
├── .algokit.toml
├── projects
│   ├── project1
│   │   └── .algokit.toml
│   └── project2
│       └── .algokit.toml

The workspace configuration file is defined as follows:

# ... 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:

# ... 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

# ... 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:

Define order in .algokit.toml:

[project]
type = 'workspace'
projects_root_path = 'projects'

[project.run]
hello = ['project_a', 'project_b']

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:

Use command-line options:

$ algokit project run hello -s  # or --sequential
$ algokit project run hello -c  # or --concurrent

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:

$ 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.