> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # Resource commands Use Paddle CLI resource commands to work with entities in your Paddle account, and see how their arguments and flags map to API operations. --- Resource commands work with entities in your Paddle account, like products, customers, and subscriptions. They're generated from the [Paddle API](https://developer.paddle.com/api-reference.md), and each command matches an API operation. Learn how resource commands work on this page, then use the [API reference](https://developer.paddle.com/api-reference.md) to see what each command does, which fields it accepts, and what it returns. ## Mapping to the API The structure of resource commands follows this pattern: ```sh paddle [ID] [flags] ``` Each part of the command comes from the API: | Part | Comes from | Example | | ------------- | --------------------------------------------- | ---------------------------------------- | | `` | The section of the API reference. | `products`, `notification-settings` | | `` | The API operation. | `list`, `get`, `create`, `update` | | `[ID]` | Paddle IDs in the endpoint path. | `pro_01htz88xpr0mm7b3ta2pjkr7w2` | | `[flags]` | Query parameters and the request body. | `--status active`, `--json @product.json` | Here's how some API operations map to full CLI commands: | API operation | CLI command | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [List products](https://developer.paddle.com/api-reference/products/list-products.md) | `paddle products list` | | [Update a product](https://developer.paddle.com/api-reference/products/update-product.md) | `paddle products update pro_01htz88xpr0mm7b3ta2pjkr7w2 --json '{...}'` | | [Cancel a subscription](https://developer.paddle.com/api-reference/subscriptions/cancel-subscription.md) | `paddle subscriptions cancel sub_01h3h3a9sfpr5syq38tq0sd4sp --json '{...}'` | Run `paddle --help` to see every operation for a resource in your installed version of the CLI. For details about each operation, see the [API reference](https://developer.paddle.com/api-reference.md). New API operations and query parameters come to the CLI in a new version. If your version doesn't have a command for an operation yet, [update the CLI](https://developer.paddle.com/sdks/cli.md#update), or use [`paddle api`](https://developer.paddle.com/sdks/cli/commands.md#paddle-api) to call the endpoint directly: ```sh paddle api /subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/history ``` ## Paddle IDs Commands that work with one entity, like `get`, `update`, or `cancel`, take its [Paddle ID](https://developer.paddle.com/api-reference/about/paddle-ids.md) as an argument: ```sh paddle customers get ctm_01hv6y1jedq4p1n0yqn5ba3ky4 ``` When a command takes more than one ID, pass them in the order they appear in the endpoint path. For example, `paddle addresses get` takes the customer ID, then the address ID, like `GET /customers/{customer_id}/addresses/{address_id}`: ```sh paddle addresses get ctm_01hv6y1jedq4p1n0yqn5ba3ky4 add_01hv8gq3318ktkfengj2r75gfx ``` Only IDs in the endpoint path are arguments. To check which IDs a command takes, and in what order, run it with `--help`. To find an ID, run a `list` command, like `paddle customers list`, or copy it from the Paddle dashboard. ## Query parameters Query parameters become flags in the CLI, with underscores changed to hyphens. For example, `per_page` becomes `--per-page`, and `order_by` becomes `--order-by`. ```sh paddle customers list --status active --email jo@example.com paddle transactions list --subscription-id sub_01h3h3a9sfpr5syq38tq0sd4sp --per-page 10 ``` Put values that contain square brackets in quotes, like `--order-by 'billed_at[ASC]'`. Where the API accepts a comma-separated list, the flag does too: ```sh paddle products list --status active,archived --include prices ``` Resource commands only accept exact dates. To filter by a date range, like transactions billed before a date, use [`paddle api`](https://developer.paddle.com/sdks/cli/commands.md#paddle-api): ```sh paddle api /transactions --query 'billed_at[LT]=2026-10-01T00:00:00Z' ``` ## Request bodies Commands that send a request body, like `create`, `update`, and `cancel`, take it as JSON with `--json`. Pass it inline, or from a file with `@`: ```sh paddle products create --json '{"name": "AeroEdit Student", "tax_category": "standard"}' paddle products create --json @product.json ``` The CLI checks that your JSON is valid before it sends anything. Fields in the request body are the same as in the API reference. To see them in your terminal, use `--help` for a readable list or `--schema` for the full JSON schema: ```sh paddle products create --help paddle products create --schema ``` ## Output The CLI can return results as a table, JSON, or CSV. In a terminal, results show as a table. When you send output to another program or a file, the CLI uses JSON instead. Choose a different format with `--output`, or `-o` for short: ```sh paddle products get pro_01htz88xpr0mm7b3ta2pjkr7w2 --output json paddle customers list -o csv > customers.csv ``` Tables truncate nested fields, like a subscription's `items` or `scheduled_change`. To see their full values, use `--output json`. In a terminal, the JSON is indented for easier reading. JSON output is the same as the [Paddle API](https://developer.paddle.com/api-reference.md) response, with `meta.environment` added to show which account the command ran against, `sandbox` or `production`. To change the default, run `paddle output json` or set the `PADDLE_OUTPUT` environment variable. ## Filter results Use `--jq` to filter or reshape results with a [jq](https://jqlang.org) expression. You don't need jq installed. ```sh paddle customers list --jq '.data | map({id, email})' paddle customers list --jq '.data | length' ``` The filter runs before the CLI formats results. It works with tables and CSV too. ## Pagination List commands return one page of results. Use `--per-page` to set how many results to return, and `--after` to get the next page. When there are more results, the CLI prints the command for the next page. ```sh paddle customers list --per-page 50 paddle customers list --per-page 50 --after ctm_01hv6y1jedq4p1n0yqn5ba3ky4 ``` In JSON output, the command for the next page is in `meta.pagination.next_command`. For more on how pagination works, see [Pagination](https://developer.paddle.com/api-reference/about/pagination.md). ## Delete and cancel Commands that delete or cancel something, like `paddle subscriptions cancel`, ask you to confirm before they run. In a terminal, type `y` at the prompt. When there's no prompt, like in a script or when an AI agent runs the CLI, pass the same ID again with `--confirm`: ```sh paddle notification-settings delete ntfset_01j82d983j814ypzx7m1fw2jpz --confirm ntfset_01j82d983j814ypzx7m1fw2jpz ```