pod-cli

A zero-dependency, margin-gated print-on-demand workflow CLI for Printify — upload print files, create and publish products, and refuse to ship anything below your profit floor. Dry-run first: the whole pipeline is testable before you have an account or a token.

• Zero dependencies. Pure Python standard library. Clone and run, or pip install.
• Margin gate built in. Every create runs a MARGIN-1 profit check (default ≥50% net after single-item shipping, apparel returns reserve, and channel fees). Below the floor it blocks — reprice, pick a cheaper blank, or pass an explicit, logged --allow-below-floor exception. Never eat the floor by accident.
• Dry-run first. --dry-run prints the exact HTTP request (Authorization redacted) and sends nothing. price-check and skus run fully offline.
• Your catalog stays in data. SKUs load from a JSON file you provide (--skus), so the tool carries no products of its own — point it at your file.
• Rate-limit hygiene. Reads X-Ratelimit-*, paces requests, and backs off on HTTP 429 (honoring Retry-After).
• Secrets stay out of the repo. Token/shop id live in ~/.config/pod/.env.

$ pod price-check --skus skus.json
$ pod --dry-run whoami
$ pod --dry-run upload logo-tote --skus skus.json --sku-dir ./art
$ pod --dry-run create logo-tote --skus skus.json --blueprint 384 --provider 1

Install / run

git clone https://github.com/Pvragon/pod-cli && cd pod-cli
./pod price-check --skus examples/skus.example.json    # no install, no token
# or
pip install -e . && pod price-check

Python 3.10+.

Configure (to go live)

~/.config/pod/.env:

PRINTIFY_API_TOKEN=your_personal_access_token
PRINTIFY_SHOP_ID=your_connected_shop_id

Then pod whoami → pod catalog "<query>" (resolve the real blueprint + print_provider + live print_area) → upload → create → publish.

Your SKU file

Copy examples/skus.example.json to skus.json and edit. Each SKU declares its print file, target dims, placement, decoration method, target retail, and your ballpark base + single-item shipping cost (the floor binds at live quotes). See the example for the full shape.

Commands

Command	What	Token?
price-check [--channel etsy|shopify]	MARGIN-1 across the catalog	no
skus	list the registry	no
whoami	GET /v1/shops.json — token check	yes / --dry-run
catalog "<query>"	list blueprints (resolve live print_area)	yes
upload <sku>	base64-upload the print file → image id	yes
create <sku> --blueprint N --provider M	create a product — MARGIN-1 gated	yes
publish <product_id>	push live to the connected store	yes
generate --designs D --blanks B [--out skus.json]	cross a design × blank catalog into a curated SKU catalog (SEO + collections + margin)	no

Scaling a catalog with generate

POD stores win on a large, well-curated catalog, not a boutique few — but a blanket dump of generic SKUs is invisible in search. generate builds volume with curation: it crosses a design catalog (examples/designs.example.json) with a blank catalog (examples/blanks.example.json) and, for each compatible pairing, emits a SKU with an auto-solved floor-clearing retail, a collection, and up to 13 SEO tags — pairs that can't clear the floor at a plausible price are flagged REVIEW, not shipped. Grow the design catalog to scale the store; the margin gate is the curation that keeps volume from becoming unprofitable spam. Set a per-blank max_retail so a mug caps lower than a framed print.

Design notes / scope

The Printify decoration model and upload flow (POST /v1/uploads/images.json accepting a hosted url or base64 contents → image id → referenced in print_areas) are per Printify's developer docs. Field names are validated against the live API when you run with a token; --dry-run shows exactly what would be sent.

Prior art & why this exists

Good Printify tooling already exists — this deliberately does something narrower and different:

• PrintiPy — a full-featured Python library for the Printify API. If you want a rich SDK to build on, use it. pod-cli is a thin, dependency-free workflow CLI, not a library; if you'd rather not maintain raw HTTP calls, wrapping PrintiPy is a reasonable alternative to this.
• printify-mcp — an MCP server exposing Printify to AI assistants. Different integration model (in-session tools vs a scriptable CLI that runs in CI and by hand).
• printing-press-library — manifest-driven Printify product creation/auditing.

What pod-cli adds to that ecosystem: zero dependencies, a profit-floor gate as a first-class, blocking step, dry-run-first safety, and catalog-as-data. It began as internal store-ops automation and is released in that spirit — small, honest, and useful if those properties matter to you.

License

MIT © Pvragon. See LICENSE.