> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Build with Gemini CLI

Set up Gemini CLI for the best possible Paddle workflow by installing the Paddle extension, connecting the Paddle MCP server, and adding a GEMINI.md file.

---

[Gemini CLI](https://github.com/google-gemini/gemini-cli) is an AI coding agent made by Google. It runs in your terminal and integrates with Gemini models.

This guide runs through setting up Gemini CLI for the best possible experience when building with Paddle.

## Before you begin

You'll need:

- A Paddle [sandbox account](https://developer.paddle.com/sdks/sandbox.md)
- A [sandbox API key](https://developer.paddle.com/api-reference/about/authentication.md) with any permissions you plan to use.
- Gemini CLI installed.
- A project, with a Paddle SDK installed.

## Install the Paddle extension {% step=true %}

The Paddle Gemini extension bundles the [Paddle agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) with the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) and the [Paddle MCP servers](https://developer.paddle.com/sdks/ai/paddle-mcp/.md). Gemini auto-discovers the skills and connects the MCP servers when you install it.

From your terminal, run:

```bash
gemini extensions install PaddleHQ/paddle-agent-skills
```

Restart Gemini CLI for the extension to load.

## Set your Paddle API keys {% step=true %}

The extension wires up two Paddle MCP servers so the agent can work in both sandbox and live environments. This is useful for porting data from one to the other.

| MCP server       | URL                                  | API key env var          |
| ---------------- | ------------------------------------ | ------------------------ |
| `paddle-sandbox` | `https://sandbox-mcp.paddle.com/mcp` | `PADDLE_SANDBOX_API_KEY` |
| `paddle-live`    | `https://mcp.paddle.com/mcp`         | `PADDLE_LIVE_API_KEY`    |

The MCP servers read API keys from environment variables. Export them in your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent):

```sh
export PADDLE_SANDBOX_API_KEY= # Your sandbox API key
export PADDLE_LIVE_API_KEY= # Your live API key
```

[Create API keys](https://developer.paddle.com/api-reference/about/authentication.md) at **Paddle > Developer tools > Authentication**.

Restart Gemini CLI and your terminal after setting the variables so the MCP servers pick them up. Default to sandbox during development, so `PADDLE_SANDBOX_API_KEY` is the one to start with.

{% callout type="warning" %}
Start with a sandbox API key while you're evaluating. Scope your live API key narrowly, since the Paddle MCP server doesn't gate destructive operations on its own. See [Permissions and destructive actions](https://developer.paddle.com/sdks/ai/paddle-mcp#permissions-and-destructive-actions.md) for details.
{% /callout %}

## Add Paddle conventions to your GEMINI.md {% step=true %}

Gemini CLI reads project conventions from `GEMINI.md` at the project root. A focused Paddle section tells it which SDK to use, how to handle environments, and how to verify webhooks.

Create a `GEMINI.md` file at the project root, or add this to your existing `GEMINI.md` file.

```markdown {% title="GEMINI.md" wrap=true %}
## Paddle integration

When writing or modifying code that integrates with Paddle:

- Always check current Paddle documentation via the `paddle-docs` MCP server before suggesting code. The Paddle API and SDKs evolve frequently — do not rely on training data alone.
- Use the official Paddle SDK for the language in use:
  - Node.js → `@paddle/paddle-node-sdk`
  - Python → `paddle-python-sdk` (imports as `paddle_billing`)
  - Go → `github.com/PaddleHQ/paddle-go-sdk/v5`
  - PHP → `paddlehq/paddle-php-sdk`
- All development uses the sandbox environment. Sandbox API keys contain `_sdbx`; sandbox client-side tokens are prefixed with `test_`.
- Always verify webhook signatures before acting on the payload:
  - Node: `paddle.webhooks.unmarshal()`
  - Python: `Verifier().verify(request, secret)`
  - Go: `paddle.NewWebhookVerifier()` with `Middleware`
  - PHP: `(new Verifier())->verify($request, $secret)`
- For destructive account changes (updating prices, archiving products, cancelling subscriptions), ask for explicit confirmation before calling the `paddle-sandbox` or `paddle-live` MCP server.
- Use `paddle-sandbox` by default. Only call `paddle-live` when the prompt explicitly mentions live, production, or real customer data.
- API keys and webhook secrets live in environment variables — never inline credentials into code.
```

Adjust the SDK list to match the language(s) your project uses. Gemini CLI loads this every time you start a session.

## Prompt your first integration {% step=true %}

With the extension installed, the Paddle MCP servers connected, and your `GEMINI.md` file in place, ask Gemini to scaffold a Paddle integration.

```markdown {% wrap=true %}
Add a Paddle Checkout integration to this Next.js app. Use the paddle-docs MCP server to look up the current Paddle.js syntax. Then use the paddle-sandbox MCP server to create three products in my sandbox account — Starter ($10/mo), Pro ($30/mo), Enterprise ($300/mo) — and generate a /pricing page that opens checkout for each tier. Wire up a /api/webhooks route that verifies the signature and logs transaction.completed events.
```

Gemini uses the docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and writes code that matches your `GEMINI.md` conventions.

## Best practices

- **Mention Paddle and the relevant MCP server explicitly.**  
  "Use the paddle-docs MCP server to look up X" beats hoping the agent calls it on its own.
- **Be specific in prompts.**  
  Concrete pricing, event names, and entity IDs work better than vague descriptions.
- **Review tool calls before approving them.**  
  Gemini CLI prompts before executing MCP tools. Read every call, especially anything destructive.
- **Never commit API keys.**  
  Keep API keys in environment variables.
- **Create your own skills.**  
  When you find yourself repeating the same instructions over and over, package them as a SKILL.md file in your project's `skills/` directory. Gemini auto-discovers them.