Metadata-Version: 2.4
Name: shotbot
Version: 0.1.0
Summary: CLI for the Shotbot screenshot API
Author: Valentin Beck
License: MIT
Project-URL: Homepage, https://www.shotbot.net/screenshot-cli-tools/
Keywords: screenshot,capture,api,cli,shotbot
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# shotbot-python-cli

A single-file Python CLI for the [Shotbot](https://www.shotbot.net) screenshot API.
Same flag names, exit codes, and config-file layout as the
[PHP](https://api.shotbot.net/cli/php/shotbot) and
[Node.js](https://api.shotbot.net/cli/node/shotbot) clients | scripts written
for one work as-is with the others.

Documentation: <https://www.shotbot.net/screenshot-cli-tools/> (English) /
<https://www.shotbot.fr/outil-cli-capture-ecran/> (French).

## Requirements

- Python 3.8+
- Standard library only | no `pip install` needed.

## Install

```sh
curl -fsSL https://api.shotbot.net/cli/python/shotbot -o shotbot \
  && chmod +x shotbot \
  && ./shotbot help
```

To put it on your `$PATH`:

```sh
sudo mv shotbot /usr/local/bin/
```

## First run

On first use you'll be prompted for your API key. It is saved to
`~/.shotbot-python-cli/config.json` (chmod 600). Get a key at
<https://www.shotbot.net/screenshot-api-key/>.

```
$ shotbot capture --url=https://example.com

No Shotbot API key configured.
Get one at https://www.shotbot.net/screenshot-api-key/

API key: abc123def456
✓ Saved to /home/you/.shotbot-python-cli/config.json (chmod 600)
```

## Usage

```sh
shotbot capture --url=https://example.com
shotbot capture --url=https://example.com --output                    # cwd, auto-named
shotbot capture --url=https://example.com --output=screenshots/       # into dir, auto-named
shotbot capture --url=https://example.com --output=hero.jpg           # exact path
shotbot capture --url=https://example.com --full-page --dark
shotbot capture --url=https://example.com --json | jq .
```

> **Privacy:** any capture saved with `--output` is **never published on the
> CDN**. The CLI requests a private capture, the worker writes the file to a
> non-public directory on the server, the CLI fetches it once from
> `api.shotbot.net`, and the server deletes it on read. There is no public URL
> at any point | useful for sensitive pages (intranet, dashboards, customer
> data). Captures without `--output` keep the existing CDN-backed flow.

### Capture options

#### Free tier
| Option              | Values                                      | Default  |
| ------------------- | ------------------------------------------- | -------- |
| `--url`             | http(s) URL (required)                      |          |
| `--format`          | `jpg`, `png`, `webp`, `avif`, `pdf`         | `jpg`    |
| `--viewport`        | 360..1920 (px)                              | `1280`   |
| `--output-size`     | 120..1920 (resize the result, px)           | viewport |
| `--wait`            | 0..120 (seconds after page load)            | `5`      |
| `--ratio`           | `16:9`, `4:3`, `1:1`, `9:16`, etc.          | `16:9`   |
| `--full-page`       | flag                                        | off      |
| `--nojs`            | flag (disable JavaScript before navigation) | off      |
| `--color-scheme`    | `dark` \| `light` (sets prefers-color-scheme) | off    |
| `--hidpi`           | flag (2x DPR)                               | off      |

#### Pro
| Option                | Values                                                     |
| --------------------- | ---------------------------------------------------------- |
| `--dismiss-cookies`   | `accept` \| `reject` (auto-handle cookie consent banners)  |
| `--scroll`            | flag (scroll the page before capture; lazy-load trigger)   |
| `--block-ads`         | flag (block ad-network requests)                           |
| `--crop-height`       | 10..20000 (crops the result, overrides ratio, implies full-page) |
| `--selector`          | CSS selector (capture only the matched DOM element)        |
| `--http-auth-user`    | string (HTTP Basic Auth user)                              |
| `--http-auth-pass`    | string (HTTP Basic Auth password)                          |

#### PDF (only when `--format=pdf`)
| Option                | Values                                              | Default  |
| --------------------- | --------------------------------------------------- | -------- |
| `--pdf-page-size`     | `A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`      | `A4`     |
| `--pdf-margin`        | 0..50 (page margin in mm)                           | `10`     |
| `--pdf-scale`         | 0.10..2.00 (rendering scale)                        | `1.00`   |
| `--pdf-landscape`     | flag (landscape orientation)                        | off      |

#### CLI ergonomics
| Option         | Values                                      | Default  |
| -------------- | ------------------------------------------- | -------- |
| `--output`     | save image to disk; see below               | none     |
| `--json`       | print full JSON response, no chrome         | off      |
| `--timeout`    | max seconds to wait for the capture         | `180`    |

`--output` automatically requests a **private capture** | the file is not put
on `static.shotbot.net`. See the privacy note above.

### `--output` modes

| Form                               | Saves to                                                   |
| ---------------------------------- | ---------------------------------------------------------- |
| `--output`                         | `./<host>-<short_token>.<format>` (cwd, auto-named)        |
| `--output=screenshots/`            | `screenshots/<host>-<short_token>.<format>` (auto-named)   |
| `--output=path/to/file.jpg`        | exactly that path                                          |

Auto filename example for `https://www.example.com/`:
`example.com-a1b2c3d4.jpg` (`www.` stripped, first 8 chars of the job id, format extension).

## Persistent defaults

Save options once and they apply to every `capture`. Per-call flags always win.

```sh
shotbot set full-page                # always full-page
shotbot set output ./shots/          # always save into ./shots/ (and private)
shotbot set viewport 1440            # always render at 1440 px
shotbot set format webp              # always webp

shotbot defaults                     # show what's stored
shotbot defaults --keys              # list every settable key + type
shotbot unset full-page              # forget that default
```

Booleans accept `true`/`false`/`yes`/`no`/`1`/`0`; bare `set <key>` on a boolean
is shorthand for `set <key> true`. Defaults live in the same `config.json` as
the API key, under a `defaults` object.

**Free tier**

| Settable key       | Type           | Notes                                    |
| ------------------ | -------------- | ---------------------------------------- |
| `format`           | string (enum)  | `jpg` / `png` / `webp` / `avif` / `pdf`  |
| `viewport`         | int            | 360..1920                                |
| `output-size`      | int            | 120..1920 (resize the result)            |
| `wait`             | int            | 0..120                                   |
| `ratio`            | string         | `16:9`, `4:3`, `1:1`, etc.               |
| `color-scheme`     | string (enum)  | `dark` \| `light`                        |
| `full-page`        | bool           |                                          |
| `nojs`             | bool           | disable JavaScript                       |
| `hidpi`            | bool           |                                          |

**Pro**

| Settable key       | Type           | Notes                                    |
| ------------------ | -------------- | ---------------------------------------- |
| `dismiss-cookies`  | string (enum)  | `accept` \| `reject`                     |
| `scroll`           | bool           | scroll before capture                    |
| `block-ads`        | bool           |                                          |
| `crop-height`      | int            | 10..20000                                |
| `selector`         | string         | CSS selector                             |
| `http-auth-user`   | string         | HTTP Basic user                          |
| `http-auth-pass`   | string         | HTTP Basic password                      |

**PDF (only when `format=pdf`)**

| Settable key       | Type           | Notes                                    |
| ------------------ | -------------- | ---------------------------------------- |
| `pdf-page-size`    | string (enum)  | `A4`/`A3`/`A5`/`Letter`/`Legal`/`Tabloid` |
| `pdf-margin`       | int            | 0..50 (mm)                               |
| `pdf-scale`        | float          | 0.10..2.00                               |
| `pdf-landscape`    | bool           |                                          |

**CLI**

| Settable key       | Type           | Notes                                    |
| ------------------ | -------------- | ---------------------------------------- |
| `output`           | string         | path or `true`; makes every capture private + saved locally |
| `timeout`          | int            | max polling seconds                      |

### Other commands

| Command                         | What                                              |
| ------------------------------- | ------------------------------------------------- |
| `shotbot status`                | Show account plan, credits, quota, captures in flight. |
| `shotbot set <key> [value]`     | Persist a default option.                         |
| `shotbot unset <key>`           | Clear a persisted default.                        |
| `shotbot defaults [--keys]`     | List your defaults; `--keys` lists settable keys. |
| `shotbot config`                | Print the path to the config file.                |
| `shotbot reset`                 | Re-prompt for the API key.                        |
| `shotbot version`               | Print the version.                                |
| `shotbot help`                  | Show help.                                        |

## Environment

| Variable           | Effect                                                |
| ------------------ | ----------------------------------------------------- |
| `SHOTBOT_API_KEY`  | Override the stored key (useful in CI).               |
| `SHOTBOT_API_BASE` | Override the API base URL (default `https://api.shotbot.net`). |
| `NO_COLOR`         | Disable ANSI color output.                            |

## Exit codes

| Code | Meaning                                          |
| ---- | ------------------------------------------------ |
| `0`  | Success.                                         |
| `2`  | Bad invocation (missing args, bad config, etc.). |
| `3`  | Network error.                                   |
| `4`  | API returned an error response.                  |
| `5`  | Waitlisted (quota exhausted).                    |
| `6`  | Capture failed on the server side.               |
| `7`  | Polling timeout.                                 |

## CI example

```sh
export SHOTBOT_API_KEY=abc123def456
shotbot capture --url=https://staging.example.com --output=before.jpg
```

## License

MIT. See [`LICENSE`](LICENSE).
