Create and audit Printify products with manifest-driven image uploads, personalization checks, and local proofing.
This CLI covers Printify's official product, upload, catalog, order, shop, and webhook API surface, then adds workflow commands for product creation confidence. Agents can compile personalized manifests, upload images, validate placement, compare drift, and inspect fulfillment risk without parsing raw nested API payloads.
Created by @horknfbr (horknfbr).
Authentication
Printify uses a personal access token as a bearer token. Set PRINTIFY_API_TOKEN in your environment or .env; do not pass the token as a command argument.
Quick Start
# Find the shop ID to use for product and order work while keeping the response small.
printify-pp-cli shops-json --agent --select id,title
# Choose a blueprint before selecting a print provider or variants.
printify-pp-cli catalog retrieves-list-of-blueprints-in-the --agent --select id,title
# Upload product artwork before composing the product manifest.
printify-pp-cli uploads an-image --body-json '{"file_name":"front.png","contents":"data:image/png;base64,iVBORw0KGgo="}' --agent
# Create a draft product from a prepared manifest.
printify-pp-cli shops products-json create-anew-product 123456 --title Sample --blueprint-id 384 --print-provider-id 1 --variants '[]' --print-areas '[]' --agent
# Compare the intended manifest with the product that now exists in Printify.
printify-pp-cli product-drift --product-file ./examples/current-product.json --manifest ./examples/sample-product.json --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Product proofing
-
personalization-audit — Audit a product for documented personalization placeholder fields, missing text/image setup, and unsupported browser-only gaps.
Use this before publishing a personalized product or before handing a manifest to another agent.
printify-pp-cli personalization-audit --product-file ./examples/sample-product.json --agent
-
placement-matrix — Show variant, print-area, placeholder, uploaded image, x/y/scale/angle, and missing-placement rows for a product.
Use this when an agent must prove artwork placement is consistent across variants.
printify-pp-cli placement-matrix --product-file ./examples/sample-product.json --uploads-file ./examples/sample-uploads.json --agent
-
product-drift — Compare an intended product manifest against the current Printify product payload after create or update.
Use this after automation creates a product and before trusting the resulting listing.
printify-pp-cli product-drift --product-file ./examples/current-product.json --manifest ./examples/sample-product.json --agent
Catalog decisions
-
catalog-margin-matrix — Join catalog variants and shipping data to estimate per-variant cost and margin at a target retail price.
Use this before creating a batch when product economics matter more than raw catalog browsing.
printify-pp-cli catalog-margin-matrix --variants-file ./examples/sample-variants.json --shipping-file ./examples/sample-shipping.json --target-price 24.99 --agent
Batch automation
-
personalization-batch — Expand a reusable product manifest and CSV rows into per-product manifests using documented image and text placeholder fields.
Use this when an agent needs repeatable personalized product drafts before making API writes.
printify-pp-cli personalization-batch --template ./examples/template-product.json --csv ./examples/personalization.csv --out ./examples/generated-manifests --agent
Operational audits
-
asset-reuse — List uploaded images, where each is used, unused uploads, and products sharing the same artwork.
Use this to clean upload libraries or verify that a product batch reuses the expected artwork.
printify-pp-cli asset-reuse --products-file ./examples/sample-products.json --uploads-file ./examples/sample-uploads.json --agent
-
fulfillment-risk — Flag open orders tied to risky product, variant, publish, or shipment states.
Use this when an agent needs to find fulfillment problems before customer-service work starts.
printify-pp-cli fulfillment-risk --orders-file ./examples/sample-orders.json --products-file ./examples/sample-products.json --agent
Recipes
Find a shop with narrow output
printify-pp-cli shops-json --agent --select id,title
Use this first so follow-up product and order commands target the right shop without dumping the full shop payload.
Compile personalized product manifests
printify-pp-cli personalization-batch --template ./examples/template-product.json --csv ./examples/personalization.csv --out ./examples/generated-manifests --agent
Turn a reusable template and row data into deterministic product manifests before any API writes.
Proof artwork placement
printify-pp-cli placement-matrix --product-file ./examples/sample-product.json --uploads-file ./examples/sample-uploads.json --agent --select variant_id,print_area,image_id,x,y,scale,angle
Inspect only the placement columns an agent needs before publishing.
Check product drift after create
printify-pp-cli product-drift --product-file ./examples/current-product.json --manifest ./examples/sample-product.json --agent
Confirm the remote product still matches the manifest the automation intended.
Scan fulfillment risk
printify-pp-cli fulfillment-risk --orders-file ./examples/sample-orders.json --products-file ./examples/sample-products.json --agent
Join orders, variants, product state, and shipment state into a single operational risk view.
Usage
Run printify-pp-cli --help for the full command reference and flag list.
Commands
catalog
Browse the Printify catalog including blueprints, print providers, product variants, and shipping information. Explore available products and their customization options.
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint - Retrieve a list of all print providers that fulfill orders for a specific blueprintprintify-pp-cli catalog retrieve-alist-of-available-print-providers - Retrieves the list of blueprints in the catalog to explore fromprintify-pp-cli catalog retrieve-alist-of-variants-of-ablueprint-from-aspecific-print-provider - Retrieves the list of of variants options for the Print Provider and Blueprint.
Those form the set of options available for customization Product (Blueprint)
on particular manufacturer (Print Provider).printify-pp-cli catalog retrieve-aspecific-blueprint - Retrieves the list of blueprints in the catalog to explore fromprintify-pp-cli catalog retrieve-aspecific-print-provider - Retrieves the list of blueprints in the catalog to explore fromprintify-pp-cli catalog retrieve-available-shipping-list-information - Retrieves the list of print providers avilable for the Blueprintprintify-pp-cli catalog retrieve-economy-shipping-method-information - Retrieves the list of print providers available for the Blueprintprintify-pp-cli catalog retrieve-express-shipping-method-information - Retrieves the list of print providers available for the Blueprintprintify-pp-cli catalog retrieve-priority-shipping-method-information - Retrieves the list of print providers available for the Blueprintprintify-pp-cli catalog retrieve-shipping-information - Retrieves the list of print providers avilable for the Blueprintprintify-pp-cli catalog retrieve-specific-shipping-method-information - Retrieves the list of print providers avilable for the Blueprintprintify-pp-cli catalog retrieves-list-of-blueprints-in-the - Retrieves the list of blueprints in the catalog to explore from
shops
Manage Printify shops and shop connections. Retrieve shop information and disconnect shops from your account.
shops-json
Manage shops json
printify-pp-cli shops-json - This will return the list of available merchant shops (IDs and titles)
uploads
Upload and manage images and assets. Upload images from URLs or base64-encoded content, retrieve upload information, and archive uploaded images.
printify-pp-cli uploads an-image - Upload an imageprintify-pp-cli uploads retrieve-an-uploaded-image-by-id - Retrieve an uploaded image by id
uploads-json
Manage uploads json
printify-pp-cli uploads-json - Retrieve a list of uploaded images
Output Formats
# Human-readable table (default in terminal, JSON when piped)
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint mock-value
# JSON for scripting and agents
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint mock-value --json
# Filter to specific fields
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint mock-value --json --select id,name,status
# Dry run — show the request without sending
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
printify-pp-cli catalog retrieve-alist-of-all-print-providers-that-fulfill-orders-for-aspecific-blueprint mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
printify-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/printify-public-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
PRINTIFY_BEARER_AUTH | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
printify-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $PRINTIFY_BEARER_AUTH
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 or unauthorized responses — Confirm
PRINTIFY_API_TOKEN is set from .env or your shell, then rerun printify-pp-cli health --agent.
- Product creation fails with missing variants or print areas — Run catalog blueprint/provider commands first, then regenerate the manifest with valid
blueprint_id, print_provider_id, variants, and print_areas.
- Personalization looks incomplete — Run
printify-pp-cli personalization-audit --product-file ./examples/sample-product.json --agent; the CLI reports documented fields separately from unsupported browser-only controls.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press