ScreenshotMachine CLI Cannot Load a Local HTML File: Troubleshooting
ScreenshotMachine’s documented API takes a web URL, not a local file path. Learn how to identify the CLI, render HTML locally, or serve it for capture.
Short answer: ScreenshotMachine’s documented Website Screenshot API takes the page to capture through a url parameter. The official examples show sending a web URL and saving the returned image to a local output file. The documentation reviewed here does not describe a local filesystem path or file:// URL as supported input. [ScreenshotMachine API documentation] [ScreenshotMachine examples]
The title says “CLI,” but the available authoritative material documents the hosted API and example client code, not a canonical ScreenshotMachine CLI. A third-party command-line wrapper may behave differently. First identify the executable and version; then use the workflow below that matches whether your HTML must stay on your machine.
1. Confirm what the command is actually calling
- Find the executable name and package that installed it. Check its version and help output (for example, the command’s documented
--versionand--helpoptions, if present). - Inspect the command’s input argument. If it sends the target as ScreenshotMachine’s
url, a local path such as./page.htmlis not the web page URL described in the API documentation. - Separate the input from the output. In ScreenshotMachine’s Bash example, the request supplies a page URL and redirects the returned image to a local filename. That output filename does not tell the service where to find the input HTML. [ScreenshotMachine Bash example]
- Save the exact invocation and complete error output, but remove API keys, cookies, and other secrets before sharing them.
Do not assume that a command called a “ScreenshotMachine CLI” is an official client or accepts the same schemes as the API. The sources reviewed do not establish its package, flags, version, or error behavior.
2. Choose a workflow for the HTML file
| Workflow | Input the renderer needs | Use it when |
|---|---|---|
| ScreenshotMachine API | A page URL supplied as url |
The capture service can retrieve the page over the network. |
Local-file renderer such as shot-scraper |
A path to an HTML file | The file should be rendered directly from disk. The shot-scraper documentation describes HTML file paths; this is a separate tool, not a ScreenshotMachine feature. [shot-scraper documentation] |
| Serve the HTML, then capture its URL | A URL reachable by the capture service | You want to keep ScreenshotMachine in the workflow and can make the page available to it. This follows from the API’s URL input; reachability depends on your network setup. [ScreenshotMachine API documentation] |
A development server bound only to localhost or 127.0.0.1 on your computer is ordinarily reachable from your own browser, but that does not make it reachable from a remote capture service. Use a network-reachable staging URL or a local renderer when the page must remain on your machine. Consider access controls and the sensitivity of the HTML before exposing it.
3. Render a local HTML file with a local renderer
When the input must remain a disk file, use a tool whose documentation explicitly accepts a local HTML path. The following example follows the documented shot-scraper command pattern; check its current installation and command options in its documentation before using it.
shot-scraper ./page.html -o screenshot.pngKeep the file’s dependent assets available as well. Relative stylesheets, scripts, fonts, and images resolve relative to the document location or its base URL. If an asset is missing, the page can render but look incomplete. For a multi-file project, run the page through your normal local web server and use the server URL with a local browser capture tool, or ensure the renderer can resolve the project’s relative assets.
For reproducible captures, use the same browser version, viewport, device scale, fonts, and wait condition on each run. A screenshot taken before client-side rendering finishes can be blank or incomplete even though the file opened successfully.
4. Keep ScreenshotMachine in the flow by providing a reachable URL
If the HTML can be served where ScreenshotMachine can retrieve it, pass that page URL as the API’s url input. The API documentation describes the parameter as the web page URL to capture and recommends URL encoding; its parameter notes say the http(s):// prefix is optional. [ScreenshotMachine API documentation]
For a real deployment, replace the example URL with the reachable page URL and use the request syntax documented for your account and desired output. Do not put a private API key in a public repository or expose it in a client-side application.
curl -G 'https://api.screenshotmachine.com' \
--data-urlencode 'key=YOUR_SCREENSHOTMACHINE_KEY' \
--data-urlencode 'url=https://example.com/page.html' \
-o screenshot.pngThis illustrates the documented URL-input and local-output pattern. The dossier does not provide a complete endpoint specification or current options for every account, so consult ScreenshotMachine’s official API docs for the exact endpoint, authentication parameter, output format, and supported options for your setup.
Make sure that the URL works from outside your development machine. A private hostname, firewall, login-only page, or loopback address can prevent a hosted service from fetching it. If the page requires authentication, check the API’s documented authentication and request options rather than assuming local browser cookies are sent automatically.
5. Troubleshoot common symptoms
| Symptom | Likely cause | What to do |
|---|---|---|
The CLI rejects ./page.html or says the URL is invalid |
The command may be passing a filesystem path into an API input documented as a web URL. | Confirm the command implementation. Use a renderer with documented local-file support, or serve the HTML and pass a reachable URL. |
| The request succeeds but the image is an error page or empty | The remote service could not retrieve the page, or the page failed to load before capture. | Open the URL from a machine outside your local network, verify the response and access requirements, and inspect the returned image. Do not infer local-server reachability from success in your own browser. |
| The screenshot is missing styles, fonts, or images | Relative assets may resolve differently, be unavailable remotely, or be blocked by access rules. | Check asset paths and network access from the renderer. Prefer absolute reachable asset URLs or serve the complete project structure consistently. |
| The screenshot captures a loading state | JavaScript rendering or asynchronous assets may not have finished. | Use the selected tool’s documented wait mechanism and wait for a page-specific ready condition where available. Avoid arbitrary long delays unless the page has no better readiness signal. |
| A loopback URL works locally but fails in hosted capture | localhost refers to the machine making the request, which is different from your workstation for a remote service. |
Provide a network-reachable staging URL or use local rendering. |
| The CLI behavior does not match this guide | The title may refer to a wrapper with its own supported inputs and flags. | Record package/executable name, version, operating system, exact command with secrets removed, full error, and whether the HTML uses relative assets. Check that tool’s own documentation. |
6. Cost, reliability, and privacy considerations
- Hosted capture: The API must be able to reach the page. Account limits and charges depend on the provider and plan; the sources reviewed do not establish a price or a special upgrade that enables local-file input.
- Local capture: The HTML can remain on your machine, but browser installation, fonts, dependencies, and environment consistency become your responsibility.
- Repeatability: Keep viewport, browser/runtime versions, font availability, wait conditions, and asset versions stable when screenshots are used for visual checks.
- Reliability: Distinguish a successful API response from a correct rendered page. Inspect status and the image content; a saved output file alone does not prove that the target page rendered as intended.
- Privacy: Before making a local page reachable to a hosted service, check whether it contains credentials, personal data, or unpublished content and restrict access appropriately.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request accepts a URL and returns PNG, JPEG, WebP, or PDF. Like other hosted URL workflows, the page must be available to the service; this does not make a disk-only HTML file a remote URL. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and the response identifies the page verdict and billing status in headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account to try 1,000 screenshots a month with no card.
FAQ
Can ScreenshotMachine take a screenshot of a local HTML file?
The API documentation reviewed here describes a web page URL as the capture input and does not document a local filesystem path or file:// URL. For a definitive answer about a particular CLI wrapper, identify its package and version and check that wrapper’s documentation.
Why does a local output filename work if a local HTML input does not?
The output filename is where your command writes the image returned by the service. The input tells the service what page to fetch. Those are separate paths.
What information should I include when asking for CLI-specific help?
Include the executable or package name, version, operating system, exact command with secrets removed, full error text, and whether the HTML uses relative assets. That distinguishes API input limitations from wrapper-specific behavior.
