How to Save a Webpage with SingleFile from the Command Line

Use SingleFile CLI to render a webpage in a headless browser and save the result as one self-contained HTML file:

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

Install the CLI and a compatible browser first. For a page that requires sign-in, create a browser profile, sign in interactively, and reuse that profile for the capture. SingleFile CLI also accepts a file of URLs and can crawl links when you configure its crawl options. Its output is HTML; it does not produce a screenshot image.

The official SingleFile CLI repository documents the commands and options. The parent SingleFile project describes its goal as saving a complete web page into a single HTML file.

1. Install SingleFile CLI and check the browser

SingleFile CLI runs through a headless browser. The project documents Chrome or a Chromium based browser in its default location as the standard setup. You can use Firefox with --browser-engine firefox; consult the installed help for Firefox limitations and available options.

Choose an installation method

Download an executable: Download the executable for your platform from the official releases page, save it somewhere on your PATH or invoke it by its full path, and ensure the browser is installed.

Use npm and npx: Node.js supplies npm and npx. Install the CLI locally, then run it with npx:

npm install single-file-cli
npx single-file https://www.wikipedia.org wikipedia.html

For a globally installed command, use npm install -g single-file-cli and then run single-file.

Use Docker: The project documents this basic workflow:

docker pull capsulecode/singlefile
docker run capsulecode/singlefile "https://www.wikipedia.org"

To save the result to a file in the current directory, mount that directory as the output volume. On Linux or macOS:

docker run -v "$(pwd):/usr/src/app/out" capsulecode/singlefile "https://www.wikipedia.org" wikipedia.html

On Windows Command Prompt, the repository shows %cd% for the current directory:

docker run -v %cd%:/usr/src/app/out capsulecode/singlefile "https://www.wikipedia.org" wikipedia.html

Check the repository README if your Docker setup needs a different image or output configuration.

Install from source: The manual route requires Deno. The repository documents cloning the project with its submodules and making the launcher executable on Unix-like systems:

git clone --depth 1 --recursive https://github.com/gildas-lormeau/single-file-cli.git
cd single-file-cli
chmod +x single-file
./single-file https://www.wikipedia.org wikipedia.html

After installing, check the command and options available in your installed version:

single-file --help

2. Save one webpage as a self-contained HTML file

The command syntax is single-file <url> [output] [options ...]. The URL is required; the output path is optional. Quote URLs that contain shell-sensitive characters, such as ampersands, so the shell passes the whole URL as one argument.

single-file "https://example.com/article?topic=web&page=2" article.html

Use an explicit output path when you want a predictable filename or destination:

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

The output is a browser-rendered HTML file with page resources included as supported by SingleFile. It is intended to preserve a page as a single file; it is not a guarantee that every dynamic feature, protected page, or site will be reproduced perfectly. Open the saved file in a browser and check the content you need.

Print captured HTML to standard output

To send the captured HTML to the terminal instead of naming an output file, use --dump-content:

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

You can redirect standard output to a file in a shell if that fits your workflow:

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

For authenticated pages, create a browser profile, complete sign-in in the browser window, then reuse that profile for later captures. This keeps the interactive login step separate from repeatable capture commands.

Create a profile and open the sign-in page:

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

Sign in in the browser window that opens. Exit the browser when finished so the profile is saved.
Capture the authenticated page with that profile:

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

The project says the profile is copied for reuse and left unmodified. Keep profile files private: they may contain the browser session state used to access your account. If the site expires the session, sign in again with the profile workflow.

4. Save a list of URLs or crawl links

Process a URL list

Put one URL per line in a text file, then pass it with --urls-file:

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

For repeatable batch work, use the filename template option documented by the CLI and check single-file --help for its supported placeholders. The project also documents Docker use with --dump-content=false for saving one or multiple pages using a filename template.

Crawl internal links to a limited depth

A single URL command captures that page; it does not archive the whole site. To crawl internal links one level deep, the repository gives this configuration:

single-file https://www.example.com --crawl-links=true --crawl-inner-links-only=true --crawl-max-depth=1

The CLI also documents rewrite rules, external-link crawling, and an archive mode that marks links that were not archived. Consult single-file --help for exact option names and behavior in your installed version. Set a crawl depth deliberately: the number of pages can grow with the site’s link structure.

5. Choose a browser and locate its executable

Chrome or a Chromium based browser in the default folder is the documented default. If SingleFile cannot locate your browser, pass its path explicitly:

single-file https://www.example.com page.html --browser-executable-path=/path/to/browser

Use the executable path for your actual installation; the path above is a placeholder. For Firefox, select its engine as documented:

single-file https://www.example.com page.html --browser-engine firefox

SingleFile CLI uses the Chrome DevTools Protocol for Chrome and WebDriver BiDi for Firefox. Browser engine choice, executable location, and Firefox limitations are worth checking when a capture fails or differs from what you see in a regular browser.

6. Understand options, output, and exit codes

SingleFile CLI’s options cover browser selection, output behavior, browser profiles, URL lists, and crawling. This guide shows the options established in the project instructions; use single-file --help as the authoritative list for your installed version rather than relying on options from another release.

Need	Option or pattern	What to check
Choose browser executable	`--browser-executable-path`	Provide the path to the installed browser executable.
Use Firefox	`--browser-engine firefox`	Review the CLI help for Firefox limitations.
Reuse a signed-in profile	`--browser-profile=PATH`	The profile must have an active session for the target site.
Read a URL batch	`--urls-file=FILE`	Check that the file is readable and contains valid URLs.
Capture linked pages	`--crawl-links=true`	Set link scope and depth intentionally.
Restrict to internal links	`--crawl-inner-links-only=true`	Use with crawling when you want to stay within the site.
Limit crawl depth	`--crawl-max-depth=1`	Choose a depth appropriate for the archive you need.
Write HTML to stdout	`--dump-content`	Redirect stdout if you want a file.

Exit codes help distinguish partial batch failures from a startup error:

Code	Meaning	Next step
`0`	All pages were saved.	Review the output files.
`1`	At least one capture failed while other batch or crawl pages were saved.	Identify and retry the failed URLs.
`255`	An error prevented the process from running.	Check installation, browser availability, command syntax, and help output.

7. Troubleshoot common problems

Symptom	Likely cause	Fix
`single-file: command not found`	The executable is not on PATH, or the npm package is not installed globally.	Run it with `npx single-file`, invoke the downloaded executable by its path, or check the global npm installation.
Browser cannot be found	Chrome or Chromium is absent from the expected location.	Install a supported browser or supply its path with `--browser-executable-path`.
The command starts but cannot launch the browser	Incorrect executable path, permissions, or environment-specific browser setup.	Verify the browser path and permissions. Check the CLI help and the repository instructions for your platform.
The saved page shows a login screen	The request did not use a signed-in profile, or the session expired.	Create or refresh a profile by signing in interactively, then pass it with `--browser-profile`.
The saved page is incomplete or visually different	The site may rely on dynamic behavior, protected content, or browser-specific features.	Open the source page in the selected browser, retry after confirming it loads, and compare Chrome/Chromium with Firefox if appropriate. A capture cannot guarantee every dynamic feature is preserved.
A batch reports failure but some files exist	Exit code `1` means at least one page failed while others were saved.	Keep successful outputs and retry the failed URLs individually to isolate the cause.
The command exits with `255`	An error prevented the CLI from running.	Check installation requirements, executable permissions, browser setup, URL syntax, and `single-file --help`.
Docker output is missing from the host directory	The host folder may not be mounted to the expected container output location.	Use the documented volume mount and confirm the current directory and output filename.
The output file is empty after redirection	The command may have failed before writing captured HTML to stdout.	Check its exit code and error output, then retry with an explicit output filename.

8. Performance, reliability, and cost considerations

SingleFile CLI renders pages in a browser, so captures depend on browser availability and the page loading successfully. For reliable repeat runs, pin down the browser engine and executable path, keep the signed-in profile current where required, and inspect exit codes for batches. Retry only failed URLs rather than assuming a partial batch succeeded completely.

Batch files and link crawls save manual command entry, but crawl scope affects how much work is attempted. Start with the smallest useful depth and internal-only crawling when external pages are not part of the archive. The research dossier establishes no benchmark or typical file size, so plan storage from your own pages and outputs.

The CLI itself is an open source project licensed under AGPL; its repository directs commercial service or product licensing inquiries to the maintainer. Review the project’s license and repository notes for your use case. This article does not make a legal determination.

Or skip the browser setup

If you need a screenshot image instead of a self-contained HTML archive, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. ScreenshotNeo captures screenshots and PDFs; it does not replace SingleFile when you need a self-contained HTML file.

FAQ

Does SingleFile CLI save an entire website?

No. A normal command captures the supplied page. To capture linked pages, configure crawling and a depth; a one-page command does not archive a whole site.

Can I use it without installing the CLI globally?

Yes. The project documents downloadable executables, npx, source installation, and Docker as routes to run it.

Yes, when you create a browser profile, sign in interactively, and reuse that profile for the capture. A valid session is required.

Will the saved file work offline?

SingleFile’s purpose is to save a complete page in one HTML file, but the project does not guarantee every site’s dynamic behavior will work offline. Open and inspect the saved file for the content you need.

Where can I find every option for my version?

Run single-file --help. The CLI’s options and compatibility details can change, so use the help shipped with the version you installed.