How to install ScreenshotMachine CLI on Ubuntu

Direct answer: The official ScreenshotMachine materials reviewed do not establish a separately installable ScreenshotMachine CLI package for Ubuntu. They document a remote screenshot API and provide a Bash script that calls it with curl. On Ubuntu, use Bash and curl to send a GET request to the API, then save the returned image to a file.

This guide sets up that documented command-line route. It does not install a local browser or screenshot engine. ScreenshotMachine’s screenshot API uses https://api.screenshotmachine.com/, requires your customer API key, and requires the page URL. See the official API documentation for the current parameter reference.

1. Check for Bash and curl

Open a terminal and check that both commands are available:

bash --version
curl --version

Bash is the shell used to run the command or script; curl makes the HTTP request. The official materials reviewed show Bash and curl but do not specify Ubuntu release requirements or package-install commands. If either command is missing, use the package instructions for your specific Ubuntu release and verify the package name in Ubuntu’s official documentation.

2. Get an API key

Get your own ScreenshotMachine customer key through its account signup process. The key is a credential: do not commit it to a public repository, put it in a public web page, or paste it into shared logs. The API documentation says a unique customer API key is required.

3. Make a screenshot request from the terminal

Replace YOUR_API_KEY and the example URL with your key and target page. This command saves the response body as page.jpg:

curl --fail --show-error --silent --get 'https://api.screenshotmachine.com/' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com/' \
  --data-urlencode 'dimension=120x90' \
  --data-urlencode 'device=desktop' \
  --data-urlencode 'format=jpg' \
  --output page.jpg

Use the exact parameter names and account details shown in the ScreenshotMachine API documentation. URL encoding matters: --data-urlencode safely encodes query values such as URLs with ampersands or other reserved characters. The API documentation’s default dimension is 120x90, which is very small for many uses, so set a suitable dimension explicitly.

The service returns image content for successful captures. For invalid or incomplete requests, its documentation says it can return an error image and an X-Screenshotmachine-Response header with an error code. Therefore, a file being written does not by itself prove the capture succeeded; inspect the response headers when diagnosing failures.

4. Choose capture options

Option	Documented choices or behavior	When to change it
`dimension`	Width from 100 to 1920 and height from 100 to 9999; `full` is accepted for full-length capture. Default: `120x90`.	Set the viewport size you need. Use `full` for a full-page image where supported by your workflow.
`device`	`desktop`, `phone`, or `tablet`. Default: `desktop`.	Choose the device profile appropriate to the layout you need to capture.
`format`	`jpg`, `png`, or `gif`. Default: `jpg`.	Choose the output type your downstream tool accepts. Match the filename extension to the requested format.
Cache age	The API documents a cache-age option.	Use the documented parameter when you need to control how fresh a cached capture may be; consult the current parameter table for its exact name and accepted values.
Capture delay	The API documents a delay option.	For pages that load images or animations late, ScreenshotMachine advises a greater delay, such as 2000 milliseconds or more.
Zoom	The API documents a zoom option.	Adjust only when the output scale needs to differ from the default; verify accepted values in the current API reference.

Do not assume an option’s exact parameter spelling or accepted range from another screenshot service. Use the ScreenshotMachine parameter table for the current names and constraints.

5. Save the request as a reusable Bash script

This script takes the target URL as its first argument and reads the API key from an environment variable, keeping the credential out of the script itself:

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

if [[ $# -lt 1 ]]; then
  printf 'Usage: %s PAGE_URL [OUTPUT_FILE]\n' "$0" >&2
  exit 2
fi
if [[ -z "${SCREENSHOTMACHINE_KEY:-}" ]]; then
  printf 'Set SCREENSHOTMACHINE_KEY before running this script.\n' >&2
  exit 2
fi

page_url=$1
output_file=${2:-screenshot.jpg}

curl --fail --show-error --silent --get 'https://api.screenshotmachine.com/' \
  --data-urlencode "key=${SCREENSHOTMACHINE_KEY}" \
  --data-urlencode "url=${page_url}" \
  --data-urlencode 'dimension=1280x800' \
  --data-urlencode 'device=desktop' \
  --data-urlencode 'format=jpg' \
  --output "$output_file"
printf 'Saved response to %s\n' "$output_file"

Save it as screenshot.sh, then run:

export SCREENSHOTMACHINE_KEY='YOUR_API_KEY'
bash screenshot.sh 'https://example.com/' example.jpg

The example uses a 1280 by 800 desktop capture. Adjust the dimension and other values to your needs and to the documented API limits. Treat the output as untrusted until you check that the request succeeded; an API error response may itself be an image.

6. Requests from public web pages

Do not expose the customer key in public HTML or browser-side JavaScript. ScreenshotMachine documents a hash safeguard for requests made from public HTML pages: calculate the hash from the URL plus your secret phrase using MD5. When a secret phrase is set, requests with a missing or incorrect hash are ignored. Keep the phrase private and follow the service’s documentation for the exact hash construction and parameter names.

7. Screenshot API versus PDF API

The screenshot API returns an image and uses https://api.screenshotmachine.com/. The separate PDF API uses https://pdfapi.screenshotmachine.com; its documented Bash/curl example redirects the returned PDF to a local file. Do not send PDF options to the screenshot endpoint or assume the two endpoints share all parameters. Use the official PDF API documentation if your desired output is a PDF.

8. Troubleshooting

Symptom	Likely cause	What to do
`bash: curl: command not found`	curl is not available in this Ubuntu environment.	Install curl using the instructions for your Ubuntu release, then confirm with `curl --version`.
Authentication error or error image	The key is missing, mistyped, or not the customer key for this service.	Check the account key and the query parameter name against the API docs. Do not print the key into a shared log.
`invalid_url` in `X-Screenshotmachine-Response`	The URL is malformed or was not encoded correctly.	Pass a complete URL including scheme, such as `https://example.com/`, and use `--data-urlencode`.
Image file exists but shows an error	The API can return an error image for invalid or incomplete requests.	Capture response headers and inspect `X-Screenshotmachine-Response`; correct the reported request problem.
Page capture misses late images or animation	The page content was not ready at capture time.	Increase the documented delay, for example to 2000 milliseconds or more, and retry.
HTTP or DNS failure	Local network, proxy, DNS, or remote service connectivity issue.	Check that the Ubuntu machine can reach the endpoint, then retry with curl’s error output enabled. A command-line prerequisite failure is different from an API response error.
Public-page request is ignored	A secret phrase is configured and the hash is missing or incorrect.	Generate the documented MD5 hash from the URL and secret phrase; keep the phrase private.

9. Performance, reliability, and cost

Each capture is a remote HTTP request, so completion time depends on network conditions and how long the target page takes to render. For long or dynamic pages, a larger documented delay can improve completeness while increasing wait time. Use cache-age settings when their freshness tradeoff fits your use case. For automation, distinguish transport failures from API-level errors by preserving HTTP status and response headers during diagnosis.

Check ScreenshotMachine’s current account and pricing information before estimating usage costs; the research materials reviewed here do not establish a price or quota. Avoid embedding API credentials in source control, and rotate exposed credentials through the service account process.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF, and the API accepts familiar parameter names used by other screenshot APIs. See the ScreenshotNeo API documentation.

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

Cookie banners are accepted or removed before capture, along with known newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Is ScreenshotMachine CLI an Ubuntu package?

The official sources reviewed for this guide document a remote API and Bash/curl example, not a dedicated installable Ubuntu CLI package. This does not rule out unrelated third-party projects with similar names.

Does the command capture a page locally?

No. curl sends the request to ScreenshotMachine’s hosted API, which performs the capture and returns the result.

Can I use the same endpoint to create a PDF?

No. The PDF API has a separate endpoint and its own documented options.

Which format should I use?

The documented image formats are JPG, PNG, and GIF. Choose based on the requirements of the system that will consume the result, and use a matching output filename.