> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.agentverse.ai/v-2/llms.txt
> - v1: https://docs.agentverse.ai/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentverse.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentverse.ai/_mcp/server.

# Agentverse CLI

The **Agentverse CLI** is a command-line tool for managing your [Hosted Agents](/documentation/create-agents/hosted-agents) on [Agentverse](https://agentverse.ai/) 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

**`copy`**

```bash copy
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**:

**`copy`**

```bash copy
brew install fetchai/avctl/avctl
```

### Windows

Run the installation script in **PowerShell**:

**`copy`**

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

Or use **Chocolatey**:

**`copy`**

```bash copy
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:

   ```copy
   mkdir myagent
   cd myagent
   ```

   > **Note**
   >
   > To *create* a new Agent:
   >
   > ```copy
   > avctl hosting init
   > ```
   >
   > To *retrieve* an existing Agent from Agentverse:
   >
   > ```copy
   > 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:

   ```copy
   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:

   ```copy
   AGENT_ADDRESS={{ .AgentName.Address }}
   ```

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

   ```copy
   avctl hosting init --workspace
   ```

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

4. Deploy the workspace with:

   ```copy
   avctl hosting deploy
   ```

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

> **Note**
>
> Use either an individual Agent configuration or a workspace configuration for a project. They cannot be used together. If you switch between them, remove the existing `.avctl/config.toml` before initializing the new configuration.

## AVCTL Commands

### Main Commands

A full list of commands is available below:

| Command          | Purpose                                   |
| ---------------- | ----------------------------------------- |
| `hosting init`   | Create a new Agent from a template        |
| `hosting pull`   | Download an existing Agent                |
| `hosting push`   | Upload local changes                      |
| `hosting sync`   | Synchronize local and Agentverse versions |
| `hosting deploy` | Deploy or update an Agent                 |
| `hosting run`    | Run an Agent locally                      |
| `hosting logs`   | View Agent logs                           |
| `hosting stop`   | Stop a running Agent                      |

### 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:

| Command                  | Purpose             |
| ------------------------ | ------------------- |
| `hosting add secrets`    | Add a secret        |
| `hosting get secrets`    | List stored secrets |
| `hosting delete secrets` | Delete a secret     |