Screenshot Machine CLI Command Line Examples for Linux

To take a Screenshot Machine screenshot from the Linux command line, use Bash and curl to call its hosted screenshot API. The available documentation supports this API workflow; it does not establish a separately installed native Screenshot Machine CLI executable. You need a Screenshot Machine customer key and the URL to capture. This guide follows the vendor’s screenshot API documentation.

Capture a webpage from Linux with Bash and curl

Save this as screenshot.sh. Replace the API key and target URL. The example requests a 1366 × 768 PNG, disables the cache, waits two seconds, and uses 100% zoom.

#!/usr/bin/env bash
set -euo pipefail

CUSTOMER_KEY="PUT_YOUR_CUSTOMER_KEY_HERE"
SECRET_PHRASE="" # Leave empty if you have not configured one.
URL="https://www.google.com"
DIMENSION="1366x768"
DEVICE="desktop"
FORMAT="png"
CACHE_LIMIT="0"
DELAY="2000"
ZOOM="100"
OUTPUT="output.png"

ARGS=(
  --data-urlencode "key=$CUSTOMER_KEY"
  --data-urlencode "dimension=$DIMENSION"
  --data-urlencode "device=$DEVICE"
  --data-urlencode "format=$FORMAT"
  --data-urlencode "cacheLimit=$CACHE_LIMIT"
  --data-urlencode "delay=$DELAY"
  --data-urlencode "zoom=$ZOOM"
  --data-urlencode "url=$URL"
)

if [[ -n "$SECRET_PHRASE" ]]; then
  HASH=$(printf '%s' "$URL$SECRET_PHRASE" | md5sum | cut -d ' ' -f 1)
  ARGS+=(--data-urlencode "hash=$HASH")
fi

curl -G -sS "https://api.screenshotmachine.com" "${ARGS[@]}" -o "$OUTPUT"
printf 'Saved response to %s\\n' "$OUTPUT"

Run it with bash screenshot.sh. The script uses standard Linux shell tools, including curl and (if a secret phrase is configured) md5sum. The strict shell flags are script safeguards, not a vendor requirement. Keep the key and secret phrase out of public repositories and client-side code.

Minimal one-line request

For a quick capture, use curl -G and URL-encode each parameter. Replace the placeholder key before running:

curl -G -sS "https://api.screenshotmachine.com" \
  --data-urlencode "key=PUT_YOUR_CUSTOMER_KEY_HERE" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "dimension=1366x768" \
  --data-urlencode "format=png" \
  -o screenshot.png

Why use `--data-urlencode`?

Web addresses often contain characters that have special meaning in a query string, such as &, ?, or #. Passing the URL through --data-urlencode lets curl encode it as a parameter. Avoid building the query URL by concatenating raw values, which can accidentally split a target URL into extra API parameters.

Choose the capture options

The parameter names, documented defaults, and ranges below come from Screenshot Machine’s API documentation and may change. Set the values that fit your capture rather than relying on defaults.

Parameter	Purpose and documented behavior
`key`	Your customer API key. Required.
`url`	The webpage to capture. Required. URL-encode it in the request.
`dimension`	Viewport width and height in `WIDTHxHEIGHT` form. Documented default: `120x90`. Width range: 100–1920; height range: 100–9999. Use `full` for full-page height.
`format`	Documented choices: `jpg`, `png`, or `gif`. Default: `jpg`.
`cacheLimit`	Maximum cache age in days, documented from 0 to 14; default: 14. Set to `0` to request a fresh capture. The docs also describe fractional-day cache durations.
`delay`	Wait time before capture in milliseconds. The documentation lists choices from 0 to 10000 in increments; default: 200 ms. A longer delay may let late content or animations finish.
`zoom`	Scale from 10% to 400%; default: 100%. The vendor says 200% or higher can create a retina-style larger image. Zoom is ignored for screenshots below typical device dimensions.
`device`	Device setting, shown as `desktop` in the vendor’s example. Consult the current API guide for supported values.
`hash`	Optional safeguard when a secret phrase is configured. See the authentication section below.

Viewport or full page

A fixed dimension captures a viewport-sized image. Use dimension=full when you need full-page height. For a normal viewport, choose dimensions that match the layout you want to inspect; the documented width and height limits still apply.

JPG, PNG, or GIF

Choose a format your next step accepts. The API documentation lists JPG, PNG, and GIF, with JPG as the default. The Bash example names the output file output.png because it requests PNG. Keep the file extension consistent with the requested format so downstream tools and people can identify it correctly.

Cached or fresh capture

The documented cache age is up to 14 days by default. A cache can avoid repeatedly fetching an unchanged page; set cacheLimit=0 when you need a fresh screenshot. If a page changes frequently, choose a cache age suitable for your use case.

Immediate capture or wait

The documented default delay is 200 milliseconds. Increase delay when the page needs extra time for late content or animation, within the vendor’s documented choices up to 10000 milliseconds. A delay can help with time-dependent rendering, but it also adds waiting time to each request.

Protect the API key and configure the hash

The API requires a customer key. Store it in a private environment or configuration file with restricted access instead of committing it to a repository. Do not place a secret phrase in publicly accessible HTML or JavaScript.

If a secret phrase is configured, the vendor documents hash as the MD5 digest of the URL value concatenated with that phrase. The script computes it with md5sum and adds it to the request. The vendor says calls with a missing or incorrect hash are ignored once the phrase is set. This hash check does not make a publicly exposed API key or secret phrase safe; keep both private.

Capture a website as a PDF

Screenshot Machine documents PDF generation as a separate API from image screenshots. Its PDF endpoint is https://pdfapi.screenshotmachine.com. This Bash example illustrates the distinct request shape; consult the current PDF guide for the accepted option values and defaults.

#!/usr/bin/env bash
set -euo pipefail

CUSTOMER_KEY="PUT_YOUR_CUSTOMER_KEY_HERE"
URL="https://example.com"

curl -G -sS "https://pdfapi.screenshotmachine.com" \
  --data-urlencode "key=$CUSTOMER_KEY" \
  --data-urlencode "url=$URL" \
  --data-urlencode "paper=A4" \
  --data-urlencode "orientation=portrait" \
  --data-urlencode "media=print" \
  --data-urlencode "background=true" \
  --data-urlencode "delay=2000" \
  --data-urlencode "scale=1" \
  -o output.pdf

The vendor’s PDF Bash example includes paper, orientation, media, background, delay, and scale options. See the Screenshot Machine PDF API documentation before relying on specific option values. Do not send PDF options to the image endpoint or assume an image response is a PDF.

Troubleshoot failed or unexpected output

A successful curl process only confirms that curl completed the transfer. Screenshot Machine documents that invalid or incomplete requests can return an error image, so check the response header and inspect the file when a result looks wrong.

Symptom or response code	Likely cause	What to check
File is an error image or not the expected screenshot	Invalid or incomplete request; the API can return an image containing an error message.	Inspect `X-Screenshotmachine-Response`, verify parameters, then open the returned file.
`missing_key` or `invalid_key`	The key is absent or not accepted.	Check the key value, account, and that the request includes `key`.
`missing_url` or `invalid_url`	The target URL is absent or malformed.	Include a complete URL and pass it using `--data-urlencode`.
`invalid_hash`	The configured secret phrase and hash do not match, or the hash is missing.	Calculate MD5 from the exact URL value followed by the secret phrase; add the resulting `hash` parameter.
`no_credits`	The account has no available credits.	Check the account’s remaining credits.
`invalid_selector` or `invalid_crop`	A selector or crop parameter is invalid.	Review the selector or crop syntax and remove it temporarily to isolate the problem.
`system_error`	The service reports a system error.	Retry later and inspect the response header and account status if it persists.
Unexpectedly old image	A cached capture may have been returned.	Set `cacheLimit=0` to request a fresh screenshot.
Late content is missing	The page may need more time before capture.	Increase `delay` within the documented range and make sure the URL itself loads correctly.

To save headers for diagnosis, rerun the request with -D response-headers.txt. For example:

curl -G -sS -D response-headers.txt \
  "https://api.screenshotmachine.com" \
  --data-urlencode "key=PUT_YOUR_CUSTOMER_KEY_HERE" \
  --data-urlencode "url=https://example.com" \
  -o response.bin

Check response-headers.txt for X-Screenshotmachine-Response. Use file response.bin or open the file to determine whether the body is the expected image or an error response.

Performance, reliability, and cost considerations

Latency: The configured delay adds directly to the time before capture. Use the shortest delay that consistently includes the content you need; long delays make batches of requests slower.
Freshness: Cache age trades freshness for reuse. Set it to zero for a fresh request; use an appropriate positive age when an older capture is acceptable.
Image size: Larger dimensions and higher zoom create larger output files. Choose dimensions and format for the downstream task rather than requesting maximum size by default.
Reliability: Check the documented response header and validate the output, since error responses may be images. For automated jobs, treat an unexpected response code or file type as a failed capture rather than assuming the curl exit status is enough.
Cost: The cited Screenshot Machine API documentation identifies account credits and a no_credits error. Review your account’s current pricing and credit terms before running a large batch; the dossier does not establish current prices.

Or skip the browser setup

If you want a single screenshot request without setting up browser automation, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns PNG, JPEG, WebP, or PDF. Its API documentation covers the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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}`);

Cookie banners are accepted and removed before capture; more than 60 known consent platforms, newsletter popups, and chat widgets can be removed, with each step configurable.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

FAQ

Is there a native Screenshot Machine CLI for Linux?

The cited vendor material documents Bash and curl examples that call its hosted API. It does not establish a separately installed native CLI.

Can I use a webpage URL containing query parameters?

Yes. Pass the complete target URL through --data-urlencode so its reserved characters are encoded as part of the parameter.

Why does my output file contain text?

The service can return an error image with a message for an invalid or incomplete request. Check the response header and the key, URL, hash, credits, and any optional selector or crop values.

Can I reuse this exact request to make a PDF?

No. The vendor documents a separate PDF endpoint at pdfapi.screenshotmachine.com with PDF-specific options.