Screenshot CLI

1Run it

With Node on your machine there is nothing to install: npx fetches the command and runs it. Or install it globally with npm or pip. It has no dependencies, sends no usage data and does not check for updates.

With npx

npx localscreenshot https://example.com

Node 18.17 or later, nothing to install first. In a terminal, npx asks once before it downloads the package: npx -y skips the question.

With npm

npm install -g localscreenshot

Installs the command globally.

With pip

pip install localscreenshot

Python 3.9 or later, no dependencies.

The examples below write localscreenshot. If you did not install it, write npx localscreenshot instead. Other ways to run it are in the CLI documentation.

2Your key

Create a free account and copy your key from the dashboard. Put it in your environment:

export LOCALSCREENSHOT_API_KEY="your key"

Or run localscreenshot login once to save it on your machine. The key is never accepted as an argument, so it stays out of your shell history, and it goes to the API host only, over HTTPS.

3Examples

Options are flags. Each command saves one image and prints its size and what it cost.

A page as it loads

localscreenshot https://example.com

Saves example.com-<date>-<time>.png in the current folder and prints what it cost.

From another country

localscreenshot https://www.netflix.com --country BR -o netflix-br.png

The page is loaded from Brazil. The answer reports the country that was observed.

A whole page on a phone

localscreenshot https://www.wikipedia.org --device iphone_15 --full-page --format jpeg

An iPhone screen, the full height of the page, as a JPEG.

After a click

localscreenshot https://www.notion.com --click-text "Product"

Clicks the one element that shows this text, then takes the picture: an open menu, a tab, a dialog.

Without the clutter

localscreenshot https://example.com --no-cookie-banners --no-ads --dark

Cookie banners and ads hidden, in dark mode.

Saved /home/you/example.com-20261012-133800.png
1440 x 900, 88,627 bytes
Credits: 1 used, 47 left

Three more commands: localscreenshot countries lists the 227 countries, localscreenshot credits shows what is left on your account, localscreenshot logout removes the saved key. The CLI documentation has the table of every option. The API has more options than the command: for those, call the API.

4In a script or in CI

Use it in scripts and CI. It exits with 0 when the image is saved, 1 when the API refused or the screenshot failed, 2 when it was not used correctly, and 130 if you stop a screenshot with Ctrl+C. Errors go to the error output, on one line.

• --json prints the answer of the API, with the path of the saved file, for the next step of your script.
• -o chooses the file name. An existing file is not overwritten without --force, and the command checks before it asks for the screenshot: no credit is used.
• A failed screenshot is not charged.

- name: Screenshot the home page
  run: npx -y localscreenshot https://example.com -o home.png
  env:
    LOCALSCREENSHOT_API_KEY: ${{ secrets.LOCALSCREENSHOT_API_KEY }}

Keep the key in the secrets of your repository. The same line works in any CI that can run a shell command. Every exit code is in the CLI documentation.

5From Python

The Python package is also a library, with one function that takes the same options and returns the image.

from localscreenshot import screenshot

shot = screenshot("https://example.com", country="BR", full_page=True)
with open(f"example.{shot.extension}", "wb") as file:
    file.write(shot.image)

Install it with pip install localscreenshot. Arguments and errors are in the CLI documentation.

6Credits and limits

• The command is free and open source. Screenshots use the credits of your account.
• 50 free credits every month, no card. A free account can send 10 requests a minute and run 2 screenshots at a time.
• A screenshot costs 1 credit, or 2 from a chosen country. A failed screenshot is not charged.
• Plans start at €19 a month for 2,000 credits. Credit packs start at €12, paid once, for 1,000 credits.

Prices are before tax. The full grid is on the Pricing page.

7Packages and source

Like the API, it does not sign in to websites, solve CAPTCHAs or get past paywalls. You get a clear error instead.