# TagadaPay Plugin CLI Documentation

[![npm version](https://badge.fury.io/js/%40tagadapay%2Fplugin-cli.svg)](https://badge.fury.io/js/%40tagadapay%2Fplugin-cli)
[![npm downloads](https://img.shields.io/npm/dm/@tagadapay/plugin-cli.svg)](https://www.npmjs.com/package/@tagadapay/plugin-cli)

A powerful modular CLI tool for deploying and managing plugins, React apps, and static websites on the TagadaPay platform with advanced routing capabilities.

**Latest Version: 2.2.0** - [View Changelog](#changelog)

## Table of Contents

- [Quick Start](#quick-start)
- [Architecture](#architecture)
- [Commands Reference](#commands-reference)
- [Interactive Mode](#interactive-mode)
- [Deployment Management](#deployment-management)
- [Domain Management](#domain-management)
- [Configuration](#configuration)
- [White-Label & Custom Base URL](#white-label--custom-base-url)
- [Changelog](#changelog)

## Quick Start

### 🚀 **Interactive Mode (Recommended)**

The CLI features a powerful interactive mode for easy deployment management:

```bash
# Install globally (latest version)
npm install -g @tagadapay/plugin-cli@latest

# Login to TagadaPay
tgdcli login

# Interactive deployment manager (best experience)
tgdcli int

# Interactive deploy with configuration
tgdcli ideploy

# Interactive mount to alias or custom domain
tgdcli imount

# Interactive list with tree view
tgdcli ilist
```

> **💡 Tip**: Make sure you're using the latest version (`2.2.0`) to access all features including White-Label Support and Clean Remove functionality. Run `npm install -g @tagadapay/plugin-cli@latest` to update.

### ⚡ **Command Line Mode (Advanced)**

For automation and advanced users:

```bash
# Deploy with explicit options
tgdcli deploy --store-id store123 --plugin-id my-app --name "My App"

# Deploy React project with auto-detection
tgdcli deploy --react --store-id store123 --plugin-id my-react-app --name "My React App"

# Mount existing deployment to alias
tgdcli mount-alias dep_abc123 my-alias

# List all deployments
tgdcli list --store-id store123

# White-label / Custom domain (for partners like Apptics)
tgdcli deploy --base-url crm.apptics.ai --store-id store123
```

## Architecture

### 🏗️ **Modular Design**

The CLI is built with a clean, modular architecture:

```
src/
├── services/           # Business logic services
│   ├── AuthService     # Authentication & session management
│   ├── ConfigService   # Configuration loading & validation
│   ├── DeploymentService # Deployment & build operations
│   ├── DomainService   # Custom domain management
│   └── InteractiveService # Interactive flow orchestration
├── commands/           # CLI command handlers
│   ├── AuthCommands    # login, logout, whoami
│   ├── DeployCommands  # deploy, init
│   ├── DomainCommands  # domain management
│   └── InteractiveCommands # interactive flows
└── types/             # Shared TypeScript interfaces
```

**Key Benefits:**

- 🧩 **Single Responsibility**: Each service has one clear purpose
- 🔄 **No Duplication**: Interactive mode reuses command logic
- 🧪 **Easy Testing**: Services can be tested in isolation
- 📈 **Maintainable**: Find and fix issues quickly
- 🚀 **Extensible**: Add new features without breaking existing ones

### 🎯 **Plugin Deployment System**

The CLI manages deployments with advanced routing capabilities:

- 🎯 **Multiple deployments** can share the same domain
- 🏷️ **Alias mounting** for easy access (`my-app--store123.cdn.tagadapay.com`)
- 🌐 **Custom domain mounting** for production use
- 🔄 **Route management** with pattern matching and exclusions
- 📊 **Deployment tracking** with detailed mount information

## Commands Reference

### 🔐 **Authentication**

```bash
# Login to TagadaPay (production by default)
tgdcli login

# Login to specific environment
tgdcli login --dev          # Development environment
tgdcli login --local        # Local environment
tgdcli login --prod         # Production environment (default)

# Login to white-label CRM (for partners like Apptics)
tgdcli login --base-url crm.apptics.ai

# Check current authentication
tgdcli whoami

# Logout
tgdcli logout
```

### 🚀 **Deployment**

```bash
# Basic deployment
tgdcli deploy --store-id store123 --plugin-id my-app --name "My App"

# React project deployment
tgdcli deploy --react --store-id store123 --plugin-id my-react-app --name "My React App"

# Initialize new plugin project
tgdcli init my-plugin "My Plugin" --mode direct-mode

# List deployments
tgdcli list --store-id store123

# Remove specific deployment
tgdcli remove-deployment dep_abc123

# Remove all deployments for a store
tgdcli remove-all-deployments --store-id store123 --force

# Deploy to custom base URL (white-label)
tgdcli deploy --base-url crm.apptics.ai --store-id store123 --plugin-id my-app
```

### 🎯 **Mounting & Routing**

```bash
# Mount deployment to alias
tgdcli mount-alias dep_abc123 my-alias

# Interactive mount (alias or custom domain)
tgdcli imount --store-id store123

# List all routes for a store
tgdcli routes --store-id store123

# Clean all routes for a store
tgdcli clean-routes --store-id store123 --force

# Unmount all deployments
tgdcli unmount-all --store-id store123 --force
```

## Interactive Mode

### 🎛️ **Interactive Deployment Manager**

The best way to manage deployments with a full-featured interface:

```bash
# Start interactive deployment manager
tgdcli int --store-id store123

# Interactive manager with environment selection
tgdcli int --store-id store123 --dev

# Interactive manager with custom base URL (white-label)
tgdcli int --base-url crm.apptics.ai --store-id store123
```

**Features:**

- 📋 **Deployment List**: View all deployments with mount information
- 🚀 **Deploy**: Create new deployments with guided setup
- 🎯 **Mount**: Mount deployments to aliases or custom domains
- 🗑️ **Clean Remove**: Safely remove deployments and ALL attached routes (NEW in v2.1.0)
- 🧹 **Unmount**: Remove individual aliases or custom domains
- 🌳 **Tree View**: Visual representation of routes and mounts

### 🚀 **Interactive Deploy**

Guided deployment with configuration options:

```bash
# Interactive deploy with configuration
tgdcli ideploy --store-id store123

# Interactive deploy for React projects
tgdcli ideploy --react --store-id store123
```

**Process:**

1. **Build Detection**: Auto-detects build directory (`dist`, `build`, `out`)
2. **Plugin Configuration**: Set plugin ID and display name
3. **Alias Selection**: Choose custom alias for easy access
4. **Config File**: Optional JSON configuration injection
5. **Deployment**: Automated build and deployment process

### 🎯 **Interactive Mount**

Easy mounting to aliases or custom domains:

```bash
# Interactive mount manager
tgdcli imount --store-id store123

# Interactive mount for production
tgdcli imount --store-id store123 --prod
```

**Options:**

- 🏷️ **Alias Mount**: Create custom subdomain aliases
- 🌐 **Domain Mount**: Mount to custom domains (production only)
- 📊 **Mount Status**: View current mounts and routes

### 📋 **Interactive List**

Enhanced deployment listing with tree view:

```bash
# Interactive list with tree view
tgdcli ilist --store-id store123

# Interactive list for specific environment
tgdcli ilist --store-id store123 --local
```

**Features:**

- 🌳 **Tree View**: Visual route hierarchy
- 📊 **Mount Information**: Aliases and custom domains
- 🔗 **Direct Links**: Clickable URLs for testing
- 📅 **Deployment Details**: Creation dates and status

## Domain Management

### 🌐 **Custom Domains (Production Only)**

Manage custom domains for production deployments:

```bash
# List all custom domains
tgdcli list-domains

# Add new custom domain
tgdcli add-domain mystore.com

# Verify domain ownership and DNS
tgdcli verify-domain domain_abc123

# Remove custom domain
tgdcli remove-domain domain_abc123
```

**Domain Setup Process:**

1. **Add Domain**: Register domain with TagadaPay
2. **DNS Configuration**: Set up required DNS records
3. **Verification**: Verify ownership and DNS propagation
4. **Mounting**: Mount deployments to verified domains

**DNS Requirements:**

- **CNAME Record**: Point domain to TagadaPay CDN
- **TXT Record**: Domain ownership verification
- **SSL Certificate**: Automatically provisioned via Let's Encrypt

## Configuration

### 🔧 **Environment Configuration**

The CLI supports multiple environments with automatic configuration:

```bash
# Production (default)
tgdcli login --prod
tgdcli deploy --store-id store123

# Development environment
tgdcli login --dev
tgdcli deploy --dev --store-id store123

# Local development
tgdcli login --local
tgdcli deploy --local --store-id store123
```

### 📁 **Local Configuration Files**

The CLI uses local configuration files for convenience:

- **`.local.cli.json`**: Stores selected store ID for commands
- **Authentication files**: Environment-specific auth tokens
- **Config injection**: Optional JSON files for plugin configuration

### 🎯 **Plugin Configuration**

Configuration is handled automatically by the TagadaPay platform. When building plugins, use the **TagadaPay Plugin SDK** to access configuration data through React hooks.

**👉 For configuration access in your plugin code, see the [Plugin SDK documentation](../plugin-sdk/README.md)**

## White-Label & Custom Base URL

### 🏢 **Overview**

The CLI now supports custom base URLs through the `--base-url` flag, enabling white-label partners and organizations with custom TagadaPay instances to use their own domains seamlessly.

**Perfect for:**
- 🏢 **White-label Partners** - Like Apptics (crm.apptics.ai)
- 🔒 **Private Instances** - Internal company deployments
- 🌐 **Regional Deployments** - Localized TagadaPay instances
- 🧪 **Custom Testing** - Dedicated test environments

### 🎯 **Quick Start**

```bash
# 1. Login to your custom domain
tgdcli login --base-url crm.apptics.ai

# 2. Deploy your plugin
tgdcli deploy --base-url crm.apptics.ai --store-id store123 --plugin-id my-app

# 3. List deployments
tgdcli list --base-url crm.apptics.ai --store-id store123

# 4. Interactive management
tgdcli int --base-url crm.apptics.ai --store-id store123
```

### 📋 **Universal Command Support**

The `--base-url` flag works with **all CLI commands**:

| Command Category | Example |
|------------------|---------|
| **Authentication** | `tgdcli login --base-url crm.apptics.ai` |
| **Deployment** | `tgdcli deploy --base-url crm.apptics.ai --store-id store123` |
| **Interactive** | `tgdcli int --base-url crm.apptics.ai --store-id store123` |
| **Listing** | `tgdcli list --base-url crm.apptics.ai --store-id store123` |
| **Mounting** | `tgdcli mount-alias dep_123 my-alias --base-url crm.apptics.ai` |
| **Domains** | `tgdcli list-domains --base-url crm.apptics.ai` |

### 🔄 **Environment Flag Comparison**

| Flag | Purpose | Target URL | Use Case |
|------|---------|------------|----------|
| `--prod` | Production | `https://app.tagadapay.com` | Default TagadaPay production |
| `--dev` | Development | `https://app.tagadapay.dev` | TagadaPay team development |
| `--local` | Local | `http://app.localhost:3000` | TagadaPay team local dev |
| `--base-url <domain>` | **Custom** | Any domain | **White-label partners** |

### 💡 **How It Works**

#### **Automatic Protocol Detection**
```bash
# These are equivalent:
tgdcli login --base-url crm.apptics.ai
tgdcli login --base-url https://crm.apptics.ai

# Protocol is automatically added if missing
```

#### **Backward Compatibility**
```bash
# Both flags work identically:
tgdcli deploy --base-url crm.apptics.ai --store-id store123
tgdcli deploy --api-url crm.apptics.ai --store-id store123

# --base-url and --api-url are aliases
```

#### **Environment Configuration**
The CLI automatically:
1. ✅ Detects custom domains (contains `.` or starts with `http`)
2. ✅ Adds `https://` protocol if missing
3. ✅ Extracts CDN domain for plugin URLs
4. ✅ Manages separate authentication per domain

### 🚀 **Complete Workflow Example**

#### **Apptics White-Label Setup**

```bash
# Step 1: Login to Apptics CRM
tgdcli login --base-url crm.apptics.ai
# Enter your API key when prompted

# Step 2: Verify authentication
tgdcli whoami --base-url crm.apptics.ai

# Step 3: Initialize a new plugin
tgdcli init my-checkout "Checkout Plugin" --base-url crm.apptics.ai

# Step 4: Deploy the plugin
cd my-checkout
tgdcli deploy --base-url crm.apptics.ai --store-id your-store-id

# Step 5: Interactive management
tgdcli int --base-url crm.apptics.ai --store-id your-store-id

# Step 6: List all deployments
tgdcli list --base-url crm.apptics.ai --store-id your-store-id
```

### 🔧 **CI/CD Integration**

```bash
# GitHub Actions / GitLab CI Example
- name: Deploy to White-Label CRM
  run: |
    tgdcli login --base-url ${{ secrets.CUSTOM_BASE_URL }} --api-key ${{ secrets.API_KEY }}
    tgdcli deploy --base-url ${{ secrets.CUSTOM_BASE_URL }} \
      --store-id ${{ secrets.STORE_ID }} \
      --plugin-id my-app \
      --name "My App"
```

### ❓ **Frequently Asked Questions**

**Q: Does `--base-url` work with all commands?**
A: Yes! It works with authentication, deployment, interactive mode, domains, and all other CLI commands.

**Q: What happens if I don't specify `--base-url`?**
A: The CLI defaults to TagadaPay production (`https://app.tagadapay.com`).

**Q: Can I save my base URL so I don't need to type it every time?**
A: Authentication is stored per-environment. After login, subsequent commands can use the stored auth, but you still need to specify `--base-url` for each command.

**Q: Do I need to specify `https://`?**
A: No, the CLI automatically adds `https://` if you only provide the domain.

**Q: Can I use this with custom ports?**
A: Yes! Example: `--base-url https://crm.example.com:8443`

**Q: Is this only for production environments?**
A: No, you can use `--base-url` with any TagadaPay-compatible instance, including testing/staging environments.

### 🛡️ **Best Practices**

1. **Environment Variables** - Store base URL in environment variables for CI/CD
2. **Separate Auth** - Login separately for each base URL/environment
3. **Verify First** - Use `tgdcli whoami --base-url <domain>` to verify authentication
4. **Document Custom Domains** - Keep a list of your organization's custom domains
5. **Test Before Production** - Test deployments on staging domains first

### 📞 **Partner Support**

For white-label partners needing assistance:
- 📖 **Documentation**: See this section
- 💬 **Slack**: Contact your partner success manager
- 📧 **Email**: partners@tagadapay.com

## Deployment Management

### 🚀 **Deployment Lifecycle**

```bash
# 1. Create deployment
tgdcli deploy --store-id store123 --plugin-id my-app --name "My App"

# 2. Mount to alias for testing
tgdcli mount-alias dep_abc123 test-alias

# 3. Mount to production domain
tgdcli imount --store-id store123  # Interactive domain mounting

# 4. Monitor and manage
tgdcli ilist --store-id store123   # View deployment tree

# 5. Update deployment
tgdcli deploy --store-id store123 --plugin-id my-app --name "My App v2"

# 6. Clean up old deployments
tgdcli remove-deployment dep_old123
```

### 🔄 **Route Management**

Advanced route management for complex deployments:

```bash
# View all routes for debugging
tgdcli routes --store-id store123

# Clean up orphaned routes
tgdcli clean-routes --store-id store123

# Unmount all deployments (emergency cleanup)
tgdcli unmount-all --store-id store123 --force
```

### 📊 **Monitoring & Debugging**

```bash
# Verbose deployment with detailed logs
tgdcli deploy --verbose --store-id store123

# Check authentication status
tgdcli whoami

# Interactive tree view for visual debugging
tgdcli ilist --store-id store123
```

## Best Practices

### ✅ **Recommended Workflow**

1. **Development**: Use `--dev` environment for testing
2. **Interactive Mode**: Use `tgdcli int` for most operations
3. **Meaningful Names**: Use descriptive plugin IDs and aliases
4. **Environment Separation**: Keep dev/prod deployments separate
5. **Regular Cleanup**: Remove unused deployments and routes

### 🚀 **Performance Tips**

- Use interactive mode for better UX
- Cache store ID selection with `.local.cli.json`
- Use meaningful aliases for easy identification
- Regular cleanup of unused deployments
- Monitor route conflicts with `tgdcli routes`

### 🔒 **Security Considerations**

- Domain ownership verification in production
- Environment-specific authentication
- Regular cleanup of test deployments
- Proper DNS configuration for custom domains

## TagadaPay Internal Developer Access

> **⚠️ For TagadaPay Team Members Only**
>
> The following features are restricted to TagadaPay internal developers. If you need access to development or local environments, please contact the TagadaPay development team.

### 🔧 **Internal Environment Access**

```bash
# Development environment (TagadaPay team only)
tgdcli login --dev
tgdcli deploy --alias "my-plugin" --dev
# Result: https://my-plugin.<storeId>.dev.tagadapay.com

# Local development environment (TagadaPay team only)
tgdcli login --local
tgdcli deploy --alias "my-plugin" --local
# Result: https://my-plugin.<storeId>.local.tagadapay.com

# Custom environment URLs (TagadaPay team only)
tgdcli login --api-url https://dev.tagadapay.com
tgdcli login --api-url http://app.localhost:3000
```

### 📞 **Contact for Internal Access**

If you're a TagadaPay team member and need access to internal environments:

- 💬 **Slack**: #dev-platform channel
- 📧 **Email**: dev-team@tagadapay.com
- 🎫 **Jira**: Create a platform access ticket

## Changelog

### 🚀 **Version 2.2.0** (Latest)

**New Features:**

- ✨ **White-Label Support**: Added `--base-url` flag for custom domain support
- 🏢 **Partner Integration**: Enable Apptics and other white-label partners to use their custom domains
- 🌐 **Universal Command Support**: Works with all CLI commands (auth, deploy, interactive, domains, etc.)
- 🔄 **Backward Compatible**: Existing `--api-url`, `--dev`, `--local`, `--prod` flags work unchanged
- 🔒 **Smart Protocol Detection**: Automatically adds `https://` if protocol not specified
- 📋 **Comprehensive Documentation**: Added complete White-Label & Custom Base URL section

**Use Cases:**
```bash
# Login to white-label CRM
tgdcli login --base-url crm.apptics.ai

# Deploy to custom domain
tgdcli deploy --base-url crm.apptics.ai --store-id store123

# Interactive manager with custom base URL
tgdcli int --base-url crm.apptics.ai --store-id store123
```

### **Version 2.1.1**

**Documentation Updates:**

- 📚 **Enhanced README**: Added comprehensive changelog and version information
- 🏷️ **NPM Badges**: Added version and download badges
- 💡 **Update Tips**: Added guidance for users to get latest features

### **Version 2.1.0**

**New Features:**

- 🗑️ **Clean Remove Deployment**: Added comprehensive deployment removal command that removes deployment and all attached routes (aliases, custom domains, database records)
- 🛡️ **Enhanced Safety**: Double confirmation system for destructive operations

**Bug Fixes:**

- 🔧 **Fixed Alias Deployment**: Aliases are now properly created during deployment (was sending `alias` instead of `deploymentAlias`)
- 🗑️ **Fixed Alias Unmounting**: Resolved "Alias not found" errors and stale display issues after unmount operations
- 🧹 **Auto-cleanup**: Mounts API now automatically detects and removes stale route references

**Improvements:**

- 📊 **Better Feedback**: Enhanced status reporting for mount/unmount operations
- 🔄 **Improved Reliability**: More robust error handling and state management

### **Version 2.0.19**

- Interactive deployment management
- Advanced routing capabilities
- Multi-environment support

## Support

- 📖 **Documentation**: [docs.tagadapay.com](https://docs.tagadapay.com)
- 💬 **Discord**: [discord.gg/tagadapay](https://discord.gg/tagadapay)
- 🐛 **Issues**: [github.com/tagadapay/plugin-cli/issues](https://github.com/tagadapay/plugin-cli/issues)
- 📧 **Email**: support@tagadapay.com

---

**Made with ❤️ by the TagadaPay team**

**Author**: [Loïc Delobel](https://www.linkedin.com/in/loicdelobel/)