Quick start
The default command is a dry run. It reports findings and never changes files.
npx placeholder-photo-migrate .Apply verified migrations only:
npx placeholder-photo-migrate . --writeUse the non-writing CI check:
npx placeholder-photo-migrate . --checkSafe automatic migrations
The CLI preserves supported dimensions, colours, foreground colour, custom text, URL encoding, query strings and formats. Verified automatic providers are via.placeholder.com, placehold.it, conservative legacy placeholder.com image paths, placehold.co, dummyimage.com, placehold.jp and imageplaceholder.net.
Ambiguous or non-equivalent URLs are never rewritten blindly. They remain unchanged and are reported as manual review required.
Photo and detection-only services
The scanner detects popular services including picsum.photos, unsplash.it, loremflickr.com, placeimg.com, lorempixel.com, placekitten.com, source.unsplash.com, fakeimg.pl and placehold.net. Random, seeded, category or photo identity cannot be translated losslessly to a different catalogue, so these findings require manual review.
Options and reports
--write Apply safe migrations
--check CI check; never writes
--provider <provider> Limit selected providers
--report <file> Write a local JSON reportExit code 0 means no selected legacy URLs were found, 1 means findings remain or were migrated during that run, and 2 indicates a usage, filesystem or runtime error.
Files and project safety
The scanner supports HTML, CSS and preprocessors, JavaScript and TypeScript families, Vue, Svelte, PHP, Markdown, JSON, YAML, XML and text files. It skips binaries, invalid UTF-8, files above 10 MiB, symlinks and common dependency, build, cache and temporary directories. Git ignore rules are respected where practical, reports remain inside the project, and writes use same-directory atomic replacement.
Privacy and offline operation
Your source code is never uploaded to Placeholder.photo. The CLI runs locally, collects no telemetry or analytics, sends no project identifiers, and uses no migration-time API. After npm installation, normal scanning and migration work offline with local versioned rules.
CI example
- name: Check legacy placeholder URLs
run: npx --yes placeholder-photo-migrate . --checkPackage and support
Requires Node.js 22 or newer. Install and run the public placeholder-photo-migrate package on npm, review the official GitHub repository, or report problems through GitHub Issues. The MIT-licensed tool is built by Jansma VIP for Placeholder.photo.