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

# CLI Configuration

> Plugin manifest, config variants, and environment setup

# CLI Configuration

## Plugin Manifest

The `plugin.manifest.json` file defines your plugin. The CLI validates it before every deployment.

### Complete Example

```json theme={null}
{
  "pluginId": "my-checkout-plugin",
  "name": "My Checkout Plugin",
  "version": "2.1.0",
  "description": "A premium checkout experience",
  "author": "Your Name",
  "category": "checkout",
  "mode": "direct-mode",
  "tags": ["checkout", "premium"],
  "pages": [
    {
      "path": "/",
      "features": ["landing"],
      "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": "Order confirmation"
    }
  ],
  "router": {
    "basePath": "/",
    "matcher": ".*",
    "excluder": null
  },
  "requirements": {
    "sdk": "@tagadapay/plugin-sdk",
    "sdkVersion": "v2"
  },
  "configuration": {
    "schema": "config/schema.json",
    "uiSchema": "config/ui-schema.json"
  },
  "homepage": "https://yourwebsite.com",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT"
}
```

### Field Reference

<AccordionGroup>
  <Accordion title="pluginId (required)">
    Unique identifier for your plugin across TagadaPay. Cannot be changed once deployed.

    ```json theme={null}
    "pluginId": "my-checkout-plugin"
    ```
  </Accordion>

  <Accordion title="name, version, description, author (required)">
    Basic metadata. Version must follow semver (`MAJOR.MINOR.PATCH`).

    ```json theme={null}
    "name": "My Plugin",
    "version": "2.1.0",
    "description": "A custom checkout",
    "author": "Your Name"
    ```
  </Accordion>

  <Accordion title="category (required)">
    Plugin category for organization. Examples: `checkout`, `landing`, `upsell`, `post-purchase`.

    ```json theme={null}
    "category": "checkout"
    ```
  </Accordion>

  <Accordion title="pages (required)">
    At least one page. Each page has a `path`, optional `features`, and `remappable` flag.

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

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

    **Requirements**: `payment`, `shipping`, `customer`, `order`, `cart`, `inventory`
  </Accordion>

  <Accordion title="router (required)">
    Controls how URLs match your plugin.

    * `basePath`: Root path for the plugin (usually `/`)
    * `matcher`: Regex pattern for matching URLs (usually `.*`)
    * `excluder`: Pattern to exclude from matching (or `null`)

    ```json theme={null}
    "router": {
      "basePath": "/",
      "matcher": ".*",
      "excluder": null
    }
    ```
  </Accordion>

  <Accordion title="requirements (required)">
    SDK dependency info.

    ```json theme={null}
    "requirements": {
      "sdk": "@tagadapay/plugin-sdk",
      "sdkVersion": "v2"
    }
    ```

    `sdkVersion` must be `"v1"` or `"v2"`.
  </Accordion>

  <Accordion title="mode (optional)">
    Plugin loading mode:

    * `"direct-mode"` (default) — Plugin is served directly
    * `"proxy-mode"` — Plugin is proxied

    ```json theme={null}
    "mode": "direct-mode"
    ```
  </Accordion>

  <Accordion title="configuration (optional)">
    Allows the CRM to configure instances with a form UI. References JSON Schema files in your `config/` directory.

    ```json theme={null}
    "configuration": {
      "schema": "config/schema.json",
      "uiSchema": "config/ui-schema.json"
    }
    ```

    Without this, your plugin won't be configurable from the CRM dashboard.
  </Accordion>
</AccordionGroup>

## Config Directory

The CLI looks for a `config/` directory in your plugin root. Files found there are auto-synced after deployment.

```
my-plugin/
├── plugin.manifest.json
├── dist/
├── config/
│   ├── schema.json              # JSON Schema for config form
│   ├── ui-schema.json           # UI hints for the config form
│   ├── default.preset.json      # Default config values
│   ├── blue-theme.preset.json   # Named preset
│   └── green-theme.config.json  # Another named preset
```

### Naming Conventions

| Pattern                                     | Purpose                              |
| ------------------------------------------- | ------------------------------------ |
| `*.preset.json`                             | Config preset (synced to deployment) |
| `*.config.json`                             | Config preset (synced to deployment) |
| `schema.json` or `config.schema.json`       | JSON Schema for the config form      |
| `ui-schema.json` or `config.ui-schema.json` | UI Schema for form layout            |

### Example: Config Schema

```json title="config/schema.json" theme={null}
{
  "type": "object",
  "properties": {
    "theme": {
      "type": "object",
      "properties": {
        "primaryColor": { "type": "string", "format": "color" },
        "fontFamily": { "type": "string" }
      }
    },
    "features": {
      "type": "object",
      "properties": {
        "expressCheckout": { "type": "boolean" },
        "upsells": { "type": "boolean" }
      }
    }
  }
}
```

### Example: Config Preset

```json title="config/blue-theme.preset.json" theme={null}
{
  "theme": {
    "primaryColor": "#007bff",
    "fontFamily": "Inter, sans-serif"
  },
  "features": {
    "expressCheckout": true,
    "upsells": true
  }
}
```

When you deploy, the CLI auto-detects these files and syncs them via the `/plugins/v2/deployment/sync-config` API. This makes the presets and schema available in the CRM when creating instances.

## Local Development

Create `.local.json` in your plugin root for local development:

```json title=".local.json" theme={null}
{
  "storeId": "store_dev_123",
  "accountId": "acc_dev_456",
  "config": "blue-theme",
  "apiUrl": "https://app.tagadapay.dev"
}
```

| Field       | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `storeId`   | Your development store ID                                               |
| `accountId` | Your account ID                                                         |
| `config`    | Preset name (matches `config/*.preset.json` filename without extension) |
| `apiUrl`    | API endpoint for development                                            |

## Path Remapping

Pages with `"remappable": true` can have their URLs remapped by the CRM. This allows merchants to customize URL paths without changing plugin code.

```json theme={null}
{
  "pages": [
    {
      "path": "/products/:id",
      "features": ["product-page"],
      "remappable": true
    }
  ]
}
```

When a merchant configures a remap (e.g., external `/p/:slug` → internal `/products/:id`), the routing engine handles the translation automatically. See the [Path Remapping guide](/developer-tools/sdk/path-remapping) for details.

## Environments

The CLI supports three environments plus custom URLs:

| Name        | Flag               | API URL                     |
| ----------- | ------------------ | --------------------------- |
| Production  | `--prod` (default) | `https://app.tagadapay.com` |
| Development | `--dev`            | `https://app.tagadapay.dev` |
| Local       | `--local`          | `http://app.localhost:3000` |
| Custom      | `--base-url <url>` | Any URL                     |

```bash theme={null}
tgd login --dev
tgd deploy --local --store store_123
tgd login --base-url https://custom.tagadapay.com
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Manifest validation failed">
    The CLI validates your manifest before deploying. Common missing fields:

    * `category` — required (e.g. `"checkout"`)
    * `router` — required (`basePath`, `matcher`, `excluder`)
    * `requirements` — required (`sdk`, `sdkVersion`)

    Check validation output for specific errors.
  </Accordion>

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

  <Accordion title="Path remapping not working">
    1. Verify `"remappable": true` on the page in your manifest
    2. Check the CRM routing configuration
    3. See the [Path Remapping guide](/developer-tools/sdk/path-remapping) for debugging tips
  </Accordion>

  <Accordion title="Config not appearing in CRM">
    Make sure you have a `configuration` field in your manifest pointing to valid schema files, and that your `config/` directory contains the referenced files. They are synced automatically after `tgd deploy`.
  </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">
    All commands and flags
  </Card>

  <Card title="Plugin SDK" icon="puzzle-piece" href="/developer-tools/sdk/introduction">
    Build interactive plugins with React hooks
  </Card>

  <Card title="Hosting & A/B Testing" icon="flask-vial" href="/developer-tools/hosting/deploy-and-ab-test">
    Host pages and set up A/B tests via API
  </Card>
</CardGroup>