CLI
Every webfrost command, flag, exit code and environment variable, with examples.
webfrost is one binary: the command-line tools and the server. The archive commands (add, list, search...) work directly on the archive directory and do not talk to a server; serve runs the server. Install it first.
webfrost add https://example.comNo CLI in the Docker image
The server image does not contain the CLI. Create the admin user in the browser or with POST /api/v1/setup. See Deploy.
Help, version and flags
webfrost --help # every command
webfrost help schedule add # one command, same as: webfrost schedule add --help
webfrost --version # also -vFlags are parsed per command, and every command accepts both --flag value and --flag=value. Unknown flags and missing arguments are usage errors, not silently ignored.
| Flag | Effect |
|---|---|
--help, -h | Help for the command |
--verbose | Debug-level output, and a stack trace on unexpected errors (same as WEBFROST_LOG_LEVEL=debug) |
--quiet | Only warnings and errors |
--json | Machine-readable output, on the commands that list it below. Logs go to stderr, so stdout is only the JSON. |
--verbose and --quiet go after the command: webfrost add https://example.com --verbose.
Log lines look like [14:02:11] INFO Snapshot 1 archived. Info goes to stdout, warnings and errors to stderr. Results such as list and search are plain tab-separated text.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | The command ran and failed: a snapshot ended failed, an import had failures, something was not found, doctor found a required piece missing |
2 | Usage error: unknown command or flag, missing or invalid argument. No command at all also exits 2. |
130, 143 | Stopped by Ctrl+C (SIGINT) or SIGTERM |
Errors print as one line, Error: <message>, on stderr. Unexpected errors show their stack trace only with --verbose.
A snapshot is done when at least one extractor produced output. Individual extractors can still fail inside a done snapshot (the screenshot without a Chromium, for example): that is exit code 0. A snapshot is failed when the page could not be fetched (network error, or HTTP status 400 and above) or when no extractor produced anything: that is exit code 1.
Run
webfrost serve
Run the HTTP API, the web UI and the scheduler in this process. The same server as the Docker image, with the same environment variables (PORT, HOST, WEBFROST_DIR, SESSION_SECRET, AUTH_DISABLED, ...: see Configuration).
| Flag | Effect |
|---|---|
--port <port> | Overrides PORT (default 3000) |
--host <address> | Overrides HOST (default 0.0.0.0, or 127.0.0.1 with AUTH_DISABLED=true) |
When SESSION_SECRET is not set, serve generates one on first run and stores it in <data dir>/session-secret with mode 0600, and reuses it afterwards. Keep the data directory private and back the file up with the archive, or set SESSION_SECRET yourself.
Ctrl+C or SIGTERM stops gracefully: the scheduler first, then the listener, then running archives get up to WEBFROST_SHUTDOWN_TIMEOUT_MS (20 seconds) to finish. Unfinished snapshots stay pending and resume at the next start.
webfrost setup
Install a headless Chromium unless a usable one is found. See Chromium lookup order. --force downloads one even when another is found. Exits 1 when the download or the browser fails.
webfrost doctor
Check that WebFrost has what it needs, and say what to do about what is missing:
- version, runtime (compiled binary or source), OS and CPU;
- the data directory (exists, writable) and the database (opens, how many snapshots);
- Chromium (which one, from where, and that it starts);
- yt-dlp and ffmpeg (optional), with an install command for your OS:
brew,apt,dnforwinget; - whether the server port is free.
Exits 1 if a required check fails (data directory, database, Chromium). Missing yt-dlp or ffmpeg and a busy port are warnings. --json prints { ok, checks }.
Archive
webfrost init
Create the archive database in the data directory: Archive initialized at <dir>. Optional; every command opens or creates it.
webfrost add <url>
Archive one http or https URL and wait until the pipeline finishes. Runs all extractors, with media extraction too when yt-dlp recognizes the URL. Prints Snapshot <id> archived. and exits 0 when the snapshot is done; prints the final status and exits 1 otherwise.
| Flag | Effect |
|---|---|
--json | Print { id, url, status, extractors: [{ name, ok, error }] } on stdout |
webfrost add https://example.com
webfrost add https://example.com --json | jq '.extractors[] | select(.ok | not)'webfrost list
List snapshots, newest first, as id, status, url separated by tabs.
| Flag | Effect |
|---|---|
--status <status> | Only pending, done or failed snapshots |
--limit <n> | How many to show (default 50, at most 1000) |
--page <n> | Page of results, from 1 |
--json | Print { items, total, page, limit } |
webfrost list --status failed --limit 10When more exist than were shown, a hint on stderr gives the next --page.
webfrost delete <id>
Delete a snapshot, its database rows and its stored files. There is no trash. Exits 1 if the id does not exist.
webfrost search <query>
Full-text search (SQLite FTS5) over URL, title, text and tags, best match first. Prints id and URL, then a plain-text snippet, or No results.. The query uses FTS5 syntax: "exact phrase", prefix term*, column filters such as title:term. An invalid expression returns no results.
| Flag | Effect |
|---|---|
--limit <n> | Results per page (default 20, at most 100) |
--page <n> | Page of results, from 1 |
--json | Print { items, total, page, limit }, snippets as plain text |
webfrost search "climate change" --limit 5 --jsonwebfrost search:rebuild
Rebuild the search index from existing data. Use it after index corruption or a failed import.
Import
webfrost import [--format <fmt>] <url-or-file>
Archive every URL found in a file or at an http(s) address. --format is one of text, opml, netscape or rss; without it the format is detected from the file name and content. The command runs all pipelines and ends with Import complete: total=…, done=…, skipped=…, failed=… (…s). It exits 1 if any URL could not be queued or ended failed, 0 otherwise.
webfrost import urls.txt
webfrost import bookmarks.html
webfrost import subscriptions.opml
webfrost import --format=rss https://example.com/feed.xmlOnly rss imports skip URLs that already have a snapshot. Ctrl+C stops at once; snapshots that did not finish stay pending and resume the next time serve or schedule worker runs. Details and format rules: Bulk import.
A snapshot bundle (a ZIP file from webfrost export) is recognised by its content and imported as it is: one new snapshot with the bundle's files, results and tags, without archiving anything again. --format does not apply to it.
webfrost import snapshot-12.zip
# Imported snapshot bundle snapshot-12.zip as snapshot 31 (done): https://example.com/Push and export
Archive on one machine, keep the snapshot on another. The guide: Archive on your machine, keep it on the server.
webfrost push <id...> --to <url>
Export each snapshot as a bundle and upload it to a WebFrost server (POST /api/v1/snapshots/import), which stores it as a new snapshot with a new id: same files, results, status, creation time and tag names (tags are created on the server when missing). The snapshots must have finished (done or failed).
export WEBFROST_API_KEY=wf_... # an API key of the server
webfrost push 12 --to https://archive.example.com
# Pushed snapshot 12 (73.4 MB): snapshot 57 on https://archive.example.com, done
webfrost push 12 13 14 --to https://archive.example.com --json| Option | Description |
|---|---|
--to <url> | Required. The server's base URL (no /api/v1). |
--insecure | Allow a plain-http --to URL that is not this machine. Without it such a URL is a usage error (exit 2), since the key and the archive would travel unencrypted. |
--json | Print [{ id, ok, remote: { id, url, status }, bytes, error }], one per snapshot. |
The key comes from WEBFROST_API_KEY only, never from a flag, so it does not end up in shell history or process lists. Without it the command fails before sending anything. Create a key in the web UI (Settings, API keys) or with webfrost admin key create --name laptop on the server. A plain-http URL is accepted for this machine (localhost, *.localhost, 127.0.0.0/8, [::1]) and otherwise only with --insecure, which still prints a warning. Text from the server (error messages) is printed with control characters removed, so a hostile server cannot send terminal escape sequences. Redirects are not followed, so the key never goes to another host.
Each bundle is written to a temporary file and uploaded with its size known; on a terminal, uploads over 1 MB show a progress line. One snapshot that fails (not found, refused by the server) does not stop the others. Exit code 0 when every snapshot was stored, 1 otherwise, 2 for a usage error. A reverse proxy in front of the server may have its own upload limit below the server's WEBFROST_IMPORT_BUNDLE_MAX_BYTES (default 2 GiB); raise it for large videos.
webfrost export <id> [-o <file>]
Write a snapshot's bundle to a file, snapshot-<id>.zip by default. --json prints { id, path, bytes }. Import it with webfrost import <file> into another local archive, or upload it with curl to POST /api/v1/snapshots/import.
webfrost export 12 -o talk.zipThe bundle is a ZIP with manifest.json (the snapshot, its tag names and every result) and the snapshot's files; the format is described in the REST API reference. Files are streamed from storage (filesystem or S3) into the ZIP one at a time, so memory use does not grow with the size of the snapshot. No file may reach 4 GiB (plain ZIP, no ZIP64).
Tags
| Command | Description |
|---|---|
tag create <name> [--color <hex>] | Create a tag. Fails if the name exists. |
tag add <snapshot-id> <name> | Add a tag to a snapshot, creating the tag if needed. |
tag list [<snapshot-id>] | List all tags, or the tags on one snapshot. Columns: id, slug, name, color. |
tag remove <tag-id> | Delete a tag and remove it from every snapshot. Takes the tag id, not a name. |
webfrost tag create research --color "#4f46e5"
webfrost tag add 1 research
webfrost tag list 1Schedules
| Command | Description |
|---|---|
schedule add <url> --cron <expr> | Archive a URL on a cron schedule. |
schedule add --rss <feed-url> --cron <expr> | Archive the new items of an RSS or Atom feed on a cron schedule. |
schedule list | List schedules: id, kind ([url] or [rss]), cron, URL, last run, next run. |
schedule remove <id> | Remove a schedule. |
schedule worker | Run due schedules in this process until stopped. |
webfrost schedule add https://example.com --cron "0 0 * * *"
webfrost schedule add --rss https://example.com/feed.xml --cron "0 * * * *"schedule worker polls every 30 seconds, runs due schedules through the same scheduler the server embeds, runs pipelines at WEBFROST_CONCURRENCY, and re-queues snapshots left pending by an interrupted run. You do not need it when webfrost serve or the Docker server runs; it is for CLI-only setups. It is safe next to a server on one archive, because due schedules are claimed atomically. Set WEBFROST_SCHEDULER=false on the server to make the worker the only one. Ctrl+C lets running archives finish (up to 20 seconds). Cron is evaluated in the process time zone (TZ); it accepts names (mon-fri, jan), steps over ranges and @daily-style aliases, and schedule add rejects out-of-range values. See Scheduled archiving.
Admin
| Command | Description |
|---|---|
admin create --username <name> | Create the admin user and a key named default. The password needs at least 8 characters. Prints the key once. |
admin key create --name <label> [--expires <date>] | Create an API key. Prints the key once. |
admin key list | List active keys: id, name, expiry, last used. |
admin key revoke <id> | Revoke a key. |
--expires takes an ISO 8601 date or date-time (2027-12-31, 2027-12-31T23:59:59Z, with or without an offset) in the future. A date without a time means 00:00 UTC.
Password input
admin create reads the password from the first match of:
--password-stdin: the first line of standard input.printf '%s' "$PW" | webfrost admin create --username admin --password-stdin--password <pass>: still works, but warns, because the value ends up in your shell history and in the process list.- The
WEBFROST_PASSWORDenvironment variable. - A prompt on the terminal, asked twice, without echo.
Passing both --password-stdin and --password is a usage error. With none of the sources and no terminal, the command is a usage error (exit 2).
webfrost admin create --username admin
webfrost admin key create --name ci --expires 2027-12-31The CLI writes straight to the database, so it works with or without a server running.
Chromium lookup order
Every command that opens a browser (add, import, schedule worker, serve) and doctor look for it in this order and use the first match:
WEBFROST_CHROMIUM_PATH, used as given. A path that does not exist is an error, not a silent fallback.- WebFrost's cache: the headless Chromium
webfrost setupinstalled. - A system Chrome or Chromium:
/Applications/Google Chrome.app(and Chromium, Edge, Brave there),/usr/bin/chromium,chromium-browser,google-chromeandgoogle-chrome-stableonPATHand in/usr/bin,/snap/bin/chromium, andProgram Files\Google\Chromeor Edge on Windows. - Playwright's own browser cache (what
bunx playwright install chromiumfills).
Environment variables
| Variable | Default | Description |
|---|---|---|
WEBFROST_DIR | ~/.webfrost | Directory with archive.db and snapshots/. The CLI and the server share it. |
WEBFROST_CACHE_DIR | $XDG_CACHE_HOME/webfrost or ~/.cache/webfrost (Linux), ~/Library/Caches/webfrost (macOS), %LOCALAPPDATA%\webfrost (Windows) | Where setup installs Chromium |
WEBFROST_LOG_LEVEL | info | debug, info, warn or error. --verbose and --quiet override it. |
WEBFROST_CONCURRENCY | 3 | Pipelines in parallel for import and schedule worker |
WEBFROST_DOMAIN_DELAY_MS | 1000 | Spacing of archives of the same host, in milliseconds |
WEBFROST_CHROMIUM_PATH | none | Use an existing Chromium or Chrome binary |
WEBFROST_PASSWORD | none | Password for admin create |
WEBFROST_API_KEY | none | API key of the server push uploads to |
OTEL_EXPORTER_OTLP_ENDPOINT | none | Send traces and metrics of every command to your OpenTelemetry collector; flushed when the command ends. See Observability. |
Timeouts, storage and the server variables serve reads are in Configuration.