Metadata-Version: 2.4
Name: localscreenshot
Version: 0.1.0
Summary: Take a screenshot of any public web page from the command line or from Python, from 227 countries. The client of the localscreenshot API.
Author-email: SOFTLOGIC <hello@localscreenshot.com>
License-Expression: MIT
Project-URL: Homepage, https://localscreenshot.com
Project-URL: Repository, https://github.com/Sambel/localscreenshot-cli
Project-URL: Documentation, https://docs.localscreenshot.com
Project-URL: Issues, https://github.com/Sambel/localscreenshot-cli/issues
Keywords: screenshot,screenshot-api,website-screenshot,web-capture,url-to-image,cli,ai-agents,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# localscreenshot

Take a screenshot of any public web page from your terminal or from Python. This is the client of the [localscreenshot](https://localscreenshot.com) API.

```bash
pipx run localscreenshot https://example.com
```

It saves the image in the current folder and tells you what it cost.

## Install

```bash
pip install localscreenshot
```

Python 3.9 or later. No dependencies.

## Your API key

Create a free account at [localscreenshot.com/signup](https://localscreenshot.com/signup). A new account gets free credits, no card needed.

Then either set the key in your environment:

```bash
export LOCALSCREENSHOT_API_KEY=your_key
```

or save it once on this machine:

```bash
localscreenshot login
```

`login` asks for the key without showing it, checks it, and writes it to a file only you can read. `localscreenshot logout` removes it. The key is never accepted as a command line argument, so it does not end up in your shell history.

## Examples

```bash
# 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

# Click a menu first, then capture
localscreenshot https://www.notion.com --click-text "Product"

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

## Options

| Option | What it does |
| --- | --- |
| `-o, --output <file>` | Where to write the image. Default: `<host>-<time>.<ext>` |
| `--country <code>` | Load the page from this country, two letters |
| `--full-page` | Capture the whole page |
| `--device <name>` | Screen to render on, for example `iphone_15`, `ipad`, `desktop_hd` |
| `--format <format>` | `png` (default), `jpeg`, `webp` or `pdf` |
| `--click-text <text>` | Click the one element showing this text, then capture |
| `--no-cookie-banners` | Hide cookie banners |
| `--no-ads` | Hide ads |
| `--dark` | Render in dark mode |
| `--json` | Print the API answer as JSON |
| `--force` | Overwrite the output file if it exists |

Other commands:

```bash
localscreenshot countries   # the countries a page can be loaded from
localscreenshot credits     # the credits left on your account
```

## From Python

```python
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)

print(shot.width, shot.height, shot.credits_charged, shot.credits_remaining)
```

`screenshot()` takes the same options as the command: `country`, `full_page`, `device`, `format`, `click_text`, `block_cookie_banners`, `block_ads`, `dark`. It reads the key from `LOCALSCREENSHOT_API_KEY` or from the file written by `localscreenshot login`, or takes `api_key=`. It raises `localscreenshot.ApiError`, with the error `code` of the API, when a screenshot fails.

A screenshot uses credits from your account. A failed screenshot is not charged. The tool exits with a non-zero code when something fails, and prints the error code of the API.

## For AI tools

localscreenshot also runs an MCP server, so that Claude, Cursor, VS Code and other tools can take screenshots on their own. Setup: [localscreenshot.com/mcp](https://localscreenshot.com/mcp).

## Links

- [Documentation](https://docs.localscreenshot.com)
- [API](https://localscreenshot.com/api)
- [Pricing](https://localscreenshot.com/pricing)

MIT license.
