Printify CLI

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 blueprint
• printify-pp-cli catalog retrieve-alist-of-available-print-providers - Retrieves the list of blueprints in the catalog to explore from
• printify-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 from
• printify-pp-cli catalog retrieve-aspecific-print-provider - Retrieves the list of blueprints in the catalog to explore from
• printify-pp-cli catalog retrieve-available-shipping-list-information - Retrieves the list of print providers avilable for the Blueprint
• printify-pp-cli catalog retrieve-economy-shipping-method-information - Retrieves the list of print providers available for the Blueprint
• printify-pp-cli catalog retrieve-express-shipping-method-information - Retrieves the list of print providers available for the Blueprint
• printify-pp-cli catalog retrieve-priority-shipping-method-information - Retrieves the list of print providers available for the Blueprint
• printify-pp-cli catalog retrieve-shipping-information - Retrieves the list of print providers avilable for the Blueprint
• printify-pp-cli catalog retrieve-specific-shipping-method-information - Retrieves the list of print providers avilable for the Blueprint
• printify-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 image
• printify-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:

• TSavo/printify-mcp — JavaScript/TypeScript (27 stars)
• lawrencemq/printipy — Python (17 stars)

Generated by CLI Printing Press