cimplify assets

cimplify assets is the dev/agent surface for getting brand and product media onto the Cimplify CDN (storefrontassetscdn.cimplify.io). It wraps /v1/businesses/{id}/assets/* with a small client-side manifest cache (./cimplify-assets.json) for build-time URL substitution.

For customer-runtime uploads (receipts attached to support tickets, profile photos uploaded inside a live storefront), use the SDK's client.uploads.upload(file) instead; those land in the private bucket as documented in Uploads.

Usage

cimplify assets upload <dir> [--folder <path>] [--force]
cimplify assets ls [--prefix <folder>] [--type <mime-prefix>]
cimplify assets rm <upload_id-or-key>

upload <dir>

Walks the directory recursively and uploads each file to the Cimplify CDN. Writes a manifest at ./cimplify-assets.json keyed by manifest path → entry so re-runs are idempotent: files whose SHA-256 matches the existing entry are skipped unless --force is passed.

cimplify assets upload public/hero/

Output:

▸ skip  hero/main.jpg (unchanged)
▸ →     hero/banner-wide.jpg (482915 bytes)
✓ Uploaded 1 file (1 skipped)
  Manifest: /path/to/store/cimplify-assets.json

Flags

What lands on the CDN

A file at public/hero/main.jpg uploaded with --folder hero lands at:

https://storefrontassetscdn.cimplify.io/assets/{business_id}/hero/main.jpg

assets/ is the key_prefix configured on the storefront_assets use; {business_id} is your linked business; the rest is the folder + file path you supplied. URLs are deterministic: the init call returns public_url_preview so agents can pre-compute the final URL before the PUT happens.

Supported content

Up to 50 MB per file, any MIME type:

• Images: jpg, jpeg, png, gif, webp, avif, svg
• Documents: pdf
• Video: mp4, webm (short clips: the 50 MB cap suits hero loops and product demos; full-length streaming needs Drive Phase 10)
• 3D: glb, gltf, usdz (product viz / AR; render with <model-viewer> or Three.js)
• Fonts: woff, woff2, ttf
• Anything else with a valid MIME type

The server doesn't transcode or thumbnail; it stores raw bytes and serves them via the public CDN. For browser-playable adaptive video, see Drive's AV pipelines roadmap.

ls [--prefix <folder>] [--type <mime>]

Lists the business's confirmed storefront assets from the server (works from any machine, not just one with a local manifest). Auto-paginates.

cimplify assets ls
cimplify assets ls --prefix hero
cimplify assets ls --type video/
cimplify assets ls --type model/

Output:

Storefront assets (3 total):
  ● hero/main.jpg                          image/jpeg               482.0 KB  upl_01H...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg
  ● hero/promo.mp4                         video/mp4                 12.34 MB  upl_02J...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/promo.mp4
  ● products/laptop-pro.glb                model/gltf-binary          4.20 MB  upl_03K...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/products/laptop-pro.glb

Flags

--json emits the full server response (assets array + pagination) as a structured envelope.

rm <upload_id-or-key>

Deletes the asset on the server (DB row + best-effort blob delete) and prunes the local manifest entry. Idempotent: passing an already-gone id still returns 0.

# Delete by upload_id from `ls` output
cimplify assets rm upl_01H...

# Or by manifest key, if `./cimplify-assets.json` has it
cimplify assets rm hero/old-banner.jpg

Output:

✓ Removed hero/old-banner.jpg

If you're on a fresh machine without the local manifest, use the upl_… id from cimplify assets ls.

Manifest format

./cimplify-assets.json is a JSON object keyed by manifest path. It's a build-time cache for URL substitution and the rm-by-key convenience; the server is the source of truth, so a missing or stale manifest doesn't break upload/ls/rm.

{
  "hero/main.jpg": {
    "url": "https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg",
    "upload_id": "upl_01H...",
    "folder": "assets/hero",
    "filename": "main.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 482915,
    "sha256": "abc123...",
    "uploaded_at": "2026-05-13T12:00:00.000Z"
  }
}

Commit it. Storefront source code and CI agents read it for URL references; upload keeps it in sync.

Wiring in storefront code

Templates ship a lib/cimplify-loader.ts and have images.loaderFile set in next.config.ts to that file. Every <Image src=> flows through the loader; the loader detects Cimplify-hosted URLs (relative paths, the configured CDN base, known Cimplify hosts) and applies the transform contract. External hosts (Cloudinary, Unsplash, merchant S3) pass through unchanged.

import Image from "next/image";
import { assetUrl } from "@cimplify/sdk";

<Image src={assetUrl("hero/main.jpg")} alt="..." width={1200} height={800} />

Or for a typed React-hook entry point:

import { useImage } from "@cimplify/sdk/react";

function Hero() {
  const { src, loader } = useImage("hero/main.jpg", { format: "webp" });
  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;
}

For video and 3D, drop the URL into the appropriate tag; the SDK doesn't yet wrap them with polished components, but raw HTML works today:

<video src={assetUrl("hero/promo.mp4")} autoPlay muted loop playsInline />

<model-viewer src={assetUrl("products/laptop-pro.glb")} ar camera-controls />

Auth + scopes

cimplify assets calls /v1/businesses/{id}/assets/* with your dk_live_… key, the same auth path every cimplify deploy, cimplify env push, etc. uses. No separate token to provision.

Exit codes

JSON mode emits a single envelope per command:

cimplify assets upload public/hero/ --json

{
  "ok": true,
  "data": {
    "uploaded_count": 3,
    "skipped_count": 1,
    "manifest_path": "/path/to/cimplify-assets.json",
    "uploaded": ["assets/hero/main.jpg", "assets/hero/banner.jpg", "assets/hero/mobile.jpg"],
    "skipped": ["assets/hero/old.jpg"]
  }
}