Get started

localscreenshot is the command line client of the API. One command takes a screenshot of a public web page and saves the image in the current folder. It uses the same API key and the same credits as everything else.

1Install

With npx. 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.

npx localscreenshot https://example.com

With npm. Installs the command globally.

npm install -g localscreenshot

With pip. Python 3.9 or later, no dependencies.

pip install localscreenshot

With pipx. Runs it once without installing anything for good.

pipx run localscreenshot https://example.com

With uv. The same, with uv.

uvx localscreenshot https://example.com

The command has no dependencies. It sends no usage data and does not check for updates.

The rest of this page writes localscreenshot. If you did not install it, write npx localscreenshot, pipx run localscreenshot or uvx localscreenshot instead.

2Set your key

Create a key in the dashboard, under Connect. Then either put it in your environment:

export LOCALSCREENSHOT_API_KEY="your key"

or save it once on this machine:

localscreenshot login

login asks for the key without showing it, checks it against the API, and writes it to a file only you can read: ~/.config/localscreenshot/config.json on macOS and Linux (under $XDG_CONFIG_HOME if you set it), %APPDATA%\localscreenshot\config.json on Windows. localscreenshot logout removes it. In a script or in CI, use the environment variable.

The key is never accepted as an argument, so it does not end up in your shell history. More on keys: Your API key.

3Take a screenshot

localscreenshot https://example.com

It saves the image as example.com-<date>-<time>.png and says what it cost.

Add options as flags:

# The whole page, as a JPEG
localscreenshot https://example.com --full-page --format jpeg

# As seen from Brazil
localscreenshot https://www.netflix.com --country BR

# On a phone, in dark mode, without the cookie banner
localscreenshot https://example.com --device iphone_15 --dark --no-cookie-banners

# Choose the file name
localscreenshot https://example.com -o home.png

To click one element before the picture, give the text a visitor reads on it: localscreenshot https://www.notion.com --click-text "Product". A screenshot with a click costs 1 credit more.

Options

Device names are on Devices and sizes, country codes on Countries and attestation. The API has more options than the command: for those, call it directly, as shown on Take a screenshot.

The command does not overwrite a file. If the output file already exists, it stops and tells you to use --force or another name with -o. It checks before asking for the screenshot, so nothing is taken and no credit is used. The same goes for a path that is a folder, or whose folder does not exist.

Other commands

countries and credits take --json too.

From Python

The Python package is also a library. screenshot() takes the same options as the command and returns the image.

Its arguments are country, full_page, device, format, click_text, block_cookie_banners, block_ads and dark. It reads the key from LOCALSCREENSHOT_API_KEY or from the file written by login, or takes api_key=. When the API refuses or the screenshot fails, it raises localscreenshot.ApiError, which carries the error code of the API.

When it fails

The command prints one line on the error output and exits with a code a script can test.

An output path that cannot be written (the file exists, it is a folder, its folder is missing) also ends with 2, before any request. One rare case comes after the request: without -o, the name is built from the site and the time, and if a file of that name appears while the screenshot is being taken, the image is not written. You still find it in your dashboard.

At the login prompt, the Node package exits with 2 on Ctrl+C, not 130.

The command waits up to three minutes for a screenshot. After that it stops with still_running and gives you the id: the screenshot still finishes, and you find it in your dashboard.

What it costs

• A screenshot uses 1 credit. From a chosen country, it uses 2.
• A failed screenshot is not charged.
• localscreenshot credits shows what is left. The rules are on Credits and limits.

Your key stays with you

• The key goes to the API host only, over HTTPS. Redirects are not followed.
• The image is downloaded through its signed link, without the key.
• No message ever prints the key.

Packages and source

The Python package is on PyPI: https://pypi.org/project/localscreenshot/.

The Node package is on npm: https://www.npmjs.com/package/localscreenshot. Both packages offer the same command, with the same options.

The source code is public, under the MIT license: https://github.com/Sambel/localscreenshot-cli.