CLI Quickstart

Overview

This guide covers common CLI workflows for day-to-day MeshAgent development. If you haven’t set up MeshAgent yet, start with the Getting Started Guide first. This will walk you through creating a MeshAgent account, installing MeshAgent, and running your first agent from the CLI. The MeshAgent CLI streamlines Room interactions and agent management right from your terminal. With the MeshAgent CLI you can easily:

Authenticate and activate projects
Spin up live rooms and test your in progress agents and tools
Deploy services to your project or room
Inspect and manage existing projects, secrets, agents, and services

For a complete command reference, see MeshAgent CLI Commands documentation.

Before you begin

Set up MeshAgent: If you haven’t installed MeshAgent yet, follow our Getting Started guide. This will walk you through how to set up your MeshAgent account, create your first project, install MeshAgent, and connect to your first room with your first agent.
Install the MeshAgent CLI: You can install the CLI globally on your system or in a virtual environment. To install the CLI globally:
brew tap meshagent/homebrew-meshagent # install the latest version brew install meshagent # Display the help meshagent --help
To install the CLI in a virtual environment: Ensure you are in the appropriate project folder and have activated your virtual environment. (The virtual environment is active when the terminal prompt starts with venv.) If you need help with your machine setup check out our Machine Setup Guide for Python. Then you can install all the MeshAgent packages, or exclusively the MeshAgent CLI.
pip install "meshagent[cli]" # or "meshagent[all]"

Authenticate: Once the CLI is installed, authenticate and activate a project.

# A browser window will open for OAUTH.
meshagent setup
# Then you will be prompted to activate a project

Optional: Alternatively, instead of running the meshagent setup command you can run:

# A browser window will open for OAUTH.
meshagent auth login
meshagent project activate -i
# create an api key if necessary. The key value will be displayed only once.
meshagent api-key create --activate my-key

You are now authenticated and ready to use the CLI!

Common Workflows

Test Agents Locally

Before deploying, test your agent locally in a room:

Using CLI agents (no code required)

The MeshAgent CLI provides prebuilt ChatBot and VoiceBot agents you can test instantly:

# Authenticate to MeshAgent if not already signed in
meshagent setup

# Test a chatbot
meshagent chatbot join --room testroom --agent-name myagent

# Test a voicebot  
meshagent voicebot join --room testroom --agent-name myvoice

# Test a chatbot with tools enabled
meshagent chatbot join --room testroom --web-search --storage

Open MeshAgent Studio, join testroom, and start chatting with your agents.

Tip: Use --help to see all available tools and options: meshagent chatbot join --help. The CLI ChatBot has built in tools you can turn on and off for things like image generation, web search, local shell, and mcp.

Note: chatbot join / voicebot join are designed for local/dev usage. In containers or deployments, prefer chatbot service / voicebot service.

Run your own MeshAgent service locally

The CLI based agents expose many tools and functionality already, we recommend using these for most use cases. When you need additional custom functionality you can extend the base agent classes, for example the ChatBot. To run a custom agent or tool locally and deploy it, expose it via ServiceHost (local webhook server). A request from MeshAgent spins up your agent or tool, connects it to the Room, and manages it’s lifecycle for the session. For example, create a file called my_agent.py:

import asyncio
from meshagent.otel import otel_config
from meshagent.api.services import ServiceHost
from meshagent.agents.chat import ChatBot
from meshagent.openai import OpenAIResponsesAdapter

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="simple-chatbot")

# Create a service host
service = ServiceHost()  # optional to pass a port, MeshAgent automatically assigns an available one if none provideds

# Register an agent at a specific path
@service.path(path="/agent", identity="simple-chatbot")
class SimpleChatbot(ChatBot):
    def __init__(self):
        super().__init__(
            name="chatbot",
            title="Simple Chatbot",
            description="A helpful chatbot for room participants",
            rules=[
                "Always respond to the user first then include a fun fact at the end of your response."
            ],
            llm_adapter=OpenAIResponsesAdapter(),
        )

# Start the service
asyncio.run(service.run())

Then run the service locally with the MeshAgent CLI:

bash

# Run your agent code locally in a room
meshagent service run "my_agent.py" --room testroom

Open MeshAgent Studio, join testroom, and start chatting with your agent. You can iterate on the code and restart the service to test your changes (run Ctrl+C to stop the agent then rerun the meshagent service run command). The agent will only exist for the current session unless deployed.

Package and Deploy Services

Once your agent works locally, you’ll need to package and deploy it as a project or room service. You can do this from MeshAgent Studio or using the CLI. For example, let’s deploy a CLI based chatbot with the web search tool, image generation tool, and storage tool. First copy this meshagent.yaml file.

kind: Service # switch to service Template if installing from link for Powerboards
version: v1
metadata:
  name: chatbot
  description: "A simple chatbot that responds to users"
  annotations:
    meshagent.service.id: "meshagent.chatbot"
agents:
  - name: chatbot
    description: "A conversational agent with tools"
    annotations:
      meshagent.agent.type: "ChatBot"
ports:
- num: "*"                    # automatically assign an available MESHAGENT_PORT for the agent to run on 
  type: http
  liveness: "/"               # ensure the service is alive before connecting to the room
  endpoints:
  - path: /agent              # service path to call and run the agent on
    meshagent:
      identity: chatbot       # name of the agent as it shows up in the Room
container:
  image: "us-central1-docker.pkg.dev/meshagent-public/images/cli:{SERVER_VERSION}-esgz"
  command: "/usr/bin/meshagent chatbot service --agent-name=chatbot --image-generation=gpt-image-1 --require-storage --web-search --room-rules='agents/chatbot/rules.txt' --rule='You are a helpful assistant'"
  storage:
    room:
      - path: /data             # mount room storage path for the agent to write files to
        read_only: false        # allow write access 

Next, deploy it to your project or room.

bash

# Deploy as a project service (available in all rooms)
meshagent service create --file meshagent.yaml

# Deploy as a room service (specific room only)
meshagent service create --file meshagent.yaml --room myroom

Inspect what’s deployed:

# List project services
meshagent service list

# List services in a room
meshagent service list --room=myroom

# View service details (ID comes from list command)
meshagent service show <service-id> 

Use your deployed services in MeshAgent Studio in any of the rooms it was deployed to.

Manage Projects and Rooms

Switch projects:

# List projects
meshagent project list

# Activate a different project
meshagent project activate -i

Manage API keys:

# Create and activate a new API key
meshagent api-key create --activate my-new-key

# List API keys
meshagent api-key list

# Delete API keys
meshagent api-key delete <api-key-id>

Work with Secrets

Secrets allow you to store credentials securely for agents and services to use: When deploying a custom agent, you will need to build and push a docker image. For an example of this, check out Deploying a Custom ChatBot to see how to build and deploy a chat agent as a project or room service. If your docker image is not public, then you will need to configure a secret so that the image can be pulled.

meshagent room secret docker create --name my-image-secret --server index.docker.io --username my-username --password my-password

You can also create key-value based secrets (for API keys, etc.):

meshagent room secret keys create --name my-secret --data my-key=my-value

Logout

Rooms will spin down automatically after you leave and they are inactive. If you wish to logout you can run:

meshagent auth logout

Frequently used commands

Note you will need to fill in the appropriate parameters for these commands

Command	What it does
`meshagent setup`	Authenticate to MeshAgent and activate a project
`meshagent room agents list-toolkits`	List toolkits (including TaskRunner tool wrappers) available in a room
`meshagent chatbot join --room=myroom --agent-name=chatbot`	Join a room with the built-in chatbot
`meshagent voicebot join --room=myroom --agent-name=voicebot`	Join a room with the built-in voicebot
`meshagent service run "main.py" --room=myroom`	Test a service locally
`meshagent service create --file=meshagent.yaml`	Deploy an agent as a managed service
`meshagent service list`	View deployed project services

Next Steps

ChatBot: Tutorial on creating and customizing a MeshAgent ChatBot
Introduction to Services: Understand project and room services and how to run ad-hoc code in a Room through the Containers API
Packaging Services: Learn about meshagent.yaml configuration
Deploying Services: Learn how to deploy project and room services
CLI Commands Reference: Complete CLI command documentation
Secrets Management: Working with credentials and OAuth

Introduction

Room API

Project Administration

Agents

Tools

Observability

Services Runtime & Deployment

Secrets

Documents

UI SDKs

References

Overview

Before you begin

Common Workflows

Test Agents Locally

Using CLI agents (no code required)

Run your own MeshAgent service locally

Package and Deploy Services

Manage Projects and Rooms

Work with Secrets

Logout

Frequently used commands

Next Steps

Introduction

Room API

Project Administration

Agents

Tools

Observability

Services Runtime & Deployment

Secrets

Documents

UI SDKs

References

​Overview

​Before you begin

​Common Workflows

​Test Agents Locally

​Using CLI agents (no code required)

​Run your own MeshAgent service locally

​Package and Deploy Services

​Manage Projects and Rooms

​Work with Secrets

​Logout

​Frequently used commands

​Next Steps

Overview

Before you begin

Common Workflows

Test Agents Locally

Using CLI agents (no code required)

Run your own MeshAgent service locally

Package and Deploy Services

Manage Projects and Rooms

Work with Secrets

Logout

Frequently used commands

Next Steps