Skip to Content
WebFrostdocs
Reference

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.com

No 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 -v

Flags 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.

FlagEffect
--help, -hHelp for the command
--verboseDebug-level output, and a stack trace on unexpected errors (same as WEBFROST_LOG_LEVEL=debug)
--quietOnly warnings and errors
--jsonMachine-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

CodeMeaning
0Success
1The command ran and failed: a snapshot ended failed, an import had failures, something was not found, doctor found a required piece missing
2Usage error: unknown command or flag, missing or invalid argument. No command at all also exits 2.
130, 143Stopped 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).

FlagEffect
--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, dnf or winget;
  • 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.

FlagEffect
--jsonPrint { 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.

FlagEffect
--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
--jsonPrint { items, total, page, limit }
webfrost list --status failed --limit 10

When 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.

FlagEffect
--limit <n>Results per page (default 20, at most 100)
--page <n>Page of results, from 1
--jsonPrint { items, total, page, limit }, snippets as plain text
webfrost search "climate change" --limit 5 --json

webfrost 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.xml

Only 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
OptionDescription
--to <url>Required. The server's base URL (no /api/v1).
--insecureAllow 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.
--jsonPrint [{ 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.zip

The 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

CommandDescription
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 1

Schedules

CommandDescription
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 listList schedules: id, kind ([url] or [rss]), cron, URL, last run, next run.
schedule remove <id>Remove a schedule.
schedule workerRun 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

CommandDescription
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 listList 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:

  1. --password-stdin: the first line of standard input. printf '%s' "$PW" | webfrost admin create --username admin --password-stdin
  2. --password <pass>: still works, but warns, because the value ends up in your shell history and in the process list.
  3. The WEBFROST_PASSWORD environment variable.
  4. 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-31

The 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:

  1. WEBFROST_CHROMIUM_PATH, used as given. A path that does not exist is an error, not a silent fallback.
  2. WebFrost's cache: the headless Chromium webfrost setup installed.
  3. A system Chrome or Chromium: /Applications/Google Chrome.app (and Chromium, Edge, Brave there), /usr/bin/chromium, chromium-browser, google-chrome and google-chrome-stable on PATH and in /usr/bin, /snap/bin/chromium, and Program Files\Google\Chrome or Edge on Windows.
  4. Playwright's own browser cache (what bunx playwright install chromium fills).

Environment variables

VariableDefaultDescription
WEBFROST_DIR~/.webfrostDirectory 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_LEVELinfodebug, info, warn or error. --verbose and --quiet override it.
WEBFROST_CONCURRENCY3Pipelines in parallel for import and schedule worker
WEBFROST_DOMAIN_DELAY_MS1000Spacing of archives of the same host, in milliseconds
WEBFROST_CHROMIUM_PATHnoneUse an existing Chromium or Chrome binary
WEBFROST_PASSWORDnonePassword for admin create
WEBFROST_API_KEYnoneAPI key of the server push uploads to
OTEL_EXPORTER_OTLP_ENDPOINTnoneSend 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.

On this page