Skip to main content

​
Overview

This guide covers common CLI workflows for day-to-day MeshAgent development. If you need account creation, project setup, and a first-run walkthrough, start with the Getting Started Guide first. This page focuses on the CLI itself: installing it, connecting it to MeshAgent, testing agents locally, and deploying them. 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. Create a MeshAgent account and project: Sign up and create a project in MeshAgent Studio.
  2. Install the MeshAgent CLI: You can install the CLI globally on your system or in a virtual environment. Option 1: Install the CLI globally 
    brew tap meshagent/homebrew-meshagent
# install the latest version
brew install meshagent
# Display the help
meshagent --help
    Option 2: 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. Connect the CLI to MeshAgent: 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
    You are now authenticated and ready to use the CLI!

​
Common Workflows

​
Test Agents Locally

Before deploying, test your agent locally in a room:

​
Start with meshagent process

meshagent process is the recommended CLI path when you want one agent identity that can grow across multiple channels. Start with one chat channel and give the agent a useful default tool setup: 
meshagent process join \
  --room testroom \
  --agent-name support-agent \
  --channel chat \
  --model gpt-5.4 \
  --web-search \
  --require-storage
Open MeshAgent Studio, join testroom, and start chatting with support-agent. If the same agent should accept work from more than chat, add more --channel flags: 
meshagent process join \
  --room testroom \
  --agent-name support-agent \
  --channel chat \
  --channel queue:triage \
  --model gpt-5.4 \
  --web-search \
  --require-storage \
  --threading-mode default-new \
  --thread-dir ".threads/support-agent"
This starts one logical agent with both a chat channel and a queue channel. For more complete examples, see Using Multi-channel Agents.
Tip: Use --help to see all available tools and options: meshagent process join --help.

​
Single-channel CLI agents

chatbot join and voicebot join still work today, and they are useful if you specifically want those built-in single-channel runtimes: 
# Built-in chatbot
meshagent chatbot join --room testroom --agent-name my-chatbot --model gpt-5.4 --web-search --storage

# Built-in voicebot
meshagent voicebot join --room testroom --agent-name my-voicebot
If you need custom Python or SDK-based behavior beyond CLI flags and rules, move to the custom service workflow later. See Run Your Service Locally when you are ready for that path.

​
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 a standard process-based agent, the fastest path is to deploy it directly:
bash
meshagent process deploy \
  --room myroom \
  --service-name support-agent \
  --agent-name support-agent \
  --channel chat \
  --model gpt-5.4 \
  --require-web-search \
  --require-storage
If you want to review or customize the manifest first, generate it and then deploy it yourself:
bash
meshagent process spec \
  --service-name support-agent \
  --agent-name support-agent \
  --channel chat \
  --model gpt-5.4 \
  --require-web-search \
  --require-storage > meshagent.yaml

# Deploy as a room service
meshagent service create --file meshagent.yaml --room myroom

# Deploy as a project service
meshagent service create --file meshagent.yaml --global
Inspect what is 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 Packaging and Deploying Services 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 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 key 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 process join --room=myroom --agent-name=agent --channel chatRun a process-based agent locally
meshagent process deploy --room=myroom --service-name=agent --agent-name=agent --channel chatDeploy a standard process-based agent directly
meshagent process spec --agent-name=agent --channel chat > meshagent.yamlGenerate a manifest you can customize
meshagent chatbot join --room=myroom --agent-name=chatbotRun the built-in single-channel chatbot
meshagent voicebot join --room=myroom --agent-name=voicebotRun the built-in single-channel voicebot
meshagent service listView deployed project services
meshagent service show <service-id>Show one deployed service

​
Next Steps