Weni-CLI

Weni CLI is a highly powerful tool for creating customized AI multi-agents. This command-line interface enables developers to build, deploy, and manage sophisticated AI agents with tailored tools and functionalities across various communication channels. With Weni CLI, you can rapidly prototype, develop, and deploy agents that perfectly match your business requirements and use cases.

For comprehensive guidance and detailed documentation, we strongly recommend visiting our official documentation: https://weni-ai.github.io/weni-cli/

Overview

A command-line interface (CLI) tool to manage and interact with projects on the Weni platform.

Requirements

Python >= 3.10
Poetry >= 1.8.5

Installation

Install via PIP

You can install the CLI directly using pip:

pip install weni-cli

Manual Installation

Clone the repository:

git clone https://github.com/weni-ai/weni-cli.git
cd weni-cli

Install dependencies and make the CLI executable:
```
poetry shell
poetry install
```

Quick Start [Step by Step]

After setting up your environment, follow these steps to create your first agent:

weni login

This will open your browser for authentication. After successful login, you can close the browser tab.

2. List Available Projects

weni project list

This command will show all projects you have access to. Note down the UUID of the project you want to work with.

3. Select Your Project

weni project use your-project-uuid

Replace your-project-uuid with the UUID from the project list.

4. Verify Current Project

weni project current

This ensures you're working with the correct project.

5. Create Your Agent Definition

Create a file named agent_definition.yaml with this content:

agents:
  sample_agent:
    name: "CEP Agent"
    description: "Weni's sample agent"
    instructions:
      - "You are an expert in providing addresses to the user based on a postal code provided by the user"
      - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
    guardrails:
      - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
    tools:
      - get_address:
          name: "Get Address"
          source: 
            path: "tools/get_address"
            entrypoint: "main.GetAddress"
          description: "Function to get the address from the postal code"
          parameters:
            - cep:
                description: "postal code of a place"
                type: "string"
                required: true
                contact_field: true

6. Create Your tool Folder

Create a folder for your tool:

mkdir -p tools/get_address

7. Create the tool Class

Create a file in tools/get_address named main.py with this content:

from weni import Tool
from weni.context import Context
from weni.responses import TextResponse
import requests


class GetAddress(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        address_response = self.get_address_by_cep(cep=cep)
        return TextResponse(data=address_response)

    def get_address_by_cep(self, cep):
        url = f"https://viacep.com.br/ws/{cep}/json/"
        response = requests.get(url)
        return response.json()

Make sure the file folder matches the path specified in your agents.yaml file.

7.1 Create the requirements.txt file

Create a requirements.txt file in the same folder as your tool with the necessary dependencies:

requests==2.32.3

8. Upload Your Agent

weni project push agent_definition.yaml

That's it! You've just created your first agent with a custom tool using Weni-CLI.

The agent will now be able to:

Receive a CEP (postal code) from the user
Call the ViaCEP API through your tool
Return the address information to the user

Features

Login: Authenticate with Weni to access your projects.
List projects: View a list of all projects available in your account.
Select project: Set the project to be used by the CLI.
Current project: Display information about the currently selected project.
Push project definition: Upload the agents definition file to the selected project.
Agent evaluation: Initialize and run agent evaluations with weni eval.

Usage

weni login

This will open your default browser for authentication. After successful login, you can close the browser tab.

2. List projects

View all projects associated with your account:

weni project list

3. Select project

Choose the project you want to work with:

weni project use <project-uuid>

Replace <project-uuid> with the UUID of your project from the list command.

4. View current project

Check the currently configured project:

weni project current

5. Push project definition

Upload a YAML definition file to the configured project:

weni project push <definition_file.yaml>

Replace <definition_file.yaml> with the path to your YAML definition file.

6. Initialize an evaluation plan

Create an agent_evaluation.yml test plan in the current directory:

weni eval init

This generates a file where you only need to define your tests:

tests:
  greeting:
    steps:
      - Send a greeting message to the agent
    expected_results:
      - Agent responds with a friendly greeting

You can also choose a directory:

weni eval init --plan-dir <path_to_directory>

7. Run agent evaluation

Run all tests from agent_evaluation.yml:

weni eval run

Common options:

# Run only specific tests
weni eval run --filter "greeting,checkout_flow"

# Verbose output with detailed reasoning
weni eval run --verbose

# Custom plan directory
weni eval run --plan-dir <plan_directory>

Agent Definition File Structure

Below is an example of a valid agent definition file structure:

agents:
  sample_agent:
    name: "Sample Agent"                                                                      # Maximum of 55 characters
    description: "Weni's sample agent"
    instructions:
      - "You should always be polite, respectful and helpful, even if the user is not."       # Minimum of 40 characters
      - "If you don't know the answer, don't lie. Tell the user you don't know."              # Minimum of 40 characters
    guardrails:
      - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."  # Minimum of 40 characters
    tools:
      - get_order_status:
          name: "Get Order Status"                                                            # Maximum of 40 characters
          source: 
            path: "tools/order_status"
            entrypoint: "main.GetOrderStatus"
          description: "Function to get the order status"
          parameters:
            - order_id:
                description: "Order ID"
                type: "string"
                required: true
      - get_order_details:
          name: "Get Order Details"                                                           # Maximum of 40 characters
          source: 
            path: "tools/order_details"
            entrypoint: "main.GetOrderDetails"
          description: "Function to get the order details"
          parameters:
            - order_id:
                description: "Order ID"
                type: "string"
                required: true

## Examples

- Log in and list projects:
  ```bash
  weni login
  weni project list

Set and check the current project:

weni project use 12345678-1234-1234-1234-123456789012
weni project current

Push a definition file:
```
weni project push definition.yaml
```

Contributing

Contributions are welcome! Follow the steps below to contribute:

Fork the repository.
Create a branch for your feature or bug fix:
```
git checkout -b my-feature
```

Commit your changes:

git commit -m "Description of my feature"

Push your branch:
```
git push origin my-feature
```
Open a Pull Request in the original repository.

Metadata

Release files for weni-cli 3.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for weni-cli 3.9.0
File	Size	Uploaded	Provenance
weni_cli-3.9.0.tar.gz	66.8 kB	Oct 16, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for weni-cli 3.9.0
File	Interpreter	ABI	Platform	Reset
weni_cli-3.9.0-py3-none-any.whl 83.4 kB Oct 16, 2026 Without provenance	Python 3	none	any	Details

Total release size: 150.3 kB

Release files / weni_cli-3.9.0.tar.gz

Download URL	weni_cli-3.9.0.tar.gz
Size	66.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`6b482eacebde80f2e3045c93c615dfb558042355b09fd6b01f6571373134fd0a`
BLAKE2b-256 checksum How to use checksums	`d63998203ab03d3a01bfe4f33368e1ab3ca20461ab367bcc38d842c70a54ebc1`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.12.15 Linux/6.17.0-1022-azure`

Release files / weni_cli-3.9.0-py3-none-any.whl

Download URL	weni_cli-3.9.0-py3-none-any.whl
Size	83.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a90093bcf922dab55524fbe432b8509f47d7f17f0cccd7c7a72a4c31169ea5c9`
BLAKE2b-256 checksum How to use checksums	`b7511d75b5f56d8d75a6043f42e5c20812ad32c7d46f73733057ee7083845a03`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.12.15 Linux/6.17.0-1022-azure`

Security for weni-cli 3.9.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.