SingleFile CLI

2.0.83 verified Sat Apr 25 auth: no javascript

SingleFile CLI is a command-line tool (v2.0.83) for saving complete web pages as single HTML files, including CSS, images, fonts, and other resources embedded as data URIs. It operates by launching a headless Chromium browser via the Chrome DevTools Protocol and injecting a standalone script. Unlike browser extensions, this CLI is designed for automation, batch processing, and server-side use. It runs on Deno, Node.js (>=20), and Bun (>=1.0). Key differentiators include support for crawling links, URL filtering, Docker deployment, and extensive customization of saved output. Alternatives include monolith and archiveweb.page, but SingleFile CLI uniquely combines headless browser automation with SingleFile's proven page-saving fidelity.

Common errors

error Error: Cannot find module 'single-file-cli' ↓

cause npx single-file-cli instead of npx single-file

fix

Use 'npx single-file <url>'.

error error: Uncaught (in promise) Error: Failed to launch browser ↓

cause Chrome/Chromium not found in default path

fix

Set --browser-executable-path or install Chrome.

error Error: EACCES: permission denied, open 'out/filename.html' ↓

cause Insufficient write permissions to the output directory

fix

Specify an output path with writable permissions.

error Error: Invalid URL ↓

cause Missing protocol (http/https) in URL

fix

Add 'https://' prefix to the URL.

Warnings

breaking Node.js <20 is no longer supported ↓

fix Upgrade Node.js to >=20.

gotcha Chromium/Chrome must be installed and accessible in default location or specified via --browser-executable-path ↓

fix Set the --browser-executable-path option or install Chrome in the default directory.

gotcha Running via npm without -g requires npx prefix; otherwise command not found ↓

fix Use 'npx single-file' or install globally with -g.

deprecated The --crawl-rewrite-rule option uses regex with sed-like syntax, which may be misinterpreted in some shells ↓

fix Enclose the rule in quotes to avoid shell expansion.

Install

npm install single-file-cli

yarn add single-file-cli

pnpm add single-file-cli

Imports

single-file
wrong
```
single-file <url> without npx if not installed globally
```
correct
```
npx single-file <url>
```
Can be run via npx after npm install -g single-file-cli or as a global command.
SingleFile (Docker)
wrong
```
docker run singlefile-cli <url>
```
correct
```
docker run capsulecode/singlefile <url>
```
Docker image is named 'capsulecode/singlefile', not 'singlefile-cli'.
CLI via npx
wrong
```
npx single-file-cli <url>
```
correct
```
npx single-file <url>
```
The npx package name is 'single-file-cli', but the command is 'single-file'.

Quickstart

Saves the page https://example.com to example.html, specifying a custom Chromium executable path.

npx single-file 'https://example.com' example.html --browser-executable-path='/usr/bin/chromium-browser'