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

---

{% callout type="note" %}
Gemini CLI has been replaced by Antigravity CLI and is no longer available, except for enterprise customers. Antigravity CLI plugins don't support authentication (see issue [#25](https://github.com/google-antigravity/antigravity-cli/issues/25)), so your extension won't work when you upgrade. We recommend installing [skills](https://developer.paddle.com/sdks/ai/agent-skills.md) and [MCP servers](https://developer.paddle.com/sdks/ai/paddle-mcp.md) manually until Google resolves this issue.
{% /callout %}

[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 account that you want to connect to — [sandbox](https://developer.paddle.com/sdks/sandbox.md), live, or both.
- If connecting to a sandbox account, 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.

## Connect the Paddle MCP servers {% 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                                  | Authentication    |
| ---------------- | ------------------------------------ | ----------------- |
| `paddle-sandbox` | `https://sandbox-mcp.paddle.com/mcp` | API key           |
| `paddle-live`    | `https://mcp.paddle.com/mcp`         | OAuth or API key |

`paddle-sandbox` reads a sandbox [API key](https://developer.paddle.com/api-reference/about/authentication.md) from an environment variable. Create a key at **Paddle > My account > Settings > Authentication**, then export it in your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent):

```sh
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.

{% callout type="warning" %}
A live connection made with OAuth has the same **read** access as your Paddle user role. You can change this under **Paddle > Connectors > MCP**. Access to sandbox is determined by its API key permissions, so scope the key to only what the agent needs.
{% /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, 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 {% 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.