Agentverse CLI

The Agentverse CLI is a command-line tool for managing your Hosted Agents on Agentverse from your terminal. It is also known as AVCTL (Agentverse Control).

It allows you to create and retrieve Agents from Agentverse, synchronize local changes, run Agents locally, and deploy them to Agentverse.

Install AVCTL

Install AVCTL on your operating system using one of the following methods.

macOS and Linux

curl -fsSL https://github.com/fetchai/avctl/releases/latest/download/install.sh | sh

To install a specific version, set AVCTL_VERSION to the desired version number, such as v0.1.17 (e.g., AVCTL_VERSION=v0.1.17).

You can also use Homebrew:

brew install fetchai/avctl/avctl

Windows

Run the installation script in PowerShell:

Invoke-WebRequest -UseBasicParsing https://github.com/fetchai/avctl/releases/latest/download/install.ps1 | Invoke-Expression

Or use Chocolatey:

choco install avctl

Check that AVCTL is installed with avctl version.

Sign in

Before managing Agents, connect AVCTL to your Agentverse account using avctl auth login.

Your browser will open, so you can sign in with your account.

If you are working in a remote environment, use avctl auth login --no-browser to receive a sign-in URL that you can open in your browser.

You can check your current authentication status with avctl auth status.

Manage a single Agent

1. Sign in to Agentverse: avctl auth login

2. Set up your Agent by creating a project folder:

   mkdir myagent
   cd myagent
   To create a new Agent:

   avctl hosting init

   To retrieve an existing Agent from Agentverse:

   avctl hosting pull -a <agent_address>

   You can find your Agent addresses with avctl hosting get agents.

   After pulling an existing agent, you can proceed to run any of the commands listed below in this guide.

3. Once you are satisfied with your Agent, you can deploy your Agent to Agentverse using avctl hosting deploy. If the Agent is already deployed, this updates and restarts it.

Manage multiple Agents

1. Sign in to Agentverse: avctl auth login

2. Set up your Agent by creating a project folder containing all the Agents you have in mind for your project. This folder will define your workspace:

   mkdir myworkspace
   cd myworkspace

   A workspace is simply a folder containing multiple Agent projects. Each Agent folder should contain:

   • agent.py — the Agent’s main code.
   • pyproject.toml — the packages and dependencies required by the Agent.
   • .env — configuration values, including references to other Agents the Agent depends on.

   For example, if one Agent needs to communicate with another, its .env file can contain the other Agent’s address:

   AGENT_ADDRESS={{ .AgentName.Address }}

3. From the project folder, initialize your workspace using:

   avctl hosting init --workspace

   This way, AVCTL will detect the Agents and their dependencies and consequently configure the workspace.

4. Deploy the workspace with:

   avctl hosting deploy

   AVCTL deploys the Agents in the correct order based on their dependencies.

AVCTL Commands

Main Commands

A full list of commands is available below:

Manage secrets

AVCTL can also manage secrets used by your Agents. You can add, view, or delete secrets without storing their values directly in your Agent code: