Tool Run is a scalable way to build your tool and test it in real-time. With this feature, it's simple to debug problems and create a tool that is both scalable and performant at the same time.

First, you need to have your tool. If you don't know how to create a tool or still have questions about this subject, you can read the tools page Tools.

Next, you need to write your test. Let's take the following tool as an example:

Notice that my tool has a specific parameter called "cep". Therefore, the expected input for this tool to be processed is a postal code. This way, I'll create a test file for this tool in the same directory as the specific tool code.

My test file would look something like this:

test_definition.yaml:

Make sure that path_test corresponds to the correct path of your tool test.

It's also important to note that if your tool uses any external libraries, you must include a requirements.txt file in the same directory as your tool code. This file should list all the dependencies needed for your tool to run properly.

Following the previous steps, we can now run a test, but how?

The command works as follows:

A practical example of the command considering the agent definition that was mentioned above would be:

Result:

An error occurred while loading the image https://github.com/vtexdocs/dev-portal-content/main/docs/guides/Weni-by-VTEX/CLI/assets/run-no-v.png

There is also a variation of this command in case you need to include ways to debug the code. You can add the -v argument at the end of the command to get more detailed logs of your tool, like this:

Choosing a test file

• Use -f/--file to specify a test definition YAML located in the tool folder.
• If -f is omitted, the CLI looks for test_definition.yaml in the tool's source.path directory.
• You can also set source.path_test in your agent definition to point to a custom test file; when present, the CLI uses that path by default.

Credentials and globals discovery

For development, the CLI will read optional files from the tool directory:

• .env for credentials exposed to your tool via context.credentials
• .globals for key/value pairs exposed via context.globals

Both files follow a simple KEY=VALUE per line format.

Result:

An error occurred while loading the image https://github.com/vtexdocs/dev-portal-content/main/docs/guides/Weni-by-VTEX/CLI/assets/run-with-v.png

When your tool needs to interact with external services that require authentication, you'll need to provide credentials during testing. The official method for handling credentials with weni run is using your agent definition and a .env file.

Using Agent Definition and .env File

This approach mimics how credentials work in production, making your local development environment consistent with deployment.

First, update your agent definition to include credentials:

Then, create a .env file inside the tool folder (e.g., tools/get_address/.env) with the actual credential values:

Now you can run your tool test with credentials using the same command:

The CLI will automatically pick up the credentials from the tool folder .env file and make them available to your tool during execution.

Accessing Credentials in Your Tool Code

Your tool code should access credentials through the Context object as shown below:

The key line is api_key = context.credentials.get("api_key"), which retrieves the credential value that was defined in your agent definition and stored in your tool folder .env file.

Important: Never hardcode credentials in your tool code. Always access them through the Context object to ensure your code remains secure and works consistently across different environments.