> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin CLI

> Deploy and manage plugins with the TagadaPay CLI

# TagadaPay Plugin CLI

<Card title="Latest Version" icon="tag">
  **v3.0.3** — `@tagadapay/plugin-cli`
</Card>

A command-line tool for deploying React apps, static websites, and plugins on TagadaPay with routing, domain management, and instance management.

```bash theme={null}
npm install -g @tagadapay/plugin-cli
```

The CLI installs two binary aliases: **`tgd`** (short) and `tgdcli` (long). All examples below use `tgd`.

## Quick Start

<Steps>
  <Step title="Login">
    ```bash theme={null}
    tgd login
    ```

    Opens your browser for secure authentication. Defaults to production.
  </Step>

  <Step title="Deploy your plugin">
    ```bash theme={null}
    cd my-plugin
    tgd deploy
    ```

    The CLI reads `plugin.manifest.json`, creates a ZIP of your `dist/` folder, uploads it, and deploys.
  </Step>
</Steps>

## Interactive Mode

The easiest way to manage everything — deploy, mount, install, manage domains:

```bash theme={null}
tgd interactive
```

<Frame>
  ```
  🎛️  TagadaPay Plugin Manager
  ────────────────────────────

  ? What would you like to do? (Use arrow keys)
  ❯ 🚀 Deploy Plugin
    📋 List Deployments
    🔌 Install Plugin from Store
    🔗 Mount Plugin to Alias
    📊 List Instances
    🌐 Manage Domains
    ❌ Exit
  ```
</Frame>

Interactive mode provides store selection, config variant picking, real-time upload progress, and guided workflows.

## Commands

### Authentication

<CodeGroup>
  ```bash Login theme={null}
  tgd login              # Production (default)
  tgd login --dev        # Development
  tgd login --local      # Local dev server
  ```

  ```bash Logout theme={null}
  tgd logout
  tgd logout --dev
  ```

  ```bash Check Status theme={null}
  tgd whoami
  ```
</CodeGroup>

### Deploy

```bash theme={null}
tgd deploy                                     # Auto-detect manifest, prompt for store
tgd deploy --store store_abc123                # Specify store
tgd deploy --store store_abc123 --config config/production.json
tgd deploy --plugin-id "custom-id"             # Override plugin ID
tgd deploy --auto-suffix                       # Append random suffix to plugin ID
tgd deploy --overwrite                         # Replace existing deployment (same plugin+version)
```

| Flag            | Alias              | Description                                        |
| --------------- | ------------------ | -------------------------------------------------- |
| `--store`       | `--store-id`, `-s` | Target store ID (prompts if omitted)               |
| `--config`      | `-c`               | Path to manifest (default: `plugin.manifest.json`) |
| `--env`         | `-e`               | Environment: `dev`, `local`, `prod`                |
| `--dev`         | `-d`               | Shortcut for `--env dev`                           |
| `--local`       | `-l`               | Shortcut for `--env local`                         |
| `--prod`        | `-p`               | Shortcut for `--env prod` (default)                |
| `--plugin-id`   |                    | Override plugin ID from manifest                   |
| `--auto-suffix` |                    | Append random 6-char suffix to plugin ID           |
| `--overwrite`   | `--force`          | Delete existing deployment and replace             |
| `--verbose`     |                    | Show detailed API logs                             |

<Warning>
  `--overwrite` permanently deletes the existing deployment (record, instances, routes) and replaces it. This is not reversible.
</Warning>

After deploying, the CLI auto-syncs config templates if a `config/` folder exists (presets, schema, uiSchema).

### Archive

Create a local ZIP without deploying:

```bash theme={null}
tgd archive                        # Creates archive from current dir
tgd archive --output my-plugin.zip # Custom output filename
```

### List

```bash theme={null}
tgd list --store store_abc123           # List active plugins
tgd list --store store_abc123 --inactive # Include inactive
```

### Instance Management

<CodeGroup>
  ```bash Install Plugin theme={null}
  tgd install --store store_abc123
  # Interactive — select plugin, configure, create instance
  ```

  ```bash List Instances theme={null}
  tgd list-instances --store store_abc123
  # Shows instances grouped by plugin → version → config
  ```

  ```bash Mount to Alias theme={null}
  tgd mount-alias --store store_abc123
  # Interactive — select instance, pick alias
  ```

  ```bash List Mount Points theme={null}
  tgd list-mounts --store store_abc123
  # Shows all aliases/domains and their mounted routes
  ```
</CodeGroup>

### Domain Management

Domain commands authenticate via your login session. They do **not** require `--store-id`.

<CodeGroup>
  ```bash List Domains theme={null}
  tgd list-domains
  tgd list-domains --dev
  ```

  ```bash Add Domain theme={null}
  tgd add-domain checkout.example.com
  # Adds and auto-verifies
  ```

  ```bash Verify Domain theme={null}
  tgd verify-domain cdm_abc123
  # Takes a domain ID (not domain name)
  ```

  ```bash Remove Domain theme={null}
  tgd remove-domain cdm_abc123
  ```

  ```bash Domain Info theme={null}
  tgd domain-info checkout.example.com
  ```

  ```bash Auto-Verify All theme={null}
  tgd auto-verify-domains
  ```
</CodeGroup>

## Plugin Manifest

Every plugin requires a `plugin.manifest.json`. The CLI validates it before deploying.

### Required Fields

```json theme={null}
{
  "pluginId": "my-checkout-plugin",
  "name": "My Checkout Plugin",
  "version": "1.0.0",
  "description": "A custom checkout experience",
  "author": "Your Name",
  "category": "checkout",
  "mode": "direct-mode",
  "pages": [
    {
      "path": "/",
      "features": ["landing"],
      "remappable": false
    },
    {
      "path": "/checkout",
      "features": [
        {
          "type": "checkout",
          "requirements": ["payment"]
        }
      ],
      "remappable": true
    },
    {
      "path": "/thankyou/:orderId",
      "features": [
        {
          "type": "thankyou"
        }
      ],
      "remappable": true
    }
  ],
  "router": {
    "basePath": "/",
    "matcher": ".*",
    "excluder": null
  },
  "requirements": {
    "sdk": "@tagadapay/plugin-sdk",
    "sdkVersion": "v2"
  }
}
```

### All Manifest Fields

| Field           | Required | Description                                            |
| --------------- | -------- | ------------------------------------------------------ |
| `pluginId`      | Yes      | Unique plugin identifier                               |
| `name`          | Yes      | Human-readable name                                    |
| `version`       | Yes      | Semver (`1.0.0`)                                       |
| `description`   | Yes      | Short description                                      |
| `author`        | Yes      | Author name                                            |
| `category`      | Yes      | Category (e.g. `checkout`, `landing`, `upsell`)        |
| `pages`         | Yes      | Array of page definitions (at least one)               |
| `router`        | Yes      | Routing config: `basePath`, `matcher`, `excluder`      |
| `requirements`  | Yes      | SDK info: `sdk`, `sdkVersion` (`v1` or `v2`)           |
| `mode`          | No       | `direct-mode` (default) or `proxy-mode`                |
| `configuration` | No       | Config schema for CRM: `schema`, `uiSchema`, `presets` |
| `homepage`      | No       | URL to plugin homepage                                 |
| `repository`    | No       | URL to source repository                               |
| `license`       | No       | License identifier                                     |
| `tags`          | No       | Array of tag strings                                   |
| `landingImgUrl` | No       | Preview image URL                                      |
| `public`        | No       | Whether plugin is listed publicly                      |

### Page Features

Simple string features:

```json theme={null}
{ "path": "/", "features": ["landing"] }
```

Features with requirements (for pages that need data):

```json theme={null}
{
  "path": "/checkout",
  "features": [
    {
      "type": "checkout",
      "requirements": ["payment", "shipping", "customer"]
    }
  ]
}
```

**Feature types**: `landing`, `checkout`, `thankyou`, `product-page`, `catalog`, `upsell`, `post-purchase`, `static`

**Requirements**: `payment`, `shipping`, `customer`, `order`, `cart`, `inventory`

## Environments

The CLI supports three built-in environments:

| Flag               | Environment | API URL                     |
| ------------------ | ----------- | --------------------------- |
| `--prod` (default) | Production  | `https://app.tagadapay.com` |
| `--dev`            | Development | `https://app.tagadapay.dev` |
| `--local`          | Local       | `http://app.localhost:3000` |

You can also pass a custom URL:

```bash theme={null}
tgd login --base-url https://custom.tagadapay.com
```

## Workflow Examples

### Deploy & Mount

<Steps>
  <Step title="Build your plugin">
    ```bash theme={null}
    npm run build
    ```
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    tgd deploy --store store_abc123
    ```

    Note the deployment ID from the output.
  </Step>

  <Step title="Install (create instance)">
    ```bash theme={null}
    tgd install --store store_abc123
    ```

    Select the deployment, optionally configure it.
  </Step>

  <Step title="Mount to alias">
    ```bash theme={null}
    tgd mount-alias --store store_abc123
    ```

    Select the instance and choose an alias path.
  </Step>
</Steps>

### Update a Plugin

```bash theme={null}
# Bump version in plugin.manifest.json
npm run build
tgd deploy --store store_abc123

# Or overwrite same version
tgd deploy --store store_abc123 --overwrite
```

### A/B Testing

Deploy two variants and mount them via the [A/B testing API](/developer-tools/hosting/deploy-and-ab-test):

```bash theme={null}
tgd deploy --config config/variant-a.json --store store_abc123
# Note: deployment ID A

tgd deploy --config config/variant-b.json --store store_abc123
# Note: deployment ID B
```

Then configure split testing via the API or CRM.

### Custom Domain

```bash theme={null}
tgd add-domain checkout.mystore.com
# CLI will show CNAME record to add

tgd verify-domain cdm_abc123
# After DNS propagation
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    ```bash theme={null}
    tgd logout
    tgd login
    tgd whoami
    ```
  </Accordion>

  <Accordion title="Plugin manifest not found">
    Ensure `plugin.manifest.json` exists in your current directory and is valid JSON:

    ```bash theme={null}
    cat plugin.manifest.json | python3 -m json.tool
    ```
  </Accordion>

  <Accordion title="Build directory missing">
    Build your plugin before deploying:

    ```bash theme={null}
    npm run build
    ls dist/
    ```
  </Accordion>

  <Accordion title="Version conflict on deploy">
    A deployment already exists for this plugin ID + version. Either:

    * Bump the `version` in your manifest
    * Use `--overwrite` to replace the existing deployment
  </Accordion>

  <Accordion title="Domain verification failed">
    DNS can take up to 48 hours to propagate. Check status:

    ```bash theme={null}
    tgd domain-info checkout.mystore.com
    tgd verify-domain cdm_abc123
    ```
  </Accordion>
</AccordionGroup>

### Verbose Mode

For detailed API request/response logs:

```bash theme={null}
tgd --verbose deploy
```

## Support

* **Documentation**: [docs.tagadapay.com](https://docs.tagadapay.com)
* **Support**: [developer-support@tagadapay.com](mailto:developer-support@tagadapay.com)
* **GitHub**: [Report issues](https://github.com/tagadapay/tagadapay/issues)