Reference

Command line

Every one of the 27 commands of wf, with its options, read from wf commands --json.

wf <command> [options]

Commands

Scaffolding and building

Checking and testing

Describing the project

Rendering

Upgrading

Formatting

This chapter is the reference for wf, the one binary that creates, builds, serves, checks, formats, tests, renders and describes a WebFluent project, and for wf-lsp, the language server that brings the same checks into your editor. Look up a command here when you need its exact flags, defaults and behaviour.

wf --help lists the commands, wf <command> --help lists one command's flags, and wf --version prints the version (wf X.Y.Z).

bash

$ wf init my-site -t static $ cd my-site $ wf serve

Conventions

These rules hold for every command unless its entry says otherwise:

  • The project directory. A command that works on a project uses the current directory. -d DIR (or --dir DIR) names another one; a command that takes a PATH argument instead takes the directory, or sometimes one file, as that argument.
  • Exit status. A command exits 0 when it succeeds and non-zero when it fails, so each command works as a CI step without a wrapper. A build that stops on its findings exits 1; a build that cannot run at all — a file it cannot read, a config it cannot load — exits 2.
  • --json. A describing command prints a human-readable report by default and, with --json, the same information as JSON for a tool.
  • Previews. Every command that writes files has a flag that shows what it would do and writes nothing: wf fmt --check, wf migrate --check, wf fix --dry-run. wf commands names that flag for each command.

Checking and testing

Rendering

Describing the project

These commands print what the project and the compiler hold. Each one is also a function in the webfluent crate, named in its entry and in Building a tool on the compiler.

Environment variables

Environment variables
Variable Read by What it does

WF_INSTALL_DIR

install.sh, install.ps1

Where the binary is installed (default ~/.webfluent/bin).

WF_VERSION

install.sh, install.ps1

The release to install, such as vX.Y.Z, instead of the latest.

WF_CHROME

wf test, wf verify

The Chrome or Chromium to drive, when it is not found on its own.

WF_CHROME_NO_SANDBOX

wf test, wf verify

1 starts Chrome without its sandbox from the outset, instead of trying with one first (a container that gives it none).

WF_BIN

the Node binding

The wf binary to call.

any PUBLIC_… name

wf build

A value for env.NAME (Environments and secrets).

WF_ALLOW_SHELL_ENV

wf build, wf serve

Names, comma-separated, that public_env lists without the PUBLIC_ prefix and whose value the shell may supply (WF_ALLOW_SHELL_ENV=API_URL). Without it such a name takes its value from the config or .env only, so a cloned project cannot bundle a shell secret.

Editors

wf-lsp is the language server: it runs the compiler's checks as you type and answers your editor's questions about the code. Editors says how to install it, what it answers, and how to set up VS Code, Zed, Neovim, Helix, Emacs and any other editor with LSP support.

Building a tool on the compiler

Every command above is a function in the webfluent crate, so an editor, a site builder or an agent can call it in process instead of running wf. Each one reads the project through a webfluent::vfs::Vfs: FsVfs reads the disk, and OverlayVfs::over_disk() lays the editor's unsaved buffers over it, so a tool reports the project as it is being edited.

Most of these are the compiler's own parts: they are reached with the crate's internals feature (webfluent = { version = "7", features = ["internals"] }), are not documented, and a release may change them without a major version. The ones marked "no" are the documented API.

Building a tool on the compiler
Function

Needs internals

What it is

webfluent::build::{build, check} with BuildOptions

no

wf build and wf check, returning every line and every finding as a Diagnostic with its fixes; BuildOptions::studio is --studio

webfluent::diagnostics::fixes::fix_all

no

wf fix's fix-all, for one family in one file

webfluent::syntax::{print, reprint}, webfluent::edit::{rewrite_element, rewrite_statement, rewrite_body, rewrite_declaration, rewrite_program}

yes An element, a statement or a declaration changed in the tree and written back as the smallest edit, every other byte as it was; refused when it would not read back the same

webfluent::syntax::node_id::{build_node_map_with, layers}

no Every element's id, file, place, parent and what it is inside; the node at a caret; the Layers tree

webfluent::registry::schema::of_project_via

yes

wf components

webfluent::paged::style_value

yes

Each style property's shape, a value read into parts (read_box), and the narrowest declaration written back (edit_box)

webfluent::themes::view::{view_via, set_token, reset_token}

yes

wf theme, and one token written in its place

webfluent::motion::catalogue

yes

wf motion

webfluent::validation::{must_be_via, set_rule, remove_rule, move_rule}

yes

wf rules, and a state's validate block written back one rule at a time

webfluent::scope::paths::at_via

yes

wf scope

webfluent::i18n::{plurals, table}

yes

wf translations: CLDR's plural rules, the table, and set_message

webfluent::build::assets::{list, plan}, webfluent::media::plan

yes

wf assets

webfluent::config::{schema, json_edit}

yes

wf config, and a setting written keeping the file's shape

webfluent::commands

yes

wf commands

webfluent::agent::{changeset, context, diff, edit}

yes

wf context, and a change set an agent writes to instead of the working tree, built before anyone reads it, with anchored edits