zshot 0.6.0 · released 2026-05-31
docker pull scaleassembly/zshot:0.6.0All artifacts are signed with sigstore cosign.
You can verify with the public key at https://zshot-cli.com/cosign.pub —
see verifying your download for one-line commands per platform.
This software uses code of FFmpeg 8.1 licensed under LGPL 3. Per FFmpeg's LGPL/GPL licensing, the corresponding source and our build outputs are available on the FFmpeg compliance page.
Some features of `zshot` require [a license](/support/licenses). [Sign up for a free trial license to evaluate it now](https://zshot-licensing.com/trial). `zshot` uses many different open source libraries. [Refer to this page](/support/open_source_licenses) for more information. Use of `zshot` indicates acceptance of its [EULA](/support/eula) and [Privacy Policy](/support/privacy_policy). `zshot` is permitted for commercial use, but you may not resell `zshot` nor provide it as a service. --- # Examples Source: https://zshot-cli.com/examples/ --- # Purchase Source: https://zshot-cli.com/purchase/ --- # Reference Source: https://zshot-cli.com/reference/ ## CLI Users Please refer to the [CLI flags documentation](./flags) and [config file information](./configuration). The [Examples](/examples) page will have many useful references for how to interact with the program as well. ## API Users API users should refer to the [API](./api) documentation on this site, as well as the bundled [Swagger UI]() docs that the `zshot` CLI presents when running in [`--server` mode](). Many of the [Examples](/examples) include HTTP API examples that you can refer to. ## MCP Users Users integrating `zshot` with MCP should refer to the [MCP](./mcp) documentation on this site. --- # API Source: https://zshot-cli.com/reference/api/ [`--server`](/reference/flags/server/server) runs zshot as an HTTP server, exposing capture as an API that other clients call over HTTP. It keeps a browser warm between requests, runs in [Docker](/reference/docker), exposes Prometheus [metrics](/reference/flags/server), and supports [Basic](/reference/flags/server/server-basic-auth) and [token](/reference/flags/server/server-token-auth) authentication. Server mode is a [Pro](/support/licenses) feature; [signed-URL](/reference/flags/server/server-signed-url) authentication requires [Enterprise](/support/licenses). Run zshot inside your own infrastructure and reach it from your own services. It is not built to sit on the public internet. See [Server](/reference/flags/server) for endpoints and tuning flags, and [Docker](/reference/docker) to run it in a container. ## Security The server offers [Basic](/reference/flags/server/server-basic-auth), [token](/reference/flags/server/server-token-auth), and [signed-URL](/reference/flags/server/server-signed-url) authentication, and [`--block-private-ips`](/reference/flags/security/block-private-ips) keeps a rendered page from reaching internal hosts. These controls protect a service running among trusted callers; they are not a hardening layer against wide public exposure. Put zshot behind your own network boundary and front it with a gateway that handles public traffic. ## Additional assets and the `Link` header A render returns its primary output as the response body. It can also produce sidecar artifacts. Request each with its matching `with_*` field: `with_har`, `with_warc`, `with_pprof_cpu`, `with_pprof_memory`, `with_trace`, `with_navigator_video`, `with_network_log`. Each asset the server produces is written to a temporary location and advertised with a `Link` header on the render response, one per asset: ``` Link: .har>; rel="related"; type="application/json" ``` The URL is relative, so it resolves against whatever host or reverse proxy fronts the server. Fetch the asset with a GET to that URL. Its lifetime is set by [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration); after it expires the URL returns 404. When the server requires [signed URLs](/reference/flags/server/server-signed-url), the asset links are signed and carry the same expiry. --- # Configuration Source: https://zshot-cli.com/reference/configuration/ The `zshot` configuration file ( `zshot.toml` ) is used to store licensing information. If you have a valid license key, you should store it in the file in the following format: ``` license = "MY-ZSHOT-LICENSE-KEY" ``` This file should be readable by the same user that the `zshot` process is running as. Additionally, if the file is writable, `zshot` will write back license caching information to the file to prevent frequent re-licensing checks with the `zshot` licensing server. You can specify a specific configuration file via the [`--config`](/reference/flags/common/config) flag, which will override the default lookup. ## Lookup order `zshot` resolves the license key in priority order: the [`--license-key`](/reference/flags/common/license-key) argument, then the `ZSHOT_LICENSE` environment variable, then the `license` value from the first `zshot.toml` it finds. Without [`--config`](/reference/flags/common/config), it searches: 1. `zshot.toml` in the current working directory 2. `$XDG_CONFIG_HOME/zshot.toml`, defaulting to `~/.config/zshot.toml` 3. on macOS, `zshot.toml` next to the `.app` bundle 4. `zshot.toml` in the directory containing the `zshot` binary When the resolved file is writable, `zshot` caches the signed license back to it; if no config exists, it creates one at `$XDG_CONFIG_HOME/zshot.toml`, else `~/.config/zshot.toml`. If you do not want to store your license key in a configuration file, you can also provide it via a command line argument [`--license-key`](/reference/flags/common/license-key) or via the environment variable `ZSHOT_LICENSE`. --- # Docker Source: https://zshot-cli.com/reference/docker/ The [`scaleassembly/zshot`](https://hub.docker.com/r/scaleassembly/zshot) image forwards its arguments to the `zshot` binary. Pass the same flags you would on the command line. ## Run as a server Three flags are required in a container: - [`--server`](/reference/flags/server/server) runs the HTTP server. - [`--server-bind-address 0.0.0.0`](/reference/flags/server/server-bind-address) listens on all interfaces. The server binds `127.0.0.1` by default, which is unreachable from outside the container. - [`--no-sandbox`](/reference/flags/security/no-sandbox) runs without the Chromium sandbox, which does not function in a container. ```sh docker run --rm -p 3000:3000 \ -e ZSHOT_LICENSE="MY-ZSHOT-LICENSE-KEY" \ scaleassembly/zshot \ --server --server-bind-address 0.0.0.0 --no-sandbox ``` The server listens on port 3000. See [Server](/reference/flags/server) for the endpoints and tuning flags. ## License Supply the license one of two ways: Set the `ZSHOT_LICENSE` environment variable to your license key: ```sh docker run --rm -p 3000:3000 \ -e ZSHOT_LICENSE="MY-ZSHOT-LICENSE-KEY" \ scaleassembly/zshot \ --server --server-bind-address 0.0.0.0 --no-sandbox ``` Or mount a [`zshot.toml`](/reference/configuration) and point [`--config`](/reference/flags/common/config) at it: ```sh docker run --rm -p 3000:3000 \ -v /host/zshot.toml:/etc/zshot/zshot.toml:ro \ scaleassembly/zshot \ --server --server-bind-address 0.0.0.0 --no-sandbox \ --config /etc/zshot/zshot.toml ``` ## Health checks Probe [`/status`](/reference/api). It returns 200 with the current number of in-flight requests once the server is ready. ```sh curl http://localhost:3000/status ``` --- # Flags Source: https://zshot-cli.com/reference/flags/ ## Network safety `--block-private-ips` and `--allow-ip-range` filter outbound connections by IP, so a page cannot reach internal hosts. The `robots.txt` pre-fetch honors the same filter.[^rebind] [^rebind]: The `robots.txt` fetch connects only to the IP it validated. Page navigation is filtered as well, but Chromium resolves DNS itself when connecting, leaving a narrow rebinding window zshot cannot close. For hard isolation against actively malicious input, pair the IP filter with network-level egress controls. --- # Archive Source: https://zshot-cli.com/reference/flags/archive/ --- # --har-body-size-limit Source: https://zshot-cli.com/reference/flags/archive/har-body-size-limit/ TODO --- # --har-capture-bodies Source: https://zshot-cli.com/reference/flags/archive/har-capture-bodies/ TODO --- # --har-captures-navigation Source: https://zshot-cli.com/reference/flags/archive/har-captures-navigation/ TODO --- # --har Source: https://zshot-cli.com/reference/flags/archive/har/ Write a [HAR](/reference/formats/har) of the page's network activity as a sidecar alongside another output. Takes a path: ``` zshot --output-type png --har page.har https://zshot-cli.com -f page.png ``` Capture response bodies with `--har-capture-bodies`. To emit a HAR as the primary output instead of a sidecar, use `--output-type har`. This is a Standard-tier flag. On the HTTP server, request this as `with_har=true` instead of a path. The server writes the HAR to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # --warc-captures-navigation Source: https://zshot-cli.com/reference/flags/archive/warc-captures-navigation/ TODO --- # --warc-no-gzip Source: https://zshot-cli.com/reference/flags/archive/warc-no-gzip/ TODO --- # --warc Source: https://zshot-cli.com/reference/flags/archive/warc/ Write a [WARC](/reference/formats/warc) web archive as a sidecar alongside another output. Takes a path: ``` zshot --output-type png --warc page.warc.gz https://zshot-cli.com -f page.png ``` The archive is gzip-compressed by default; pass `--warc-no-gzip` for plain WARC. To emit a WARC as the primary output instead of a sidecar, use `--output-type warc`. This is a Standard-tier flag. On the HTTP server, request this as `with_warc=true` instead of a path. The server writes the WARC to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # Browser Source: https://zshot-cli.com/reference/flags/browser/ --- # --accept-language Source: https://zshot-cli.com/reference/flags/browser/accept-language/ TODO --- # --browser-height Source: https://zshot-cli.com/reference/flags/browser/browser-height/ TODO --- # --browser-width Source: https://zshot-cli.com/reference/flags/browser/browser-width/ TODO --- # --cookie Source: https://zshot-cli.com/reference/flags/browser/cookie/ TODO --- # --device-list Source: https://zshot-cli.com/reference/flags/browser/device-list/ TODO --- # --device-scale-factor Source: https://zshot-cli.com/reference/flags/browser/device-scale-factor/ TODO --- # --device Source: https://zshot-cli.com/reference/flags/browser/device/ TODO --- # --emulate-disable-bluetooth Source: https://zshot-cli.com/reference/flags/browser/emulate-disable-bluetooth/ TODO --- # --emulate-disable-serial Source: https://zshot-cli.com/reference/flags/browser/emulate-disable-serial/ TODO --- # --emulate-disable-usb Source: https://zshot-cli.com/reference/flags/browser/emulate-disable-usb/ TODO --- # --emulate-geolocation Source: https://zshot-cli.com/reference/flags/browser/emulate-geolocation/ TODO --- # --emulate-gpu-renderer Source: https://zshot-cli.com/reference/flags/browser/emulate-gpu-renderer/ TODO --- # --emulate-gpu-vendor Source: https://zshot-cli.com/reference/flags/browser/emulate-gpu-vendor/ TODO --- # --emulate-hardware-concurrency Source: https://zshot-cli.com/reference/flags/browser/emulate-hardware-concurrency/ TODO --- # --emulate-media Source: https://zshot-cli.com/reference/flags/browser/emulate-media/ TODO --- # --emulate-memory Source: https://zshot-cli.com/reference/flags/browser/emulate-memory/ TODO --- # --emulate-mobile-device Source: https://zshot-cli.com/reference/flags/browser/emulate-mobile-device/ TODO --- # --emulate-touch-points Source: https://zshot-cli.com/reference/flags/browser/emulate-touch-points/ TODO --- # --emulate-vision-deficiency Source: https://zshot-cli.com/reference/flags/browser/emulate-vision-deficiency/ TODO --- # --full-page Source: https://zshot-cli.com/reference/flags/browser/full-page/ Capture the full scrollable page instead of just the visible viewport. zshot measures the page, scrolls through it one viewport at a time, and stitches the segments into a single tall capture.[^heuristics] Available for still image output (PNG, JPEG, WebP, TIFF, BMP, JPEG XL, and single-frame GIF/APNG/AVIF). Video output and animated-image captures (`--image-duration`) are rejected with `--full-page`. [^heuristics]: To capture pages faithfully, zshot applies several heuristics during a full-page capture: detecting and expanding content that scrolls inside an inner container rather than the page itself, and suppressing pinned elements so they appear once instead of repeating in every segment. These adjust the page as it renders, so on unusual layouts the result can differ from what you see on screen. --- # --header Source: https://zshot-cli.com/reference/flags/browser/header/ TODO --- # --javascript-file Source: https://zshot-cli.com/reference/flags/browser/javascript-file/ TODO --- # --javascript Source: https://zshot-cli.com/reference/flags/browser/javascript/ TODO --- # --platform Source: https://zshot-cli.com/reference/flags/browser/platform/ TODO --- # --proxy-auth Source: https://zshot-cli.com/reference/flags/browser/proxy-auth/ Credentials for [`--proxy-server`](/reference/flags/browser/proxy-server), in `username:password` form. This is an Enterprise-tier flag. --- # --proxy-server Source: https://zshot-cli.com/reference/flags/browser/proxy-server/ Routes the browser's traffic through a proxy. Takes an `http`, `socks4`, or `socks5` URL, for example `http://proxy.example.com:8080` or `socks5://localhost:1080`. Supply credentials with [`--proxy-auth`](/reference/flags/browser/proxy-auth). This is an Enterprise-tier flag. --- # --remove-modals Source: https://zshot-cli.com/reference/flags/browser/remove-modals/ TODO --- # --skip-robots-txt Source: https://zshot-cli.com/reference/flags/browser/skip-robots-txt/ Skips the robots.txt check that `zshot` performs by default, so a capture proceeds even when robots.txt would disallow the [zshot user agent](https://zshot-app.com/useragent.html). This is an Enterprise-tier flag. --- # --user-agent Source: https://zshot-cli.com/reference/flags/browser/user-agent/ TODO --- # Common Source: https://zshot-cli.com/reference/flags/common/ Most `zshot` operations will be affected by common options like [`--config`](/reference/flags/common/config) or [`--license-key`](/reference/flags/common/license-key). You are able to specify any of them with any operation. --- # --config Source: https://zshot-cli.com/reference/flags/common/config/ ## Config File ``` # Specify the file zshot.toml in the current directory as the configuration zshot --config zshot.toml https://zshot-cli.com/ ``` This command line flag specifies the [configuration file](/reference/configuration/) to use for this command. If you do not specify it, the program will default to looking up `$XDG_CONFIG_HOME/zshot.toml` ( and, if `$XDG_CONFIG_HOME` is not specified, `~/.config/` will be inferred ). --- # --diagnostics Source: https://zshot-cli.com/reference/flags/common/diagnostics/ ## `zshot` Diagnostics ``` # Output system diagnostics zshot --diagnostics # Output command diagnostics zshot --diagnostics --file-name test.png https://zshot-cli.com/ ``` Specifying the `--diagnostics` flag will cause `zshot` to output information about the system that is running the command, as well as helpful tools to understand how the command could be replicated in other contexts. If you are experiencing issues running `zshot`, you should provide the output of the `--diagnostics` command along with a description of the issue to [`support@zshot-app.com`](mailto:support@zshot-app.com). This will help in reproducing and assisting you with the problem. ### Warning: Content May Include Private Data Any diagnostics data you provide to support may include information that is private to your local machine. Please ensure that you do not provide any data to support that includes sensitive data or data that you do not have permission to share. --- # --file-name Source: https://zshot-cli.com/reference/flags/common/file-name/ ## File Name This indicates the target file that you would like the output rendered as. If you have not specified a format for `zshot` to transform the content as, the [format](/reference/formats) will be inferred from the file extension. ``` # Output the contents of https://zshot-cli.com/ as a PDF zshot --file-name document.pdf https://zshot-cli.com/ ``` ### Multiple Files If you have passed multiple URLs to `zshot`, the argument passed to `zshot` will be used to infer the pattern for multiple files that will be written. For example: ``` # Output three files, web-1.png, web-2.png and web-3.png, for the three URLs zshot --file-name web.png https://zshot-app.com/ https://zshot-cli.com/ https://scaleassembly.com/ ``` ### Format Override If you have specified an [`--output-type`](/reference/flags/common/output-type), this will override any detected format from the file extension. --- # --license-info Source: https://zshot-cli.com/reference/flags/common/license-info/ ## License Info ``` # Output zshot license info as a JSON payload zshot --license-info ``` This will present the `zshot` license info as a JSON payload. This will include the customer name and email for the purchaser, any expiry information, and additional attributes associated with the license. If you do not have a valid license detected from your configuration, the command will fail. --- # --license-key Source: https://zshot-cli.com/reference/flags/common/license-key/ ## License Key ``` # Output zshot license info zshot --license-key "MY-ZSHOT-LICENSE-KEY" --license-info ``` The `--license-key` allows you to specify your `zshot` license key directly in cases where you do not want to specify it via your [configuration](/reference/configuration). You may also specify the license via the `ZSHOT_LICENSE` environment variable, in cases where you would like to inject it externally (Dockerized deployments or cases where you do not want the license key to appear in process titles). --- # --log-chrome-to-stderr Source: https://zshot-cli.com/reference/flags/common/log-chrome-to-stderr/ ## CEF/Chromium Logs Output ``` # Render zshot-cli.com as a PNG, but output all Chromium log messages to STDERR zshot --log-chrome-to-stderr https://zshot-cli.com/ ```` `zshot` is based on the [CEF project](https://github.com/chromiumembedded/cef-project) which embeds the Chromium browser as a headless browser. This process itself is quite complex, and has many internal behaviors that may be helpful in observing when debugging how `zshot` rendered something. You can use `--log-chrome-to-stderr` to observe these logs. ### Log Levels The log level you specify with [`--log-level`](/reference/flags/common/log-level) will affect the logging level of the Chromium output as well. --- # --log-level Source: https://zshot-cli.com/reference/flags/common/log-level/ ## Log Levels ``` # Render zshot-cli.com as a PNG and log the zshot behavior at debug level zshot --log-level debug https://zshot-cli.com ``` When specifying a `log-level`, `zshot` will output additional debugging information. If you also specify [`--log-chrome-to-stderr`](/reference/flags/common/log-chrome-to-stderr), then CEF/Chromium logging output will be included. Valid values for `--log-level` are: * `off`: No output * `error`: Output that would explain why the process has failed * `warn`: Output that indicates system state that might cause issues * `info`: Output that is useful in understanding how `zshot` works * `debug`: Verbose output that is useful in debugging `zshot` itself * `trace`: Extremely verbose output useful in tracing low level issues with `zshot` The default value of `--log-level` is `off`. --- # --no-fail Source: https://zshot-cli.com/reference/flags/common/no-fail/ ## Do Not Fail on Non-2XX Responses ``` # Render the output of https://httpbin.org/status/404 as a PNG zshot --no-fail https://httpbin.org/status/404 ``` By default, `zshot` will consider the render attempt a failure if the target URL returns a non-2XX status code. However, you can change this behavior to consider *any completed request a success* by using the `--no-fail` flag. Other factors may contribute to the process still failing however, including network conditions (unable to reach the target server) and environment conditions (invalid licensing state). This flag will only affect how `zshot` interprets HTTP status codes. --- # --no-timeout Source: https://zshot-cli.com/reference/flags/common/no-timeout/ ## No Timeout ``` # Fetch zshot-cli.com regardless of how long it takes zshot --no-timeout https://zshot-cli.com ``` Specifying `--no-timeout` will disable all [timeouts](/reference/timeouts) in `zshot`. Use of this flag should be done with caution, especially when used in concert with [`--server`](/reference/flags/server) or [`--mcp-local-server`](/reference/flags/mcp/mcp-local-server), as it could cause the server to eventually run out of resources while waiting for requests to finish. --- # --open-source-licenses Source: https://zshot-cli.com/reference/flags/common/open-source-licenses/ ## Open Source Licensing Information ``` # Output licensing information to stdout zshot --open-source-licenses ``` `zshot` is built upon many other open source projects, each of which have their own licensing requirements. When specifying `--open-source-licenses`, `zshot` will output the license statements for all the projects used to build the version you have. This output will also include the necessary information to ensure [FFmpeg licensing compliance](/support/ffmpeg_compliance), including links to the FFmpeg source tarball and to the binary tarballs (which contain the headers) bundled with that release. --- # --output-type Source: https://zshot-cli.com/reference/flags/common/output-type/ ## Output Types ``` # Output zshot-cli.com as a PNG file zshot --output-type png https://zshot-cli.com # Output zshot-cli.com as a WARC file zshot --output-type warc https://zshot-cli.com # Output zshot-cli.com as a WEBM file zshot --output-type webm https://zshot-cli.com ``` Use `--output-type` to specify which [format](/reference/formats) you would like the output in. Each format may support different additional arguments that will affect its output: [image](/reference/flags/image) and [video](/reference/flags/video) for example support different additional flags depending on your need. The current list of supported `--output-type` arguments are: | Format | Argument Value| Category| | ------- | :-------: | ----- | | [PNG](/reference/formats/png) | `png` | [Image](/reference/flags/image) | | [PDF](/reference/formats/pdf) | `pdf` | [Document](/reference/flags/document) | | [MHTML](/reference/formats/mhtml) | `mhtml` | | | [HTML](/reference/formats/html) | `html` | | | [JPEG](/reference/formats/jpeg) | `jpeg` | [Image](/reference/flags/image) | | [JPEG XL](/reference/formats/jpegxl) | `jpegxl` | [Image](/reference/flags/image) | | [APNG](/reference/formats/apng) | `apng` | [Image](/reference/flags/image) | | [WebP](/reference/formats/webp) | `webp` | [Image](/reference/flags/image) | | [TIFF](/reference/formats/tiff) | `tiff` | [Image](/reference/flags/image) | | [AVIF](/reference/formats/avif) | `avif` | [Image](/reference/flags/image) | | [GIF](/reference/formats/gif) | `gif` | [Image](/reference/flags/image) | | [WebM](/reference/formats/webm) | `webm` | [Video](/reference/flags/video) | | [MP4](/reference/formats/mp4) | `mp4` | [Video](/reference/flags/video) | | [Markdown](/reference/formats/markdown) | `markdown` | [Document](/reference/flags/document) | | [HAR](/reference/formats/har) | `har` | [Archive](/reference/flags/archive) | | [Trace](/reference/formats/trace) | `trace` | [Diagnostics](/reference/flags/diagnostics) | | [CPU profile](/reference/formats/pprof_cpu) | `pprof_cpu` | [Diagnostics](/reference/flags/diagnostics) | | [Memory profile](/reference/formats/pprof_memory) | `pprof_memory` | [Diagnostics](/reference/flags/diagnostics) | | [WARC](/reference/formats/warc) | `warc` | [Archive](/reference/flags/archive) | | [AXTree](/reference/formats/axtree) | `axtree` | | | [LLM JSON](/reference/formats/llm_json) | `llm_json` | [Document](/reference/flags/document) | | [LLM Text](/reference/formats/llm_text) | `llm_text` | [Document](/reference/flags/document)| {.formats-table} --- # --process-timeout Source: https://zshot-cli.com/reference/flags/common/process-timeout/ ## Process Timeout ``` # Time the zshot process out after 2 seconds zshot --process-timeout 2 https://httpbingo.org/delay/3 ``` ` Sets the total time allowed for the process to complete to the number of seconds specified. This will be total time for the entire render process, including time to encode the image or video. See [timeouts](/reference/timeouts) for more information. --- # --quiet Source: https://zshot-cli.com/reference/flags/common/quiet/ ## Quiet ``` # Prevent all output zshot --quiet https://zshot-cli.com ``` Silences all output, including result filenames on a successful execution. This overrides any [log levels](/reference/flags/common/log-level) you may specify. --- # --software-rendering Source: https://zshot-cli.com/reference/flags/common/software-rendering/ ## Software Rendering ``` # Render zshot-cli.com as a PNG on the CPU, without a GPU zshot --software-rendering https://zshot-cli.com/ ``` Renders on the CPU with SwiftShader instead of the GPU. Use this when no usable GPU is available, such as a host without a graphics device or a user that lacks access to the GPU device nodes. See [Linux GPU rendering](/reference/linux) for how hardware rendering selects the GPU and which device access it requires. --- # --wait-for Source: https://zshot-cli.com/reference/flags/common/wait-for/ ## Waiting For Page Readiness ``` # Render the page when the window.load event fires zshot --wait-for load https://zshot-cli.com/ # Render the page when the document.ready event fires zshot --wait-for ready https://zshot-cli.com/ # Render the page when the networkidle0 state is arrived at zshot --wait-for networkidle0 https://zshot-cli.com/ # Render the page 5s after the page loads zshot --wait-for 5 https://zshot-cli.com/ # Render the page after the my_event CustomEvent has fired zshot --wait-for js:my_event https://zshot-cli.com/ ``` Sets the state at which point `zshot` should render the page. The following values are allowed: * `load`: The `window.load` event * `ready`: The `DOMContentLoaded` event * `networkidle0`: After there have been zero new network connections attempted for 500ms * `networkidle2`: After there have been a maximum of two network connections attempted for 1 second * `js:NAME_OF_EVENT`: When a `CustomEvent` has been triggered on the `window` object, eg: `js:my_event` would allow `zshot` to render once the page has executed the following code: `window.dispatchEvent(new CustomEvent("my_event"))` * `css:SELECTOR`: When a DOM element matching this selector exists on the page * **Any number**: If you simply specify a number, `zshot` will wait that number of seconds before continuing. `5` would wait 5 seconds, `2.5` would wait 2.5 seconds and `0` would not wait at all. The default value of `--wait-for` is `load`. ### Redirects `zshot` follows HTTP redirects, in-page navigations that run during load such as `location.href`, and instant meta-refresh automatically. To capture the destination of a redirect that fires after the page loads, such as a delayed meta-refresh or a timed script redirect, set `--wait-for` to a number of seconds larger than the redirect delay. --- # Diagnostics Source: https://zshot-cli.com/reference/flags/diagnostics/ --- # --network-log Source: https://zshot-cli.com/reference/flags/diagnostics/network-log/ Write a JSON log of the page's network requests and responses as a sidecar alongside another output. Takes a path: ``` zshot --output-type png --network-log page.network.json https://zshot-cli.com -f page.png ``` For a full archive of request and response bodies, use [`--har`](/reference/flags/archive/har) or [`--warc`](/reference/flags/archive/warc) instead. On the HTTP server, request this as `with_network_log=true` instead of a path. The server writes the log to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # --pprof-captures-navigation Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-captures-navigation/ Span the whole navigation session in the pprof instead of just the final page. Applies to any pprof produced. By default a profile covers only the destination page. With this flag, zshot re-instruments the sampling profilers periodically so each page visited contributes samples, which merge into one profile. Sampling gaps at the rotation and navigation boundaries are inherent. Over the HTTP API, pass `pprof_captures_navigation`. --- # --pprof-cpu-interval-us Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-cpu-interval-us/ CPU sampling interval in microseconds for [`pprof_cpu`](/reference/formats/pprof_cpu). Lower values sample more often, at higher overhead. Default 1000. --- # --pprof-cpu Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-cpu/ Write a [CPU sampling profile](/reference/formats/pprof_cpu) (pprof) sidecar alongside another output. Takes a path: ``` zshot --output-type png --pprof-cpu page.cpu.pprof --wait-for 3 https://zshot-cli.com -f page.png ``` The profile is gzip-compressed by default; pass `--pprof-no-gzip` for plain protobuf. To emit a CPU profile as the primary output instead of a sidecar, use `--output-type pprof_cpu`. This is a Pro-tier flag. On the HTTP server, request this as `with_pprof_cpu=true` instead of a path. The server writes the profile to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # --pprof-memory-interval-bytes Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-memory-interval-bytes/ Average number of bytes between samples for [`pprof_memory`](/reference/formats/pprof_memory). Lower values sample more allocations, at higher overhead. Default 32768. --- # --pprof-memory Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-memory/ Write a [memory allocation profile](/reference/formats/pprof_memory) (pprof) sidecar alongside another output. Takes a path: ``` zshot --output-type png --pprof-memory page.mem.pprof --wait-for 3 https://zshot-cli.com -f page.png ``` The profile is gzip-compressed by default; pass `--pprof-no-gzip` for plain protobuf. To emit a memory profile as the primary output instead of a sidecar, use `--output-type pprof_memory`. This is a Pro-tier flag. On the HTTP server, request this as `with_pprof_memory=true` instead of a path. The server writes the profile to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # --pprof-no-gzip Source: https://zshot-cli.com/reference/flags/diagnostics/pprof-no-gzip/ Write pprof output as plain protobuf instead of the default gzip-compressed form. Applies to any pprof produced — `pprof_cpu`, `pprof_memory`, and the `--pprof-cpu` / `--pprof-memory` sidecars. Over the HTTP API, pass `pprof_no_gzip`. --- # --trace-captures-navigation Source: https://zshot-cli.com/reference/flags/diagnostics/trace-captures-navigation/ When a navigator drives the page through several URLs, record the whole session in the [performance trace](/reference/formats/trace) instead of just the final page. By default the trace is trimmed to the destination: events before the last main-frame navigation are dropped, leaving only the page the navigator landed on. Set this flag to keep every step. Over the HTTP API, pass `trace_captures_navigation`. --- # --trace-no-gzip Source: https://zshot-cli.com/reference/flags/diagnostics/trace-no-gzip/ Write the [performance trace](/reference/formats/trace) as plain `.trace.json` instead of the default gzip-compressed `.trace.json.gz`. A trace is gzip-compressed unless the output path ends `.trace.json` or this flag is set; the flag wins over a `.gz` path. Over the HTTP API, where no filename is given, pass `trace_no_gzip` to the same effect. --- # --trace-no-screenshots Source: https://zshot-cli.com/reference/flags/diagnostics/trace-no-screenshots/ Omit the screenshot filmstrip from the [performance trace](/reference/formats/trace), keeping the timeline events. The trace records screenshots by default. --- # --trace Source: https://zshot-cli.com/reference/flags/diagnostics/trace/ Write a [performance trace](/reference/formats/trace) sidecar alongside another output, the way `--har` captures a HAR. Takes a path: ``` zshot --output-type png --trace page.trace.json https://zshot-cli.com -f page.png ``` The trace is gzip-compressed by default; name the path `.trace.json` or pass `--trace-no-gzip` for a plain file. To emit a trace as the primary output instead of a sidecar, use `--output-type trace`. This is a Pro-tier flag. On the HTTP server, request this as `with_trace=true` instead of a path. The server writes the trace to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # Document Source: https://zshot-cli.com/reference/flags/document/ --- # --llm-format-expects Source: https://zshot-cli.com/reference/flags/document/llm-format-expects/ TODO --- # --llm-format-model Source: https://zshot-cli.com/reference/flags/document/llm-format-model/ Select the LLM that powers the `llm`, `llm_json`, and `llm_text` output types. The value is a [provider connection string](/reference/llm_integration/providers). ```sh zshot -t llm_json \ --llm-format-model "anthropic://$ANTHROPIC_API_KEY@/claude-haiku-4-5" \ --llm-format-prompt "Summarize this page." \ https://example.com -f out.json ``` See [Providers](/reference/llm_integration/providers) for the connection-string format, the supported providers, and query options. This is a Pro-tier flag. --- # --llm-format-prompt Source: https://zshot-cli.com/reference/flags/document/llm-format-prompt/ TODO --- # --markdown-format Source: https://zshot-cli.com/reference/flags/document/markdown-format/ TODO --- # --markdown-no-title Source: https://zshot-cli.com/reference/flags/document/markdown-no-title/ TODO --- # --markdown-selector Source: https://zshot-cli.com/reference/flags/document/markdown-selector/ TODO --- # --pdf-generate-document-outline Source: https://zshot-cli.com/reference/flags/document/pdf-generate-document-outline/ TODO --- # --pdf-generate-tagged-pdf Source: https://zshot-cli.com/reference/flags/document/pdf-generate-tagged-pdf/ TODO --- # --pdf-height Source: https://zshot-cli.com/reference/flags/document/pdf-height/ TODO --- # --pdf-landscape Source: https://zshot-cli.com/reference/flags/document/pdf-landscape/ TODO --- # --pdf-prefer-css-page-size Source: https://zshot-cli.com/reference/flags/document/pdf-prefer-css-page-size/ TODO --- # --pdf-scale Source: https://zshot-cli.com/reference/flags/document/pdf-scale/ TODO --- # --pdf-width Source: https://zshot-cli.com/reference/flags/document/pdf-width/ TODO --- # Image Source: https://zshot-cli.com/reference/flags/image/ --- # --bmp-pixel-format Source: https://zshot-cli.com/reference/flags/image/bmp-pixel-format/ Pixel format for [BMP](/reference/formats/bmp) output. Requires a BMP output type; passing it with any other output type is rejected. | Value | Bits | Layout | | ----- | :--: | ------ | | `bgr24` (default) | 24 | Blue, green, red — the standard BMP byte order | | `rgb565le` | 16 | 5 red / 6 green / 5 blue, little-endian | | `gray8` | 8 | Grayscale | --- # --image-duration Source: https://zshot-cli.com/reference/flags/image/image-duration/ TODO --- # --image-framerate Source: https://zshot-cli.com/reference/flags/image/image-framerate/ TODO --- # --image-height Source: https://zshot-cli.com/reference/flags/image/image-height/ TODO --- # --image-width Source: https://zshot-cli.com/reference/flags/image/image-width/ TODO --- # MCP Source: https://zshot-cli.com/reference/flags/mcp/ Flags for serving the Model Context Protocol and for installing the bundled Agent Skill. [`--mcp-local-server`](/reference/flags/mcp/mcp-local-server) runs zshot as an MCP server over stdio. [`--install-skill`](/reference/flags/mcp/install-skill) writes the zshot Agent Skill into a skills directory or a zip package. A running [`--server`](/reference/flags/server/server) also exposes MCP over HTTP at `/mcp`. See [MCP](/reference/mcp) for setup. --- # --install-skill Source: https://zshot-cli.com/reference/flags/mcp/install-skill/ Installs zshot's bundled Agent Skill so an agent learns to drive the tool. The skill is written as a `zshot/` folder inside the target directory. With no path, it installs into the first existing skills directory it finds: `./.agents/skills`, then `~/.agents/skills`. When neither exists, it stops and asks you to create one or pass a path. ``` zshot --install-skill ``` Pass a directory to install there: ``` zshot --install-skill ~/.agents/skills/ ``` End the path in `.zip` to write a package instead of a folder, for hosts such as Claude Desktop that install a skill from a single archive. It will not overwrite an existing zip. ``` zshot --install-skill ./zshot.zip ``` See [MCP](/reference/mcp) for connecting a running server to an agent. --- # --mcp-local-server Source: https://zshot-cli.com/reference/flags/mcp/mcp-local-server/ Runs zshot as a Model Context Protocol server over stdio. zshot reads MCP JSON-RPC from stdin, writes responses to stdout, and sends all logging to stderr. It serves MCP clients such as Claude Code that launch a local server process and talk to it over stdio. This conflicts with [`--server`](/reference/flags/server/server); use one or the other. To expose MCP over HTTP from a running server instead, leave the [`/mcp`](/reference/flags/server/server-disable-mcp-endpoint) endpoint enabled. See [MCP](/reference/mcp) for client setup. --- # Navigator Source: https://zshot-cli.com/reference/flags/navigator/ ## Navigator `zshot` can augment its operation by using an [integrated LLM](/reference/llm_integration/providers). This can include hosted LLMs ( like Claude or ChatGPT ) or a local LLM. --- # --navigate Source: https://zshot-cli.com/reference/flags/navigator/navigate/ ## Automated Navigation ``` # Navigate to the weather page and screenshot it as PNG zshot --navigate "Click on the weather link" https://cnn.com/ ``` --- # --navigator-allow-url Source: https://zshot-cli.com/reference/flags/navigator/navigator-allow-url/ Widen where the [navigator](/reference/flags/navigator/navigate) may travel. By default it stays on the start URL's own origin — the same scheme, host, and port. Each `--navigator-allow-url` adds a URL glob the navigator may also visit; repeat the flag to add more. ``` zshot --navigate "find the API docs" \ --navigator-allow-url "https://*.example.com/*" \ --navigator-allow-url "https://api.partner.com/v1/*" \ https://example.com -t png -f out.png ``` A glob's `*` spans path separators, so `https://example.com/*` matches any path on that origin. Default ports are implicit: write `https://example.com/*`, not `:443`; spell out non-default ports (`http://127.0.0.1:8080/*`). Use `*` to allow any URL. Links and forms whose target the allowlist rejects are hidden from the navigator and blocked at navigation. Over the HTTP server, request this as the `navigator_allow_url` array. This is a Pro-tier flag. --- # --navigator-captures-video Source: https://zshot-cli.com/reference/flags/navigator/navigator-captures-video/ Record a video of the browser during an LLM navigation session, written as a sidecar alongside the primary output. Takes a path and requires `--navigate`: ``` zshot --output-type png --navigate "find the pricing page" --navigator-captures-video session.webm https://zshot-cli.com -f page.png ``` The format follows the path extension. Size it with `--navigator-video-width` and `--navigator-video-height`. This is a Pro-tier flag. On the HTTP server, request this as `with_navigator_video=true` alongside `navigate`. The server writes the video to a temporary location and returns its URL in a `Link` response header. See the [API reference](/reference/api) for reading those links and [`--server-additional-asset-expiration`](/reference/flags/server/server-additional-asset-expiration) for how long they live. --- # --navigator-credential Source: https://zshot-cli.com/reference/flags/navigator/navigator-credential/ TODO --- # --navigator-goal Source: https://zshot-cli.com/reference/flags/navigator/navigator-goal/ TODO --- # --navigator-max-steps Source: https://zshot-cli.com/reference/flags/navigator/navigator-max-steps/ TODO --- # --navigator-step-timeout Source: https://zshot-cli.com/reference/flags/navigator/navigator-step-timeout/ TODO --- # --navigator-type Source: https://zshot-cli.com/reference/flags/navigator/navigator-type/ Set the LLM that powers the navigator. The value is a [provider connection string](/reference/llm_integration/providers), the same format the llm formatter uses. A bare `local` runs a local model; a hosted protocol drives a remote one. ```sh zshot --navigate "Click the News link" \ --navigator-type "local:///path/to/model.gguf?gpu_layers=1" \ https://example.com ``` ```sh zshot --navigate "Click the News link" \ --navigator-type "anthropic://$ANTHROPIC_API_KEY@/claude-haiku-4-5" \ https://example.com ``` See [Providers](/reference/llm_integration/providers) for the connection-string format, the supported providers, and query options. --- # --navigator-video-height Source: https://zshot-cli.com/reference/flags/navigator/navigator-video-height/ TODO --- # --navigator-video-width Source: https://zshot-cli.com/reference/flags/navigator/navigator-video-width/ TODO --- # Security Source: https://zshot-cli.com/reference/flags/security/ --- # --allow-ip-range Source: https://zshot-cli.com/reference/flags/security/allow-ip-range/ Allows the browser to connect to a CIDR range. Repeatable. An allow range overrides any block, including the ranges added by [`--block-private-ips`](/reference/flags/security/block-private-ips). Example: `--allow-ip-range 127.0.0.1/32` permits one loopback host while private IPs stay blocked. --- # --allow-unsafe-ssl Source: https://zshot-cli.com/reference/flags/security/allow-unsafe-ssl/ Makes the browser ignore TLS certificate errors, loading pages with expired, self-signed, or hostname-mismatched certificates. This removes the protection that detects a man-in-the-middle, so restrict it to hosts you control. Sets the Chromium `ignore-certificate-errors` and `ignore-ssl-errors` switches. --- # --block-ip-range Source: https://zshot-cli.com/reference/flags/security/block-ip-range/ Blocks the browser from connecting to a CIDR range. Repeatable. Example: `--block-ip-range 10.0.0.0/8`. A matching [`--allow-ip-range`](/reference/flags/security/allow-ip-range) overrides it. To block the standard private ranges in one flag, use [`--block-private-ips`](/reference/flags/security/block-private-ips). --- # --block-private-ips Source: https://zshot-cli.com/reference/flags/security/block-private-ips/ Blocks the browser from connecting to private, loopback, and link-local IP ranges — a defense against SSRF, where a captured page redirects or fetches an internal address. On by default in [server](/reference/flags/server/server) mode; off otherwise, so enable it explicitly when capturing untrusted URLs from the CLI. Blocked ranges: `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1/128`, `fc00::/7`, `fe80::/10`. `169.254.0.0/16` covers the cloud metadata endpoint at `169.254.169.254`. Adjust the set with [`--block-ip-range`](/reference/flags/security/block-ip-range) and [`--allow-ip-range`](/reference/flags/security/allow-ip-range); an allow range wins over a block. --- # --insecure-web-mode Source: https://zshot-cli.com/reference/flags/security/insecure-web-mode/ Disables the browser's same-origin and mixed-content protections, letting a page make cross-origin requests and load insecure content it would normally be blocked from. Sets the Chromium `disable-web-security` and `allow-running-insecure-content` switches. Use it only for pages you trust; it weakens the isolation that contains a malicious page. --- # --no-sandbox Source: https://zshot-cli.com/reference/flags/security/no-sandbox/ Disables the Chromium process sandbox. zshot then renders untrusted page content without that isolation layer, so use it only where the sandbox cannot run. A container is the common case: the Chromium sandbox depends on kernel facilities a container does not grant by default, and the browser fails to start without this flag. See [Docker](/reference/docker). For background on the sandbox and the trade-off you accept by turning it off, see [no-sandbox.io](https://no-sandbox.io). --- # Server Source: https://zshot-cli.com/reference/flags/server/ [`--server`](/reference/flags/server/server) runs zshot as an HTTP server instead of rendering a single capture. It binds `127.0.0.1:3000` by default; set [`--server-bind-address`](/reference/flags/server/server-bind-address) and [`--server-bind-port`](/reference/flags/server/server-bind-port) to change that. To reach the server from another host or a container, bind `0.0.0.0`. ```sh zshot --server --server-bind-address 0.0.0.0 --server-bind-port 3000 ``` ## Endpoints - `GET /` renders from query parameters; `POST /` renders from a JSON body. See the [API](/reference/api) for sidecar assets and the `Link` header. - `GET /status` returns 200 with the current number of in-flight requests. Use it for readiness and health checks. - `GET /assets` serves sidecar artifacts referenced by the render response. - `GET /metrics` exposes Prometheus metrics unless [`--server-disable-metrics-endpoint`](/reference/flags/server/server-disable-metrics-endpoint) is set. - `GET /openapi.json` serves the OpenAPI document unless [`--server-disable-schema-endpoint`](/reference/flags/server/server-disable-schema-endpoint) is set. - `/swagger-ui` serves interactive API docs unless [`--server-disable-docs-endpoint`](/reference/flags/server/server-disable-docs-endpoint) is set. - `/mcp` serves the Model Context Protocol endpoint unless [`--server-disable-mcp-endpoint`](/reference/flags/server/server-disable-mcp-endpoint) is set. ## Concurrency [`--server-max-concurrency`](/reference/flags/server/server-max-concurrency) caps simultaneous renders. [`--server-queue-requests`](/reference/flags/server/server-queue-requests) holds requests over that cap instead of rejecting them. To run the server in Docker, see [Docker](/reference/docker). --- # --server-additional-asset-expiration Source: https://zshot-cli.com/reference/flags/server/server-additional-asset-expiration/ Lifetime in seconds for the additional render assets a request opts into with the `with_har`, `with_warc`, `with_pprof_cpu`, `with_pprof_memory`, `with_trace`, `with_navigator_video`, and `with_network_log` fields. Default is 300. Set to `0` to disable additional assets entirely — the server then writes none of them and omits the asset `Link` headers. When a render produces these sidecars, the server writes each to a temporary directory and advertises it on the response with a relative `Link: ; rel="related"` header. Clients fetch them from `GET /assets` until they expire, after which the server reclaims them. When signed URLs are configured (`--server-signed-url`), the asset links are signed and their `expires` bound is set from this lifetime, capped at `--server-signed-url-max-age` when that is smaller. --- # --server-basic-auth Source: https://zshot-cli.com/reference/flags/server/server-basic-auth/ Requires HTTP Basic authentication on every request. Pass the credential as `username:password`. Clients then send a standard `Authorization: Basic| zshot | Released | FFmpeg | Source | macOS binaries | Linux binaries |
|---|---|---|---|---|---|
| 0.6.0 | 2026-05-31 | 8.1 | tarball | tarball | tarball |
The example commands below verify zshot 0.6.0. Substitute another version or paste these into a script — the URL pattern is stable.
Each .sig file is a sigstore signing bundle — a single
JSON blob that contains the signature, certificate, and Rekor transparency-log entry. Verify it with cosign
verify-blob --bundle.
curl -LO https://releases.zshot-app.com/cli/zshot-0.6.0-macos.zip
curl -LO https://releases.zshot-app.com/cli/zshot-0.6.0-macos.zip.sig
cosign verify-blob \
--key https://zshot-cli.com/cosign.pub \
--bundle zshot-0.6.0-macos.zip.sig \
zshot-0.6.0-macos.zipcurl -LO https://releases.zshot-app.com/cli/zshot-0.6.0-linux-amd64.deb
curl -LO https://releases.zshot-app.com/cli/zshot-0.6.0-linux-amd64.deb.sig
cosign verify-blob \
--key https://zshot-cli.com/cosign.pub \
--bundle zshot-0.6.0-linux-amd64.deb.sig \
zshot-0.6.0-linux-amd64.debcosign verify \
--key https://zshot-cli.com/cosign.pub \
scaleassembly/zshot:0.6.0