Scripting

You can write scripts that run using the ape run command. The ape run command will register and run Python files defined under the scripts/ directory that do not start with an _ underscore.

CLI Scripts

Place scripts in your project’s scripts/ directory. Follow this guide to learn more about the Ape project structure. If your scripts take advantage of utilities from our ape.cli submodule, you can build a Click command line interface by defining a click.Command or click.Group object called cli in your file:

import click

@click.command()
def cli():
    print("Hello world!")

Assume we named the script helloworld.py. To execute the script, run the following:

ape run helloworld

You can also execute scripts in subdirectories. For example, assuming we have script <project>/scripts/hello/helloworld.py, we would execute it by running:

ape run hello helloworld

Note that by default, cli scripts do not have ape.cli.network_option installed, giving you more flexibility in how you define your scripts. However, you can add the network_option to your scripts by importing both the NetworkBoundCommand and the network_option from the ape.cli namespace:

import click
from ape.cli import network_option, NetworkBoundCommand


@click.command(cls=NetworkBoundCommand)
@network_option()
def cli(network):
    click.echo(f"You are connected to network '{network}'.")

Assume we saved this script as shownet.py and have the ape-alchemy plugin installed. Try changing the network using the --network option:

ape run shownet --network ethereum:mainnet:alchemy

Main Method Scripts

You can also use the main-method approach when defining scripts. To do this, define a method named main() in your script:

def main():
    print("Hello world!")

NOTE: main-method scripts will always provide a network option to the call and thus will always connect to a network.

To demonstrate, use the following script:

from ape import networks
import click


def main():
    ecosystem_name = networks.provider.network.ecosystem.name
    network_name = networks.provider.network.name
    provider_name = networks.provider.name
    click.echo(f"You are connected to network '{ecosystem_name}:{network_name}:{provider_name}'.")