Skip to main content

​
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. 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

  1. 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.
  2. 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]"
  3. 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: 
# Test a chatbot
meshagent chatbot join --room testroom --agent-name myagent

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

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

Expose your agent/tool via ServiceHost (local webhook server). A request from MeshAgent spins up your agent, connects it to the Room, and manages lifecycle for the session. 
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="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="/chat", identity="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())
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. 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. Once you’ve packaged the agent you can deploy it from the CLI to a 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, checkout the Deploying a ChatBot as a Project Service guide where you’ll learn how to build and deploy a chat agent as a project wide service. If your docker image is not public, then you will need to configure a secret so that the image can be pulled. 
meshagent 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 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
CommandWhat it does
meshagent setupAuthenticate to MeshAgent and activate a project
meshagent agents list-agentsList agents currently connected to a specific room
meshagent chatbot join --room=myroom --agent-name=chatbotJoin a room with the built-in chatbot
meshagent voicebot join --room=myroom --agent-name=voicebotJoin a room with the built-in voicebot
meshagent service run "main.py" --room=myroomTest a service locally
meshagent service create --file=meshagent.yamlDeploy an agent as a managed service
meshagent service listView deployed project services

​
Next Steps