CLI Commands

The following sections describe the CLI commands available to bot developers. You can always use forta-agent help to get a quick overview of these commands, as well as details about specific commands e.g. forta-agent run help.

Invoke commands programmatically

You can invoke the available CLI commands programmatically in NodeJS using the exported configureContainer method. This method returns a dependency injection container that can be used to access different commands. It accepts an optional object of arguments that will configure its behaviour, the most important of which is contextPath which points to the bot directory that you are running commands for (defaults to current working directory if not specified). For example, if you wanted to invoke the init command it would look like the following:

const { configureContainer } = require("forta-agent");

const pathToBotDirectory = "/Desktop/my-bot";
const container = configureContainer({ contextPath: pathToBotDirectory });
const init = container.resolve("init");
await init();

The above code snippet will initialize a Forta bot at the specified contextPath (creating the folder if it does not exist). All the CLI commands are asynchronous so you will need to await them. Similarly, you can resolve other commands that are listed below.

Exposing the CLI functionality enables developers to integrate with other tools. The first example of such an integration is the Forta Hardhat plugin. We look forward to seeing the new and creative ways developers will integrate this functionality into their own toolset!

init

Using the npx forta-agent@latest init command, you can quickly initialize a Forta bot Javascript project inside of the current working directory. The starter project includes some default configuration files as well as an example bot implementation. A keyfile and forta.config.json file will also be generated for you and placed in the ~/.forta folder if they do not already exist. You will be prompted to enter a password that will be used to encrypt the keyfile. This keyfile will be used later when publishing your bot.

Options:

--typescript - initialize Typescript project
--python - initialize Python project

Example: Initialize a Typescript Project

$ npx forta-agent@latest init --typescript

run

Easily verify the behaviour of your bot during local development using the forta-agent run command. The default behaviour (i.e. without any options) is to subscribe to a JSON-RPC endpoint and listen for the latest blocks and transactions. A stream of the latest data will be passed to your bot with any findings printed to your output console. The endpoint is specified by the jsonRpcUrl property in the forta.config.json file.

Options:

--tx - run your bot with a specific transaction hash
--block - run your bot against a specific block number/hash, including the transactions in the block
--alert - run your bot against a specific Forta alert hash
--sequence - run your bot against a sequence of tx/block/alert events
--range - run your bot against a specific range of block numbers
--file - run your bot against a JSON file of test data
--prod - used for running the bot inside of a production environment i.e. you probably won’t need this during development
--config - specify a config file to use (default: ~/.forta/forta.config.json)
--nocache - disables writing block/tx data to local disk cache (but reads are still enabled)

Example: Run a specific transaction (or a comma-delimited list)

$ forta-agent run --tx 0xf9c43e15ef2abfec163ec3b1165f18a5119ba119b6e059fc924903e5251e3543