Screenshot Any URL or HTML from the Terminal with @openkova/cli

Why a screenshot CLI?

Browser automation libraries like Playwright and Puppeteer are powerful, but they come with a setup tax: install the library, configure the browser, write the launch and capture code, handle the output path. For a one-off screenshot that's hundreds of lines of setup for a task that should be one line.

@openkova/cli wraps @openkova/core — the same engine powering the web app — into a single binary (kova) that runs anywhere Chrome does. Three subcommands, a handful of flags, and it composes with everything else in your shell.

Installation

# Global install — kova available everywhere
npm install -g @openkova/cli

# Or run once without installing
npx @openkova/cli screenshot https://example.com

Chrome detection works the same way as @openkova/mcp: checks CHROMIUM_PATH, then a puppeteer global/local install, then system paths. On macOS with Chrome installed or Linux with chromium-browser on $PATH, no configuration needed.

Three commands

kova screenshot — URL or local file

Navigates to a URL or opens a local .html file and saves a screenshot.

# Public URL
kova screenshot https://example.com

# Local file
kova screenshot ./invoice.html

# Output format and viewport
kova screenshot https://example.com --format pdf --viewport mobile

# Capture the full scrollable page
kova screenshot https://example.com --full-page

kova snippet — pipe HTML in, get an image out

Reads raw HTML from stdin and renders it as an image. This is the composable command — pair it with template engines, build scripts, or anything that emits HTML.

# Inline HTML
echo '<h1 style="font-family:sans-serif;padding:48px">Hello</h1>' | kova snippet

# From a file (via shell redirection)
kova snippet < ./og-template.html

# With a specific output format
kova snippet --format png < ./card.html

kova crawl — screenshot an entire site

Crawls a URL, discovers linked pages, and screenshots each one. Useful for archiving a site, auditing a deploy, or generating a visual diff between two versions.

# Screenshot the root page and all directly linked pages
kova crawl https://example.com

# Go one level deeper
kova crawl https://example.com --depth 2

# Save as PDF
kova crawl https://example.com --format pdf

Key flags

CI/CD integration

Because kovais a plain CLI with no server dependency, it drops into any CI pipeline that can install Chrome. Here's a GitHub Actions step that screenshots a deployed preview and saves it as an artifact:

# .github/workflows/visual-check.yml
- name: Install Chromium
  run: sudo apt-get install -y chromium-browser

- name: Install kova
  run: npm install -g @openkova/cli

- name: Screenshot preview
  run: kova screenshot ${{ steps.deploy.outputs.url }} --full-page
  env:
    CHROMIUM_PATH: /usr/bin/chromium-browser

- name: Upload screenshot
  uses: actions/upload-artifact@v4
  with:
    name: preview-screenshot
    path: "*.png"

No SaaS screenshot API to authenticate against, no usage quota to worry about — the action runs the same way on the first deploy as on the ten-thousandth.

Generating OG images in a build step

kova snippet is particularly useful for OG image generation in a static site build. Instead of calling an external API at request time, generate all images during the build and commit the PNGs:

#!/bin/bash
# generate-og.sh — run as part of your build

for post in content/posts/*.md; do
  title=$(grep '^title:' "$post" | sed 's/title: //')
  slug=$(basename "$post" .md)

  # Inject the title into your OG template and pipe to kova
  sed "s/{{TITLE}}/$title/" templates/og.html | \
    kova snippet --format png > "public/og/$slug.png"
done

The loop runs in milliseconds per image — no network round-trips, no SaaS account, and the PNGs are static files your CDN can serve directly.

Responsive QA with --viewport

Catch layout breakages before users do by adding a mobile screenshot step to your deploy workflow:

# Three viewports, one command each
kova screenshot https://staging.example.com --viewport mobile   --full-page
kova screenshot https://staging.example.com --viewport desktop  --full-page
kova screenshot https://staging.example.com --viewport wide     --full-page

The outputs are plain PNG files you can diff visually, upload as artifacts, or feed to a vision model for automated regression detection.

Archiving and testing email templates

Email clients render HTML differently from browsers, but testing the layout before sending is still useful. Render your template locally with kova snippet to check the design before it goes to an actual email client:

kova snippet --viewport mobile < ./templates/welcome-email.html

Combine with a shell loop to batch-render all templates in a directory:

for f in templates/*.html; do
  kova snippet < "$f"
done

Under the hood

@openkova/cli is built directly on @openkova/core — the same MIT-licensed library that powers the self-hosted web app. It uses puppeteer-core (no bundled Chrome) and finds a browser using the same detection chain: CHROMIUM_PATH → global/local puppeteer → system paths. The CLI is a thin command parser around the same screenshot and crawl functions, which means any bug fix or format addition in core automatically improves both the web app and the CLI.

Frequently asked questions

Does @openkova/cli require an API key or account?

No. It is MIT-licensed, runs locally, and has no usage fees or rate limits. The only requirement is a Chrome or Chromium binary on your machine.

Can I use @openkova/cli in CI/CD?

Yes. Install chromium-browser (or google-chrome) in your CI environment and call kova as a build step. Set CHROMIUM_PATH if the binary isn't on $PATH.

What is the difference between kova screenshot and kova snippet?

kova screenshot takes a URL or a local .html file path. kova snippet reads raw HTML from stdin — useful for piping template output directly into a screenshot without writing a temporary file.

How does @openkova/cli find Chrome?

It checks CHROMIUM_PATH first, then a puppeteer global/local install, then system paths (google-chrome, chromium-browser, /usr/bin/chromium, Chrome.app on macOS). Zero configuration on most developer machines.

Need screenshots from an AI assistant instead? Add a screenshot tool to Claude Desktop and Cursor with @openkova/mcp — or deploy the full web API with Docker for HTTP access from any language.