Build with Gemini CLI

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 account that you want to connect to — sandbox, live, or both.
• If connecting to a sandbox account, a sandbox API key with any permissions you plan to use.
• Gemini CLI installed.
• A project, with a Paddle SDK installed.

Install the Paddle extension

The Paddle Gemini extension bundles the Paddle agent skills with the docs MCP server and the Paddle MCP servers. Gemini auto-discovers the skills and connects the MCP servers when you install it.

From your terminal, run:

gemini extensions install PaddleHQ/paddle-agent-skills

Restart Gemini CLI for the extension to load.

Connect the Paddle MCP servers

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.

paddle-sandbox reads a sandbox API key from an environment variable. Create a key at Paddle > Developer tools > Authentication, then export it in your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

export PADDLE_SANDBOX_API_KEY= # Your sandbox API key

Restart Gemini CLI and your terminal after setting the variable so the MCP server picks it up.

paddle-live uses OAuth, so there's no key to set. The first time you use it, Gemini CLI opens your browser to authorize with Paddle. You can also run /mcp to authenticate.

Add Paddle conventions to your GEMINI.md

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.

## 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, canceling 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 languages your project uses. Gemini CLI loads this every time you start a session.

Prompt your first integration

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

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.