single-file-cli: Open Source Data Extraction & Web Scraping

What is single-file-cli?

Single-file-cli is a command-line tool that drives a headless Chrome or Firefox instance to save a faithful copy of a complete web page into one self-contained HTML file, built for developers, archivists and scraping teams that need scriptable, reproducible page capture rather than manual browser saving.

What it is

Single-file-cli is the command-line front end of SingleFile. Instead of shipping as a WebExtension embedded in a browser, it runs through Deno as a standalone script injected into the page via the Chrome DevTools Protocol, or via WebDriver BiDi when Firefox is selected. The result is the same page-preservation behaviour SingleFile is known for, but driven from a shell, a script or a container rather than from a browser toolbar. It lives in the JavaScript ecosystem and is distributed as a standalone executable, an npm package and a Docker image.

The concrete problem it solves is capture fidelity plus automation. Saving a page through a normal browser save dialogue loses inlined CSS, images and DOM state after the page mutates, and it cannot be scripted. Single-file-cli replaces that manual, lossy step with one command that writes a complete, portable HTML file to disk, the console or a mounted volume, and it can do so for a single URL, a list of URLs, or a crawl of a page's internal links.

Key capabilities

Writes a complete page to a single HTML file with single-file https://www.wikipedia.org wikipedia.html, or prints the markup to the console with --dump-content.
Drives headless Chrome or Chromium by default, and supports Firefox through --browser-engine firefox, with limitations documented in --help.
Sets the browser path explicitly with --browser-executable-path when Chrome is not in the default install folder.
Processes batches from a file with --urls-file=list-urls.txt, and crawls internal links from a starting URL with query parameters removed.
Captures pages behind a login by creating a reusable profile with --create-browser-profile ./profiles/example; the profile is copied and left unmodified on each run.
Names output files through the --filename-template option, and switches between file and console output with --dump-content=false.
Ships a Docker image, capsulecode/singlefile, plus an alternative Dockerfile at screenbreak/SingleFile-dockerized that also exposes an HTTP server.

Who uses it and how

Web-archiving and preservation work, where a single HTML file is easier to store, checksum and serve than a directory of assets.
Scraping and crawling pipelines that need rendered, post-JavaScript DOM content rather than raw HTTP responses.
CI or scheduled jobs using the Docker image, mounting the current directory to /usr/src/app/out to collect saved pages.
Teams capturing authenticated or personalised pages, reusing a prepared browser profile across repeated runs.
Batch jobs that feed a URL list through --urls-file and write templated filenames into a shared output volume.

Getting started

Download the standalone executable from the GitHub releases page, or install with npm install "single-file-cli" and run npx single-file, or pull the container with docker pull capsulecode/singlefile. Chrome or a Chromium-based browser must be present, unless --browser-engine firefox is set; manual installation from source requires Deno.

How it compares

The facts name no paid products this project replaces, so the closest comparison is SingleFile itself: this is the same engine lifted out of the WebExtension so it can run unattended from a shell, which matters when the browser UI is unavailable or hundreds of pages need saving. Among named alternatives, the screenbreak/SingleFile-dockerized Dockerfile is the nearer sibling, adding an HTTP server on top of command-line capture, while this project stays a pure CLI.

When to use it — and when not to

A self-hoster must provide a Chrome or Chromium binary (or Firefox), and Deno if installing manually from source, plus a writable output directory or mounted volume for saved files; Docker users get those dependencies bundled. It is a poor fit for anyone wanting a graphical, click-to-save workflow, since the whole point is shell and container automation. Two caveats sit in the supplied facts: the licence is AGPL-3.0, which imposes copyleft obligations on redistributed or network-served derivatives, and the project carries 49 open issues, so users should expect to read --help and the issue tracker for edge cases, particularly around the Firefox engine.

project readme (upstream, from github) — read inline

SingleFile CLI (Command Line Interface)

Introduction

SingleFile can be launched from the command line by running it into a (headless) browser.

It runs through Deno as a standalone script injected into the web page via the Chrome DevTools Protocol, or via WebDriver BiDi when using Firefox, instead of being embedded into a WebExtension.

Installation

SingleFile can be run without installing it, just download the executable file and save it in the directory of your choice here: https://github.com/gildas-lormeau/single-file-cli/releases

Make sure Chrome or a Chromium-based browser is installed in the default folder. Otherwise you might need to set the --browser-executable-path option to help SingleFile locating the path of the executable file. Firefox can be used instead by setting the --browser-engine firefox option, with some limitations described in the help.

Installation with Docker

Installation from Docker Hub

docker pull capsulecode/singlefile

docker tag capsulecode/singlefile singlefile
Manual installation

git clone --depth 1 --recursive https://github.com/gildas-lormeau/single-file-cli.git

cd single-file-cli

docker build --no-cache -t singlefile .
Run

docker run singlefile "https://www.wikipedia.org"
Run and redirect the result into a file

docker run singlefile "https://www.wikipedia.org" > wikipedia.html
Run and mount a volume to get the saved file in the current directory
- Save one page
  
  docker run -v %cd%:/usr/src/app/out singlefile "https://www.wikipedia.org" wikipedia.html (Windows)
  
  docker run -v $(pwd):/usr/src/app/out singlefile "https://www.wikipedia.org" wikipedia.html (Linux/UNIX)
- Save one or multiple pages by using the filename template (see --filename-template option)
  
  docker run -v %cd%:/usr/src/app/out singlefile "https://www.wikipedia.org" --dump-content=false (Windows)
  
  docker run -v $(pwd):/usr/src/app/out singlefile "https://www.wikipedia.org" --dump-content=false (Linux/UNIX)
An alternative docker file can be found here https://github.com/screenbreak/SingleFile-dockerized. It allows you to save pages from the command line interface or through an HTTP server.

Manual installation

Install Deno
There are 3 ways to download the code of SingleFile, choose the one you prefer:
- Install with npm and run single-file via npx (npm and npx are installed with Node.js)
```
npm install "single-file-cli"
npx single-file ...
```
  You can also install SingleFile globally with -g when running npm install.
- Download and unzip manually the master archive provided by Github
```
unzip master.zip .
cd single-file-cli-master
```
- Download with git
```
git clone --depth 1 --recursive https://github.com/gildas-lormeau/single-file-cli.git
cd single-file-cli
```
Make single-file executable (Linux/Unix/BSD etc.).
```
chmod +x single-file
```

Run

Syntax
```
single-file  [output] [options ...]
```
Display help
```
single-file --help
```

Examples

Dump the HTML content of https://www.wikipedia.org into the console

single-file https://www.wikipedia.org --dump-content

Save https://www.wikipedia.org into wikipedia.html in the current folder

single-file https://www.wikipedia.org wikipedia.html

Save a page needing a logged-in session. Create the profile first, log in to the website in the browser window, and quit the browser to save it. Then reuse the profile as many times as needed, it is copied and left unmodified.

single-file --create-browser-profile ./profiles/example https://www.example.com/login
single-file https://www.example.com/account account.html --browser-profile=./profiles/example

Save https://www.wikipedia.org with Firefox

single-file https://www.wikipedia.org wikipedia.html --browser-engine firefox

Save a list of URLs stored into list-urls.txt in the current folder

single-file --urls-file=list-urls.txt

Save https://www.wikipedia.org and crawl its internal links with the query parameters removed from the URL

single-file https://www.wikipedia.org --crawl-links=true --crawl-inner-links-only=true --crawl-max-depth=1 --crawl-rewrite-rule="^(.*)\\?.*$ $1"

Save https://www.wikipedia.org and external links only

single-file https://www.wikipedia.org --crawl-links=true --crawl-inner-links-only=false --crawl-external-links-max-depth=1 --crawl-rewrite-rule="^.*wikipedia.*$"

Save http://info.cern.ch (i.e. the first website) and its internal links into a single self-extracting ZIP file, and mark the links to pages missing from the archive

single-file http://info.cern.ch first-website.html --crawl-links=true --crawl-max-depth=2 --crawl-save-archive=true --crawl-save-archive-mark-unarchived-links=true --compress-content=true

Exit code

The exit code is 0 when all the pages have been saved, 1 when at least one capture failed (the other pages of the batch or the crawl are still saved), and 255 when an error prevented the process from running.

Compile executables

Compile executables into /dist

./compile.sh

License

SingleFile and SingleFile CLI are licensed under AGPL. Code derived from third-party projects is licensed under MIT. Please contact me at gildas.lormeau <at> gmail.com if you are interested in licensing the SingleFile code for a commercial service or product.

Frequently asked questions

Is single-file-cli free to use?

single-file-cli is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does single-file-cli do?

CLI tool for saving a faithful copy of a complete web page in a single HTML file (based on SingleFile)

What is single-file-cli written in?

single-file-cli is primarily written in JavaScript. Its source is publicly available at https://github.com/gildas-lormeau/single-file-cli, and it has 1,679 GitHub stars.