@meshcore/cli/README.md

Official CLI for managing AI agents in MeshCore.ai with LLM-powered metadata extraction

# 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](https://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)

```bash
# 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)

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

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# List all your agents
mesh agent list

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

# Output as JSON
mesh agent list --json
```

#### Update Agent

```bash
# 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

```bash
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.

```bash
# 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

```bash
# 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

```bash
# 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

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

### Real-World Example: Creating a Tool Agent

```bash
# 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

```bash
# 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`

## Contributing

This project is open source and we welcome contributions! 🎉

### Ways to Contribute
- 🐛 **Report bugs**: [Create an issue](https://github.com/MeshCore-ai/mesh-cli/issues/new/choose)
- 💡 **Suggest features**: [Request a feature](https://github.com/MeshCore-ai/mesh-cli/issues/new/choose)  
- 🔧 **Submit code**: [Create a pull request](https://github.com/MeshCore-ai/mesh-cli/pulls)
- 📖 **Improve docs**: Help make the documentation better

### Development Setup
```bash
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](https://github.com/MeshCore-ai/mesh-cli/blob/main/CONTRIBUTING.md) for detailed guidelines.

## License

MIT - See [LICENSE](https://github.com/MeshCore-ai/mesh-cli/blob/main/LICENSE)