@tagadapay/plugin-cli

v3.0.3

Published

2 months ago

CLI V3 for deploying Tagada Pay plugins - Uses V2 API endpoints

0High
0Medium
0Low

tagadapay cms plugin cli deployment react direct-mode spa

TagadaPay Plugin CLI Documentation

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

Quick Start

🚀 Interactive Mode (Recommended)

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

# 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:

# 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

# 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

# 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

# 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:

# 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:

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

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

Process:

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

🎯 Interactive Mount

Easy mounting to aliases or custom domains:

# 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:

# 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:

# 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:

Add Domain: Register domain with TagadaPay
DNS Configuration: Set up required DNS records
Verification: Verify ownership and DNS propagation
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:

# 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

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

# 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

# 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

# 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:

✅ Detects custom domains (contains . or starts with http)
✅ Adds https:// protocol if missing
✅ Extracts CDN domain for plugin URLs
✅ Manages separate authentication per domain

🚀 Complete Workflow Example

Apptics White-Label Setup

# 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

# 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

Environment Variables - Store base URL in environment variables for CI/CD
Separate Auth - Login separately for each base URL/environment
Verify First - Use tgdcli whoami --base-url <domain> to verify authentication
Document Custom Domains - Keep a list of your organization's custom domains
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: [email protected]

Deployment Management

🚀 Deployment Lifecycle

# 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:

# 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

# 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

Development: Use --dev environment for testing
Interactive Mode: Use tgdcli int for most operations
Meaningful Names: Use descriptive plugin IDs and aliases
Environment Separation: Keep dev/prod deployments separate
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

# 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: [email protected]
🎫 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:

# 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