npm package: @myop/cli
Description: Myop cli
Latest version: 0.1.57

# @myop/cli

[![npm version](https://img.shields.io/npm/v/@myop/cli.svg)](https://www.npmjs.com/package/@myop/cli)
[![License](https://img.shields.io/npm/l/@myop/cli.svg)](https://github.com/myop/cli/blob/main/LICENSE)

> Command-line interface for building, developing, and managing Myop components

Myop CLI is a powerful developer tool for creating and managing remote UI components. Build once, deploy anywhere - components built with Myop can be consumed across different frameworks and platforms.

## Features

- 🚀 **Development Server** - Hot-reload enabled dev server with visual network monitoring
- 📊 **Visual Dashboard** - Real-time request tracking and architecture visualization
- 🔄 **Auto-sync** - Automatic component synchronization across multiple dev instances
- 🌐 **Proxy Fallback** - Seamless fallback to cloud-hosted components
- 📦 **Component Management** - Easy component registration and discovery
- 🎨 **Professional UI** - Chrome DevTools-inspired interface with zoom/pan capabilities

## Installation

```bash
npm install -g @myop/cli
```

Or use locally in your project:

```bash
npm install --save-dev @myop/cli
```

## Quick Start

### Initialize a New Component

```bash
# Create a new component
myop add

# Start development server
myop dev
```

### Development Workflow

1. **Start the dev server** in your component directory:
   ```bash
   myop dev
   ```

2. **Access the dashboard** at `http://localhost:9292`

3. **View your component** at `http://localhost:9292/view/<componentId>/`

4. **Make changes** - the server watches `.js` and `.css` files and rebuilds automatically

## Commands

### `myop dev`

Start the development server with file watching and hot-reload.

```bash
myop dev [options]
```

**Features:**
- Runs on ports `9292` (main) and `9293` (management)
- Watches `.js` and `.css` files for changes
- Automatic builds on file changes
- Visual dashboard with network architecture diagram
- Multiple instances can register with the same server
- Health monitoring with automatic failover

**Options:**
- `-c, --config <path>` - Path to myop.config.json (default: `./myop.config.json`)
- `-v, --verbose` - Enable verbose logging

### `myop add`

Add a new flow or component to your project.

```bash
myop add
```

Interactive prompt to add new components to your Myop configuration.

### `myop remove`

Remove a flow or component from your project.

```bash
myop remove
```

Interactive prompt to remove components from your configuration.

### `myop install`

Install dependencies and set up your Myop project.

```bash
myop install
```

### `myop export`

Export components as static JSON files for self-hosting. Fetches your components from the Myop cloud and writes them to a local directory.

```bash
# Full export — all components
myop export --api-key myop_sk_...

# Export to a specific directory
myop export --api-key myop_sk_... --output ./components

# Incremental export — only specific releases (used by CI/CD webhooks)
myop export --api-key myop_sk_... --releases '[{"componentId":"abc","environment":"production"}]'

# Single component export
myop export --api-key myop_sk_... --component abc --env production
```

**Options:**
- `-k, --api-key <key>` - Myop API key (or set `MYOP_API_KEY` env var)
- `-o, --output <dir>` - Output directory (default: `./myop-static`)
- `-u, --url <url>` - Myop API URL (or set `MYOP_API_URL` env var)
- `--releases <json>` - JSON array of releases for incremental sync
- `--component <id>` - Single component ID
- `--env <env>` - Environment (used with `--component`)

See the [Self-Hosting docs](https://docs.myop.dev/docs/self-hosting/) for setup guides and GitHub Actions workflows.

### `myop sync`

Synchronize your components with the Myop cloud.

```bash
myop sync
```

## Configuration

Create a `myop.config.json` in your project root:

```json
{
  "componentId": "your-component-id",
  "componentName": "My Component"
}
```

**Fields:**
- `componentId` (required) - Unique identifier for your component
- `componentName` (optional) - Human-readable name displayed in the dashboard

## Development Dashboard

The dev server includes a professional visual dashboard accessible at `http://localhost:9292`:

### Features

- **Network Architecture View**
  - Visual diagram showing request flow from origins → local server → cloud
  - Interactive nodes (drag to reposition)
  - Zoom and pan controls
  - Curved connection lines for better readability

- **Real-time Monitoring**
  - Live request tracking via Server-Sent Events (SSE)
  - Origin detection and grouping
  - Component request counts
  - Local vs. proxied request statistics

- **Component Registry**
  - All registered components with IDs and names
  - Direct links to component views
  - File paths for easy navigation

- **Activity Log**
  - Recent request history
  - Origin information
  - Timestamp tracking

## Architecture

### Multi-Instance Support

The dev server supports running multiple component instances simultaneously:

1. **First Instance** - Starts both main and management servers
2. **Additional Instances** - Register with the existing server
3. **Auto-Failover** - If the main server dies, another instance takes over

### Request Flow

```
Origin Request
    ↓
Local Dev Server (port 9292)
    ↓
Component Registered?
    ├─ Yes → Serve from local dist/
    └─ No  → Proxy to cloud.myop.dev
```

### File Structure

```
myop-cli/
├── src/
│   ├── myop-cli.js              # Main CLI entry point
│   ├── commands/
│   │   └── dev/                 # Dev command
│   │       ├── index.js         # Server logic
│   │       ├── README.md        # Dev command docs
│   │       └── management-website/
│   │           ├── index.js     # HTML generator
│   │           ├── styles.css   # Dashboard styles
│   │           └── app.js       # Client-side code
│   ├── operations/              # CLI operations
│   └── common/                  # Shared utilities
└── dist/                        # Built files (npm publish)
```

## API

### Consume Endpoint

```
GET /consume?id=<componentId>
```

Returns the component's HTML loader configuration. Serves from local dist if registered, otherwise proxies to cloud.

**Response:**
```json
{
  "item": {
    "id": "component-id",
    "name": "component-id",
    "consume_variant": [{
      "id": "variant-id",
      "name": "dev version",
      "loader": {
        "type": "HTMLLoader",
        "shadowRootMode": "localFrame",
        "HTML": "<html>...</html>"
      }
    }]
  }
}
```

### Management API (port 9293)

#### Register Component
```
POST /_register
Body: { "componentId": "id", "distPath": "/path", "componentName": "name" }
```

#### Unregister Component
```
POST /_unregister
Body: { "componentId": "id" }
```

#### List Components
```
GET /_list
Response: { "components": [[id, {path, name}], ...] }
```

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/myop/cli.git
cd cli

# Install dependencies
npm install

# Build
npm run build

# Test locally
./dist/myop-cli.js dev
```

### Project Structure

The CLI is built with Vite and uses ES modules. Key technologies:

- **Commander.js** - CLI framework
- **Inquirer** - Interactive prompts
- **Ora** - Terminal spinners
- **Native Node.js APIs** - HTTP server, file watching, child processes

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:

- Code of Conduct
- Development workflow
- Submitting pull requests
- Coding standards

## Troubleshooting

### Port Already in Use

If ports 9292 or 9293 are already in use:

```bash
# Find process using the port
lsof -i :9292

# Kill the process
kill -9 <PID>
```

### Component Not Found

Ensure your `myop.config.json` exists and contains a valid `componentId`:

```bash
cat myop.config.json
```

### Build Errors

Clear the dist folder and rebuild:

```bash
rm -rf dist node_modules
npm install
npm run build
```

## License

[LICENSE](LICENSE)

## Links

- [Homepage](https://myop.dev)
- [Documentation](https://docs.myop.dev)
- [GitHub Issues](https://github.com/myop/cli/issues)
- [NPM Package](https://www.npmjs.com/package/@myop/cli)

## Support

- 📧 Email: support@myop.dev
- 💬 Discord: [Join our community](https://myop.dev/discord)
- 🐛 Issues: [GitHub Issues](https://github.com/myop/cli/issues)

---

Made with ❤️ by the Myop team