CLI Configuration

Master advanced configuration options and customization techniques for the TagadaPay CLI v3.

Plugin Manifest

The plugin.manifest.json file is the core configuration for your plugin:

plugin.manifest.json

{
  "pluginId": "my-awesome-plugin",
  "name": "My Awesome Plugin",
  "version": "1.2.0",
  "description": "An amazing checkout experience",
  "author": "Your Name",
  "homepage": "https://yourwebsite.com",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-plugin"
  },
  "pages": [
    {
      "path": "/",
      "features": ["landing"],
      "isDefault": true,
      "isEntry": true,
      "remappable": false,
      "description": "Landing page"
    },
    {
      "path": "/checkout",
      "features": [
        {
          "type": "checkout",
          "requirements": ["payment", "shipping"]
        }
      ],
      "remappable": true,
      "description": "Checkout flow"
    },
    {
      "path": "/thankyou/:orderId",
      "features": [
        {
          "type": "thankyou",
          "requirements": ["order"]
        }
      ],
      "remappable": true,
      "description": "Thank you page with order details"
    }
  ],
  "mode": "direct-mode"
}

Manifest Fields Explained

pluginId (required)

Unique identifier for your plugin

Must be unique across the TagadaPay platform
Used for deployment identification
Cannot be changed once deployed

"pluginId": "my-checkout-plugin"

name (required)

Human-readable plugin name - Displayed in the TagadaPay dashboard - Can contain spaces and special characters json "name": "Premium Checkout Experience"

version (required)

Semantic version number - Follows SemVer format: MAJOR.MINOR.PATCH - Used in deployment names - Helps track plugin updates json "version": "2.1.0"

pages (required)

Array of page configurationsEach page defines a route in your plugin:

path: URL path (supports parameters with :param)
features: Array of feature types or objects with requirements
isDefault: Mark as default page (one per plugin)
isEntry: Mark as entry point
remappable: Allow path remapping to external URLs
description: Optional page description

"pages": [
  {
    "path": "/products/:id",
    "features": ["product-page"],
    "remappable": true,
    "description": "Product detail page"
  }
]

mode (optional)

Plugin loading mode - "direct-mode": Load plugin directly (default, recommended) - "iframe-mode": Load in iframe (legacy) json "mode": "direct-mode"

router (optional)

Advanced routing configuration

basePath: Base path for all routes
matcher: Path pattern to match (uses path-to-regexp)
excluder: Pattern to exclude from matching

"router": {
  "basePath": "/",
  "matcher": ".*",
  "excluder": "/admin"
}

Page Features

Standard Features

Simple string features for common page types:

{
  "pages": [
    { "path": "/", "features": ["landing"] },
    { "path": "/about", "features": ["static"] },
    { "path": "/products", "features": ["catalog"] }
  ]
}

Complex Features with Requirements

Features that need specific data or capabilities:

{
  "pages": [
    {
      "path": "/checkout",
      "features": [
        {
          "type": "checkout",
          "requirements": ["payment", "shipping", "customer"]
        }
      ]
    },
    {
      "path": "/thankyou/:orderId",
      "features": [
        {
          "type": "thankyou",
          "requirements": ["order", "customer"]
        }
      ]
    }
  ]
}

Available Feature Types:

landing - Landing pages
checkout - Checkout flows
thankyou - Order confirmation
product-page - Product details
catalog - Product listings
upsell - Upsell offers
post-purchase - Post-purchase flows
static - Static content

Available Requirements:

payment - Payment processing
shipping - Shipping calculation
customer - Customer data
order - Order information
cart - Shopping cart
inventory - Inventory management

Path Remapping

Path remapping allows external URLs to map to internal plugin paths:

Enable Remapping

Mark pages as remappable in your manifest:

{
  "pages": [
    {
      "path": "/products/:id",
      "features": ["product-page"],
      "remappable": true // ✅ Allows remapping
    },
    {
      "path": "/checkout",
      "features": [{ "type": "checkout" }],
      "remappable": true // ✅ Allows remapping
    },
    {
      "path": "/admin",
      "features": ["admin"],
      "remappable": false // ❌ Cannot be remapped
    }
  ]
}

Example Remap Scenario

// Internal plugin path: /products/:id
// External customer URL: /p/:slug

// CRM configures the remap:
{
  externalPath: '/p/:slug',
  internalPath: '/products/:id'
}

// Customer visits: https://store.com/p/awesome-product
// Plugin receives: /products/awesome-product
// Parameter available in plugin as { id: 'awesome-product' }

Testing Remapping Locally

// In browser console or plugin code:
localStorage.setItem(
  'tagadapay-remap',
  JSON.stringify({
    externalPath: '/p/:slug',
    internalPath: '/products/:id',
  }),
);

// Or use query parameter:
// http://localhost:5173/p/test-product?__remap=/products/test-product

Local Development Config

Create .local.json for local development:

.local.json

{
  "storeId": "store_dev_123",
  "accountId": "acc_dev_456",
  "customerId": "cus_test_789",
  "config": "blue",
  "basePath": undefined,
  "apiUrl": "https://app.tagadapay.dev"
}

Fields:

storeId: Your development store ID
accountId: Your account ID
customerId: Test customer ID (optional)
config: Configuration variant name (matches config/*.json filename)
basePath: Override base path (usually undefined)
apiUrl: API endpoint for development

Configuration Variants

Directory Structure

my-plugin/
├── config/
│   ├── development.json
│   ├── staging.json
│   ├── production.json
│   └── variants/
│       ├── theme-blue.json
│       ├── theme-green.json
│       └── holiday-special.json
├── plugin.manifest.json
├── .local.json
└── dist/

Environment Configs

Development

config/development.json

{
  "environment": "development",
  "debug": true,
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d"
  },
  "features": {
    "analytics": false,
    "errorTracking": true,
    "mockPayments": true
  },
  "api": {
    "timeout": 10000,
    "retries": 3
  }
}

Staging

config/staging.json

{
  "environment": "staging",
  "debug": false,
  "theme": {
    "primaryColor": "#17a2b8",
    "secondaryColor": "#6c757d"
  },
  "features": {
    "analytics": true,
    "errorTracking": true,
    "mockPayments": false
  },
  "api": {
    "timeout": 5000,
    "retries": 2
  }
}

Production

config/production.json

{
  "environment": "production",
  "debug": false,
  "theme": {
    "primaryColor": "#28a745",
    "secondaryColor": "#6c757d"
  },
  "features": {
    "analytics": true,
    "errorTracking": true,
    "mockPayments": false,
    "performanceMonitoring": true
  },
  "api": {
    "timeout": 5000,
    "retries": 3
  },
  "security": {
    "strictMode": true,
    "cspEnabled": true
  }
}

Theme Variants

config/variants/theme-blue.json

{
  "name": "Blue Theme",
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#0056b3",
    "successColor": "#28a745",
    "warningColor": "#ffc107",
    "dangerColor": "#dc3545",
    "fontFamily": "Inter, system-ui, sans-serif",
    "borderRadius": "8px"
  },
  "branding": {
    "logo": "https://cdn.example.com/logo-blue.png",
    "favicon": "https://cdn.example.com/favicon-blue.ico"
  }
}

config/variants/holiday-special.json

{
  "name": "Holiday Special",
  "theme": {
    "primaryColor": "#c41e3a",
    "secondaryColor": "#165b33",
    "fontFamily": "Georgia, serif"
  },
  "features": {
    "snowEffect": true,
    "holidayBanner": true,
    "specialOffers": true
  },
  "promotions": {
    "enabled": true,
    "code": "HOLIDAY2025",
    "discount": 20
  }
}

Deployment Configuration

Deploy with Specific Config

# Deploy with production config
tgdcli deploy --config config/production.json

# Deploy with theme variant
tgdcli deploy --config config/variants/theme-blue.json

# Interactive selection
tgdcli interactive deploy
# > Select configuration: [production] [staging] [theme-blue]

Config Priority

The CLI resolves configuration in this order:

Command-line config (--config flag)
Interactive selection
.local.json (for local development)
Default/no config (uses store settings only)

Environment Variables

Set global CLI preferences:

# Default store ID
export TAGADA_STORE_ID=store_abc123

# API environment
export TAGADA_API_URL=https://app.tagadapay.com

# Enable debug logging
export TAGADA_DEBUG=true

# Default config directory
export TAGADA_CONFIG_DIR=./config

# Auth token (advanced)
export TAGADA_AUTH_TOKEN=your_token_here

Using Environment-Specific URLs

# Production
export TAGADA_API_URL=production
# Resolves to: https://app.tagadapay.com

# Staging
export TAGADA_API_URL=staging
# Resolves to: https://app.tagadapay.dev

# Local development
export TAGADA_API_URL=local
# Resolves to: http://app.localhost:3000

# Custom
export TAGADA_API_URL=https://custom.tagadapay.com

CLI Config File

Create ~/.tgdclirc for persistent CLI settings:

~/.tgdclirc

{
  "defaultStoreId": "store_prod_123",
  "defaultEnvironment": "production",
  "verboseLogging": false,
  "autoVerifyDomains": true,
  "confirmDestructiveActions": true,
  "colorOutput": true,
  "defaultConfigDir": "./config"
}

Advanced Configuration

Custom Build Directory

plugin.manifest.json

{
  "pluginId": "my-plugin",
  "build": {
    "directory": "build", // Default: "dist"
    "exclude": ["**/*.map", "**/*.test.js", "**/README.md"]
  }
}

Custom CDN Configuration

config/production.json

{
  "cdn": {
    "enabled": true,
    "provider": "vercel",
    "customDomain": "cdn.mystore.com",
    "cacheControl": "public, max-age=31536000, immutable"
  }
}

Analytics Configuration

config/production.json

{
  "analytics": {
    "enabled": true,
    "providers": [
      {
        "name": "google-analytics",
        "trackingId": "G-XXXXXXXXXX",
        "config": {
          "anonymizeIp": true,
          "cookieExpires": 63072000
        }
      },
      {
        "name": "facebook-pixel",
        "pixelId": "123456789",
        "config": {
          "autoConfig": true
        }
      }
    ]
  }
}

Feature Flags

config/production.json

{
  "features": {
    "expressCheckout": true,
    "oneClickUpsell": true,
    "subscriptionMode": false,
    "dynamicPricing": true,
    "inventoryCheck": true,
    "guestCheckout": true,
    "socialProof": true,
    "abandonedCart": true
  }
}

Configuration Validation

The CLI automatically validates your configuration:

# Validate config file
tgdcli validate-config config/production.json

# Validate manifest
tgdcli validate-manifest plugin.manifest.json

# Dry-run deployment (validates without deploying)
tgdcli deploy --dry-run --config config/production.json

Best Practices

1. Environment-Specific Configs

✅ Do:

config/
├── development.json
├── staging.json
└── production.json

❌ Don’t:

config/
└── config.json  // Single config for all environments

2. Sensitive Data

✅ Do:

{
  "apiKeys": {
    "stripe": "${STRIPE_API_KEY}" // Use env vars
  }
}

❌ Don’t:

{
  "apiKeys": {
    "stripe": "sk_live_abc123..." // Hardcoded secrets
  }
}

3. Config Versioning

config/production.json

{
  "configVersion": "2.0.0",
  "lastUpdated": "2025-01-15",
  "maintainer": "[email protected]",
  "changelog": ["2.0.0 - Added new payment providers", "1.5.0 - Updated theme colors"]
}

4. Documentation

Add README for each config variant:

config/variants/README.md

# Theme Variants

## Available Themes

- `theme-blue.json` - Default blue theme for general use
- `theme-green.json` - Green theme for eco-friendly campaigns
- `holiday-special.json` - Holiday theme (Nov-Dec only)

## Usage

```bash
tgdcli deploy --config config/variants/theme-blue.json
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Config file not found">
    **Error**: `Configuration file not found: config/production.json`

    **Solution**:
    ```bash
    # Check file exists
    ls -la config/production.json

    # Use absolute path
    tgdcli deploy --config /full/path/to/config/production.json
    ```
  </Accordion>

  <Accordion title="Invalid JSON in config">
    **Error**: `Invalid JSON in configuration file`

    **Solution**:
    ```bash
    # Validate JSON syntax
    cat config/production.json | python -m json.tool

    # Or use jq
    jq . config/production.json
    ```
  </Accordion>

  <Accordion title="Manifest validation failed">
    **Error**: `Invalid plugin manifest: missing required field 'pluginId'`

    **Solution**:
    ```bash
    # Ensure all required fields exist
    cat plugin.manifest.json

    # Validate against schema
    tgdcli validate-manifest
    ```
  </Accordion>

  <Accordion title="Path remapping not working">
    **Error**: 404 on remapped paths

    **Solution**:
    1. Verify `remappable: true` in manifest
    2. Check CRM routing configuration
    3. Test locally with localStorage:
    ```javascript
    localStorage.setItem('tagadapay-remap', JSON.stringify({
      externalPath: '/p/:slug',
      internalPath: '/products/:id'
    }));
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/developer-tools/cli/quick-start">
    Deploy your first plugin
  </Card>
  <Card title="CLI Reference" icon="terminal" href="/developer-tools/cli/introduction">
    Complete command reference
  </Card>
  <Card title="SDK Integration" icon="puzzle-piece" href="/developer-tools/sdk/introduction">
    Use SDK with your plugin
  </Card>
  <Card title="Examples" icon="lightbulb" href="/developer-tools/sdk/examples">
    Real-world configuration examples
  </Card>
</CardGroup>

Plugin SDK

Plugin CLI

Integration Guides

CLI Configuration

CLI Configuration

Plugin Manifest

Manifest Fields Explained

Page Features

Standard Features

Complex Features with Requirements

Path Remapping

Enable Remapping

Example Remap Scenario

Testing Remapping Locally

Local Development Config

Configuration Variants

Directory Structure

Environment Configs

Development

Staging

Production

Theme Variants

Deployment Configuration

Deploy with Specific Config

Config Priority

Environment Variables

Using Environment-Specific URLs

CLI Config File

Advanced Configuration

Custom Build Directory

Custom CDN Configuration

Analytics Configuration

Feature Flags

Configuration Validation

Best Practices

1. Environment-Specific Configs

2. Sensitive Data

3. Config Versioning

4. Documentation

Plugin SDK

Plugin CLI

Integration Guides

​CLI Configuration

​Plugin Manifest

​Manifest Fields Explained

​Page Features

​Standard Features

​Complex Features with Requirements

​Path Remapping

​Enable Remapping

​Example Remap Scenario

​Testing Remapping Locally

​Local Development Config

​Configuration Variants

​Directory Structure

​Environment Configs

​Development

​Staging

​Production

​Theme Variants

​Deployment Configuration

​Deploy with Specific Config

​Config Priority

​Environment Variables

​Using Environment-Specific URLs

​CLI Config File

​Advanced Configuration

​Custom Build Directory

​Custom CDN Configuration

​Analytics Configuration

​Feature Flags

​Configuration Validation

​Best Practices

​1. Environment-Specific Configs

​2. Sensitive Data

​3. Config Versioning

​4. Documentation

CLI Configuration

Plugin Manifest

Manifest Fields Explained

Page Features

Standard Features

Complex Features with Requirements

Path Remapping

Enable Remapping

Example Remap Scenario

Testing Remapping Locally

Local Development Config

Configuration Variants

Directory Structure

Environment Configs

Development

Staging

Production

Theme Variants

Deployment Configuration

Deploy with Specific Config

Config Priority

Environment Variables

Using Environment-Specific URLs

CLI Config File

Advanced Configuration

Custom Build Directory

Custom CDN Configuration

Analytics Configuration

Feature Flags

Configuration Validation

Best Practices

1. Environment-Specific Configs

2. Sensitive Data

3. Config Versioning

4. Documentation