ScreenshotMachine CLI Review: Setup, Output Quality, and Limits
ScreenshotMachine’s documented terminal workflow uses Bash and curl to call its screenshot API. Here’s how to run it, choose settings, and understand its limits.
Direct answer: ScreenshotMachine’s documented command-line workflow is a Bash script that sends a request to its hosted screenshot API with curl and saves the image response to a file. The official materials covered here document that workflow, but do not establish a separately installed ScreenshotMachine CLI binary. This is a documentation-based review; it does not claim hands-on testing or independently measured image quality.
The workflow suits developers who want to trigger captures from a shell script, CI job, or other process that can make HTTP requests. You need a ScreenshotMachine account and customer key. The API settings let you shape the viewport, device mode, output format, timing, cache behavior, and some page interactions. The documentation does not establish current prices, quotas, or plan limits, so check the vendor’s current account information before planning usage around them.
What “ScreenshotMachine CLI” means
In the official materials reviewed for this guide, ScreenshotMachine is a hosted HTTP GET screenshot API. Its Bash and curl example is a shell wrapper around an API call: it sets request parameters and redirects the response into a local file. The vendor-maintained Bash repository is described as an example for calling the API, which is consistent with this interpretation.
That distinction matters when setting up a machine. The documented workflow needs Bash, curl, and an API key; the reviewed material does not describe installing a dedicated command such as screenshotmachine. The API does the browser capture remotely, while the shell command makes the request and writes the returned image.
Set up the Bash and curl workflow
- Create or access a ScreenshotMachine account and retrieve your customer key.
- Choose the page URL and capture settings. Start with a modest viewport and a common image format.
- Put the key and URL in the script below, then run it from Bash.
- Check that the response file exists and is non-empty. Open it to review the returned capture.
The following is a runnable request pattern using the documented API endpoint and parameter style. Replace the placeholders with your own values. Do not publish your customer key or secret phrase in source control, public HTML, logs, or screenshots.
#!/usr/bin/env bash
set -euo pipefail
CUSTOMER_KEY="YOUR_CUSTOMER_KEY"
TARGET_URL="https://example.com"
OUTPUT="output.png"
curl --fail --silent --show-error --get \
"https://api.screenshotmachine.com" \
--data-urlencode "key=${CUSTOMER_KEY}" \
--data-urlencode "url=${TARGET_URL}" \
--data-urlencode "dimension=1024x768" \
--data-urlencode "format=png" \
--data-urlencode "cacheLimit=0" \
--output "${OUTPUT}"
file "${OUTPUT}"
Save it as capture.sh, make it executable with chmod +x capture.sh, and run ./capture.sh. The example uses URL encoding for every parameter, including the target URL. This is important when values contain reserved characters.
ScreenshotMachine’s documentation shows a customer key, optional secret phrase, target URL, and screenshot settings sent as URL-encoded form data, with the response saved as output.png. It says to obtain the API key after signup. If you use a secret phrase, the docs say a corresponding hash is required; requests with a configured phrase but missing or incorrect hash are ignored. Follow the vendor’s current hash-generation instructions for that option rather than improvising a hash format.
Choose the output and capture settings
These documented controls define what to request. They do not guarantee a particular visual result on every site: the reviewed documentation supplies no independent image-quality score, rendering-fidelity measurement, or performance benchmark.
| Control | Documented behavior | When to use it |
|---|---|---|
| Width and height | Width from 100 to 1920 pixels; height from 100 to 9999 pixels. The value full is also accepted for full-page height. |
Set the width to the layout you need to inspect. Use full-page height when the whole document matters. |
| Device mode | Desktop, phone, and tablet modes. | Choose the intended device class when checking responsive layout. |
| Format | JPG, PNG, or GIF. | Choose based on your downstream use and the content being captured. |
| Delay | Values from 0 to 10,000 milliseconds in listed increments. | Allow time for images, animations, or page content to appear before capture. |
| Zoom | 10% to 400%. The documentation says zoom is ignored for screenshots smaller than typical device dimensions. | Use only when you need a different scale and the requested screenshot dimensions support it. |
| Cache age | 0 to 14 days. A value of 0 means do not use cache. | Use zero when you need to request a capture without using the cached image, subject to the service’s current behavior. |
| CSS interactions | CSS selectors can be used to click or hide page elements before capture. | Hide a known overlay or click a control when the target page needs that interaction. |
For full-page captures, ScreenshotMachine’s documentation advises using a longer delay on long pages that contain more images or animations, giving delay=2000 or more as an example. Treat that as guidance to adjust for the page, not a guarantee that a particular delay is sufficient.
Selector values need careful encoding. The documentation specifically calls out reserved characters such as # in CSS selectors. Use --data-urlencode with curl instead of manually assembling a query string; it encodes characters such as spaces, ampersands, and hash marks for transmission.
Save and validate the returned image
The shell redirect saves the API response body as a file. A successful HTTP transfer alone is not enough to confirm that the result is a usable image, so validate the output before passing it to another tool.
test -s output.png
file output.pngThe --fail option makes curl return a failure for HTTP error responses; --show-error prints transfer errors while --silent suppresses the progress meter. For production scripts, check the command’s exit status and file type, and keep API credentials in an environment variable or secret manager rather than committing them.
Call the API from Python
Python’s requests library handles URL encoding when given a parameter dictionary. This example writes the response body to a file and rejects unsuccessful HTTP responses.
import requests
params = {
"key": "YOUR_CUSTOMER_KEY",
"url": "https://example.com",
"dimension": "1024x768",
"format": "png",
"cacheLimit": "0",
}
response = requests.get(
"https://api.screenshotmachine.com",
params=params,
timeout=90,
)
response.raise_for_status()
with open("output.png", "wb") as image_file:
image_file.write(response.content)
Install the dependency with python -m pip install requests. For repeatable jobs, read the key from an environment variable and set a timeout appropriate to your workload. A timeout in your client prevents a stuck process from waiting forever; it does not change the remote capture’s behavior.
Call the API from Node.js
This example uses the built-in fetch and URLSearchParams APIs, then writes the returned bytes to a file. It requires a Node.js version with global fetch.
import { writeFile } from "node:fs/promises";
const params = new URLSearchParams({
key: "YOUR_CUSTOMER_KEY",
url: "https://example.com",
dimension: "1024x768",
format: "png",
cacheLimit: "0",
});
const response = await fetch(
`https://api.screenshotmachine.com?${params.toString()}`
);
if (!response.ok) {
throw new Error(`ScreenshotMachine returned HTTP ${response.status}`);
}
const image = Buffer.from(await response.arrayBuffer());
await writeFile("output.png", image);
Run it in an ES module file, such as capture.mjs, with node capture.mjs. For older Node.js versions without built-in fetch, use a supported HTTP client and preserve the same URL-encoding and binary-response handling.
Limits and output quality
The published dimension, delay, zoom, and cache ranges are configuration limits, not performance results. In practical terms, the requested image is bounded by the documented maximum width and height; a very long page may also need additional delay for content to load. The docs say zoom may be ignored when the screenshot is smaller than typical device dimensions.
Output quality cannot be concluded from the format list alone. PNG support does not establish that fonts, dynamic content, lazy images, or animations render faithfully on every site. The research for this review did not include hands-on captures or independent comparisons, so it cannot verify visual fidelity, capture speed, availability, or behavior on specific pages.
For predictable use, capture representative pages in your own workflow and check the resulting files at the dimensions and formats you intend to ship. Pay particular attention to pages that load content dynamically, use overlays, or rely on animation. Keep expectations tied to your own observed results rather than inferring them from available settings.
Performance, reliability, and cost considerations
- Capture time: A delay gives page content more time to load, but also lengthens the request. Full-page captures with many images or animations may need a higher delay than simple pages.
- Freshness: A cache age of zero requests that the cache not be used. The documented range extends to 14 days; decide whether freshness or reuse matters for your task.
- Failure handling: Check the HTTP result, client timeout, and saved file. Retry only errors that make sense to retry, and avoid rapid unbounded retries that can multiply requests.
- Credentials: Keep the key out of public code. For calls exposed in public HTML, ScreenshotMachine recommends a secret phrase and corresponding hash; its docs state that a configured phrase without a correct hash causes the request to be ignored.
- Cost and quotas: Current ScreenshotMachine prices, quotas, and plan restrictions were not established in the research for this article. Review the vendor’s current account and billing details before estimating recurring cost.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| The request is rejected or ignored | The customer key may be missing or incorrect; a configured secret phrase may have no matching hash or an incorrect hash. | Confirm the key and follow the vendor’s current instructions for phrase/hash authentication. |
| The script exits without a useful message | curl output may be suppressed, or an HTTP error response may have been saved as if it were an image. |
Use --fail --show-error, inspect the exit status, and validate the output with file. |
| The image is blank or misses late content | The page may not have finished loading before capture. | Increase the delay within the documented 0–10,000 ms range and inspect the page again. |
| The full-page image is incomplete | Long pages can contain images or animations that need more time. | Try a longer delay; the documentation gives 2000 ms or more as an example for full-length pages. |
| A click or hide selector has no effect | The selector may not match the element, or reserved characters may not have been encoded. | Check the CSS selector against the page and URL-encode it, especially characters such as #. |
| The requested zoom is not reflected | The docs state zoom is ignored for screenshots smaller than typical device dimensions. | Review the requested dimensions and zoom range before changing the capture settings. |
| The saved file is not an image | The response may be an HTTP error body or another error result rather than the requested image. | Check the HTTP status before writing or consuming the body, then inspect the file type. |
| The URL behaves differently than expected | Special characters may have been interpreted as query syntax rather than as part of a parameter. | Pass parameters through --data-urlencode, URLSearchParams, or a client parameter dictionary. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture options include full-page screenshots, CSS element capture, device and viewport settings, custom CSS and JavaScript, waiting controls, caching, and more. See the ScreenshotNeo API documentation for request parameters.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and response headers report the page verdict and billing result. Its MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free 1,000 screenshots per month, with no card required.
FAQ
Does ScreenshotMachine have an official CLI binary?
The official material reviewed for this guide documents a Bash and curl example for its hosted API. It does not document a separately installed CLI binary.
Can I use the command in a CI job?
The workflow is a shell command that makes an HTTP request and saves a file, so it can be called from a shell-based job. Store credentials in the CI system’s secret storage and check the request status and output file.
Does the documentation prove that ScreenshotMachine produces high-quality screenshots?
No. It documents formats and configuration controls, but the research for this review did not establish measured image quality or independent results across websites.
What should I use for a fresh capture?
The documentation says a cache age of zero means do not use cache. Its current service behavior should be checked if cache semantics are critical to your application.
