MeshCore CLI

A command-line interface for managing AI agents in MeshCore.ai with LLM-powered metadata extraction.

🌟 Open Source: This CLI is open source! Contribute, report issues, or suggest features at github.com/MeshCore-ai/mesh-cli

Features

• Authentication: Secure login with authentication token
• Agent Management: Full CRUD operations for agents with multiple agent types (AGENT, TOOL, LLM)
• Team Management: Automatic team selection and team ID persistence
• AI Metadata Generation: Automatically extract agent metadata from README files using MeshCore API
• README Rewriter: AI-powered README transformation for mesh compatibility
• Interactive Editing: Enhanced metadata editing with real-time preview, agent type selection, and documentation editing
• Smart Fallbacks: Intelligent error handling with manual team ID input when needed
• Health Monitoring: Check agent health status
• User-Friendly: Intuitive prompts and visual feedback

Installation

From NPM (Recommended)

# Install globally
npm install -g @meshcore/cli

# Or with yarn
yarn global add @meshcore/cli

# Or with pnpm
pnpm add -g @meshcore/cli

From Source (Development)

git clone https://github.com/meshcore/mesh-cli.git
cd mesh-cli
npm install
npm run build
npm link  # Makes 'mesh' command available globally

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required environment variables:

• MESHCORE_API_URL: MeshCore API endpoint (default: https://112a8efaa53c.ngrok-free.app/agent-mesh-api)
• MESHCORE_TOKEN: Your MeshCore authentication token

Note: AI metadata generation is now handled by MeshCore API - no local LLM configuration needed!

Usage

Authentication

# Login with authentication token
mesh auth login

# Login with token directly
mesh auth login --token YOUR_TOKEN

# Check authentication status
mesh auth status

# Logout
mesh auth logout

Configuration Management

# View current configuration
mesh config

# Shows authentication status, API URL, team preferences, and README settings

The configuration now displays:

• Authentication status
• Default team ID (saved for future agent creation)
• README auto-rewrite settings
• Registered tools count

Agent Management

Create Agent from README

# Extract metadata from README using AI
mesh agent create ./path/to/project

# Create agent and auto-rewrite README for mesh compatibility
mesh agent create ./path/to/project --auto-rewrite

# Create with specific original API URL
mesh agent create ./path/to/project --auto-rewrite --original-url "https://api.example.com"

# Create from specific documentation file
mesh agent create ./docs/API.md

# Manual creation with prompts
mesh agent create --interactive

# Create with specific agent type and details
mesh agent create --name "My Tool" --description "FastAPI tool" --category "utilities"

Agent Types Supported:

• AGENT: General-purpose AI agents
• TOOL: Specialized tools and APIs (like the runway-api example)
• LLM: Large Language Models

The CLI automatically:

• Detects project type and extracts metadata from README files
• Generates clean markdown documentation (when supported by API)
• Allows interactive editing of agent type, metadata, and documentation
• Handles team selection (fetches teams or prompts for manual team ID)
• Saves team preferences for future agent creation
• Provides smart fallbacks when API permissions are limited
• Validates field lengths (name: 1-100 chars, description: 1-1000 chars)

List and View Agents

# List all your agents
mesh agent list

# Get agent details
mesh agent get <agent-id>

# Output as JSON
mesh agent list --json

Update Agent

# Update from README
mesh agent update <agent-id> --from-readme ./README.md

# Update specific fields
mesh agent update <agent-id> --name "New Name" --description "New description"

Delete Agent

mesh agent delete <agent-id>

# Skip confirmation
mesh agent delete <agent-id> --force

README Rewriting

Transform your existing README files to be compatible with MeshCore gateway URLs and usage patterns.

# Rewrite README for an existing agent
mesh rewrite-readme rewrite --agent-id <agent-id> --input ./README.md

# Rewrite with specific output file
mesh rewrite-readme rewrite --agent-id <agent-id> --input ./README.md --output ./README.mesh.md

# Rewrite with original API URL specified
mesh rewrite-readme rewrite --agent-id <agent-id> --input ./README.md --original-url "https://api.example.com"

# Detect original API URL from README
mesh rewrite-readme detect-url --input ./README.md

# Restore original README from backup
mesh rewrite-readme restore --agent-id <agent-id> --file ./README.md

Health Checks

# Check specific agent health
mesh health check <agent-id>

# Check all agents health
mesh health check-all

AI Features

The CLI uses MeshCore's AI service for intelligent documentation processing:

Metadata Extraction

1. Automatic Detection: Finds README files, package.json, and other project files
2. Smart Extraction: Identifies name, description, category, and capabilities
3. Pricing Suggestions: Recommends appropriate pricing models
4. Interactive Review: Always allows editing before submission

README Rewriting

1. Gateway URL Transformation: Converts original API endpoints to MeshCore gateway URLs
2. Usage Example Updates: Rewrites code examples and curl commands
3. Compatibility Enhancement: Adds MeshCore-specific usage instructions
4. Original URL Detection: Automatically identifies API endpoints from existing documentation

Supported Documentation Sources

• README.md files
• Package.json for Node.js projects
• API documentation
• Any markdown documentation file

Examples

Quick Start

# 1. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 2. Login
mesh auth login

# 3. Create agent from existing project with README rewriting
mesh agent create ./my-ai-project --auto-rewrite

# 4. List your agents
mesh agent list

# 5. Manually rewrite README later (if needed)
mesh rewrite-readme rewrite --agent-id <agent-id> --input ./README.md

Creating Agent with Full Control

mesh agent create \
  --name "My AI Assistant" \
  --description "Intelligent task automation agent" \
  --category "automation"

Real-World Example: Creating a Tool Agent

# Create a TOOL-type agent from a FastAPI project
mesh agent create ./path/to/runway-api

# The CLI will:
# 1. Parse the README.md and extract metadata
# 2. Show generated metadata with type defaulting to AGENT
# 3. Allow you to edit the type to TOOL
# 4. Handle team selection (or prompt for team ID)
# 5. Create the agent with type: TOOL

# Result: Successfully created tool agent for API integration
# Agent ID: bba446ec-4b5c-4970-a976-897670aad2f7
# Name: Runway ML API Connector
# Type: TOOL

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

Project Structure

mesh-cli/
├── src/
│   ├── commands/       # CLI command implementations
│   ├── services/       # API and LLM services
│   ├── utils/          # Utility functions
│   └── types/          # TypeScript type definitions
├── dist/               # Compiled JavaScript
└── .env                # Environment configuration

Error Handling

The CLI provides clear error messages and intelligent fallbacks:

• Authentication errors: Prompt to login with clear instructions
• Network errors: Show connection issues and retry suggestions
• Validation errors: Display specific field requirements with examples
• Team permission errors: Fall back to manual team ID input with UUID validation
• AI metadata generation errors: Fall back to basic README extraction
• README rewriting errors: Suggest manual retry with specific agent ID
• API key permission errors: Explain role requirements and provide alternatives

Team Management Fallbacks

When the teams API requires higher privileges, the CLI will:

1. Detect the permission error (401/403)
2. Prompt for manual team ID entry with UUID validation
3. Offer to save the team ID for future use
4. Use the default team ID for subsequent agent creation

Example team ID format: c4450a80-78d0-4133-b09a-083c0255da97

Join Our Community

Connect with other developers building on MeshCore:

• 💬 Discord: Join our Discord server for discussions, support, and updates
• 🐦 Twitter: Follow @meshcore_ai for the latest news
• 🌐 Website: meshcore.ai

Contributing

This project is open source and we welcome contributions! 🎉

Ways to Contribute

• 🐛 Report bugs: Create an issue
• 💡 Suggest features: Request a feature
• 🔧 Submit code: Create a pull request
• 📖 Improve docs: Help make the documentation better

Development Setup

git clone https://github.com/MeshCore-ai/mesh-cli.git
cd mesh-cli
npm install
npm run build
npm link  # Test your changes globally

See CONTRIBUTING.md for detailed guidelines.

License

MIT - See LICENSE