CLI

The official Screenshot Scout CLI turns a terminal command into a screenshot. It has two commands: capture, which sends one capture request and saves or prints the result, and capture-url, which builds a capture URL on your machine without calling the API.

Use it when you want captures from a terminal, a shell script, or a CI job without writing code. To capture from inside an application, use an SDK instead.

The CLI is open source. It's developed in the screenshotscout-cli repository and published on npm as @screenshotscout/cli.

What you need

• A Screenshot Scout account and an access key from the API Keys page.
• The matching secret key, but only when your API key has Require signed requests enabled. See signed requests.
• Node.js 22 or newer.

Each capture command sends one capture request, which is subject to your plan's rate limits. Only successful, uncached captures count toward your monthly quota. capture-url sends nothing at all.

Install

Install the package globally from npm:

npm install -g @screenshotscout/cli

The executable is screenshotscout:

screenshotscout --version

To run a pinned version without installing it globally, use npx:

npx @screenshotscout/cli@0.1.0 capture https://example.com

If your environment needs the explicit form:

npx --package=@screenshotscout/cli@0.1.0 screenshotscout capture https://example.com

Pin the version in scripts and CI jobs so a later release can't change what your job runs.

Set your credentials

The CLI reads two environment variables when it starts:

• SCREENSHOTSCOUT_ACCESS_KEY (required): your access key. It authenticates the capture request, and capture-url writes it into the generated URL.
• SCREENSHOTSCOUT_SECRET_KEY (optional): the matching secret key. Set it only when the API key has Require signed requests enabled. It stays on your machine, where the CLI uses it to sign capture requests and generated capture URLs automatically. The secret itself is never sent to Screenshot Scout.

export SCREENSHOTSCOUT_ACCESS_KEY="YOUR_ACCESS_KEY"
export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY"

$env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY"

There's no login prompt, credentials file, or profile to manage. If the access key isn't in the environment when you run a command, the command fails.

Capture a screenshot

capture takes the page URL as its first argument:

screenshotscout capture https://example.com

That sends one capture request. An image or PDF response is saved in the current directory as screenshot.<extension>, where the extension comes from the content type you received. Add screenshot options as flags:

screenshotscout capture https://example.com \
  --format webp \
  --full-page \
  --block-cookie-banners \
  --output ./homepage.webp

--method get and --method post choose how the request is sent. Leave the flag out unless you have a reason to pick one, such as a network that only allows GET.

Where the result goes

--output (or -o) chooses the destination. The exact value - means standard output.

A few things worth noting:

• A successful file write prints nothing. You either chose the path or you know the automatic one.
• An existing file at the destination is replaced, and the destination directory has to exist already.
• Bytes are written exactly as they arrived. Images aren't decoded or re-encoded, and JSON isn't reformatted or wrapped. Nothing is appended, including a trailing newline.

Redirecting standard output works the same for an image and for JSON:

screenshotscout capture https://example.com --output - > example.png

JSON results

Add --response-type json to get the API's JSON body instead of the image. Without --output, it's printed exactly as the API returned it, which makes it easy to pipe into another tool:

screenshotscout capture https://example.com --response-type json | jq -r .screenshot_url

Build a capture URL

capture-url builds a capture URL locally and prints it. It sends nothing, so it uses no quota:

screenshotscout capture-url https://example.com --full-page

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https%3A%2F%2Fexample.com&full_page=true

Every generated URL contains your access key and the screenshot options you passed. When SCREENSHOTSCOUT_SECRET_KEY is set, the URL also carries a signature parameter. The secret key itself is never part of the URL. The URL is printed as generated, followed by one newline.

Treat generated URLs as sensitive: anyone who has one can spend your quota. Before exposing a URL to browsers or users, configure a secret key and enable Require signed requests on the API Keys page.

capture-url accepts the same screenshot options as capture, but none of its output controls, and it always produces a GET URL.

Screenshot options

Every screenshot option in the option reference is available as a flag. The names map mechanically, so you only have to learn one rule:

Three entries in the reference have no flag: the CLI takes url as the command argument, fills access_key from SCREENSHOTSCOUT_ACCESS_KEY, and adds the signature itself when a secret key is set.

For the exhaustive list of flags and their value shapes in the version you installed, run:

screenshotscout capture --help
screenshotscout capture-url --help

The CLI checks that a number is a number and a boolean is a boolean, then sends what you gave it. Screenshot Scout decides which values are allowed, how options interact, and what each one means, all documented in the option reference. The CLI adds no defaults of its own, so an option you don't pass isn't sent at all.

Values

• Booleans take the bare flag or an inline value: --full-page and --full-page=true mean true, and --full-page=false means false.
• Omitting a boolean isn't the same as false. Omitted means the option isn't sent and Screenshot Scout decides. --full-page=false sends false.
• Repeatable options are marked (repeatable) in the help output. Repeat the flag once per value, and order and duplicates are preserved. Every other flag may appear at most once.

screenshotscout capture https://example.com \
  --headers "X-Example: first" \
  --headers "X-Example: second" \
  --hide-selectors ".cookie-bar" \
  --hide-selectors "#newsletter"

Options files

Long command lines get unreadable. --options reads the same screenshot options from a JSON object instead:

{
  "full_page": true,
  "block_cookie_banners": true,
  "format": "jpeg",
  "image_quality": 80,
  "hide_selectors": [".cookie-bar", "#newsletter"]
}

screenshotscout capture https://example.com --options ./capture.json

Keys are the API's snake_case names, so the screenshot-options part of a POST body works as is. --options - reads the object from standard input instead of a file:

echo '{"full_page": true}' | screenshotscout capture https://example.com --options -

Flags win over the file, so you can keep a shared file and override one value per run. A repeated flag replaces the file's array rather than adding to it.

Exit codes and failures

Failure messages go to standard error, so they never mix into a piped image or JSON. The message is passed through as it was produced, not rewritten. When the API rejects your options, its errors array follows on the next line, complete and unfiltered, as compact JSON:

One or more options are invalid.
[{"option":"url","message":"The \"url\" option is required."}]

The full list of error codes is in Errors. Programming stack traces are never printed.

Run it in CI

Any CI system that can run Node.js 22 can run the CLI. Keep your keys in your CI system's secret storage, expose them under the same variable names, and pin the version:

export SCREENSHOTSCOUT_ACCESS_KEY="$CI_SCREENSHOTSCOUT_ACCESS_KEY"

mkdir -p artifacts
npx @screenshotscout/cli@0.1.0 capture https://example.com \
  --full-page \
  --block-cookie-banners \
  --output artifacts/homepage.png

Nothing is interactive, so a command either runs from its arguments and environment or fails. The exit code is enough to fail the job: 2 for a mistake in the command, 1 for a capture that didn't succeed. A successful capture writes only the file, so the job log stays quiet.

To hand the result to another step without writing it to disk, use --output -.

Troubleshooting

Resources

• GitHub repository: source code, the complete written reference, issues, and releases.
• @screenshotscout/cli on npm: the published package.
• Screenshot option reference: service behavior and allowed values for every option.
• Errors: all API error codes.
• Signed requests: when and how requests are signed.
• Questions or problems: contact us.