Printful API CLI

Independent CLI over the Printful API. It is not an official Printful product. It prints JSON, keeps the API's field names unchanged, and requires an explicit --yes for every write.

Auth

Create a private token at https://developers.printful.com/tokens, or use an OAuth access token from a Printful app. Both are sent as Authorization: Bearer.

printf '%s' "$TOKEN" | printful-api auth --token-stdin   # verifies with GET /oauth/scopes, saves 0600
printful-api whoami                                       # scopes + stores

PRINTFUL_TOKEN overrides the saved token. Credentials are stored in ~/.config/printful-api/credentials.json, and XDG_CONFIG_HOME is respected.

Account-level tokens must name a store for store endpoints (orders, products, shipping rates). Pass it with --store-id <id> or PRINTFUL_STORE_ID; the CLI sends it as the X-PF-Store-Id header. Store-level tokens and OAuth tokens don't need it.

Commands

There are 56 commands, one per API v1 operation. They are generated by scripts/generate.py from the official OpenAPI spec at https://developers.printful.com/docs/openapi.json and grouped by the spec's tags:

printful-api catalog get-products --category_id 24
printful-api orders get-orders --status draft --limit 20
printful-api orders create-order --data @order.json --dry-run
printful-api orders create-order --data @order.json --yes          # draft; add --confirm true to submit (charged)
printful-api shipping-rate calculate-shipping-rates --data '{"recipient":{"country_code":"US"},"items":[{"variant_id":4012,"quantity":1}]}' --yes
printful-api products update-sync-product <id> --data @patch.json --yes
printful-api orders create-order --schema                         # body schema, offline
printful-api request GET /v2/catalog-products --query limit=5      # v2 beta or anything else

Rate limit: 120 requests/minute, lower for the mockup generator. On a 429 the error includes retry_after. The CLI never retries.

Develop

bun test && bun run test:node