webpack-cli: the argument parser standing between you and a webpack build

The rule that governs everything else

One sentence in the Introduction is the whole contract: the CLI provides the interface of options webpack uses in its configuration file, and the CLI options override options passed in the configuration file.

That precedence rule is why the tool exists as a separate package rather than being folded into webpack itself. Anything in a `webpack.config.js` file can be overridden from the command line, which is what makes a one-off flag on a CI invocation possible without editing a checked-in config.

If you followed webpack's own Getting Started guide, the README notes, webpack CLI is already installed. Otherwise there are three install routes, one per package manager:

npm install --save-dev webpack-cli
yarn add webpack-cli --dev
pnpm add --D webpack-cli

It is a dev dependency, never a runtime dependency, which is correct since it does not ship in your bundle.

Nine commands, and aliases for all of them

The command list is short enough to read in one pass, and every command has aliases so you can type the short form:

build|bundle|b [entries...] [options]
complete [shell]
configtest|t [config-path]
help|h [command] [option]
info|i [options]
serve|server|s [entries...] [options]
version|v [commands...]
watch|w [entries...] [options]

Reading them tells you what the CLI is for. `build` is the default command and can be omitted, so the bare `webpack` invocation works. `watch` is the same thing in watch mode. `serve` brings up a development server with live reloading. `configtest` validates a configuration without building, which is the one to reach for when a config file is not doing what you expect. `info` returns information about the local environment, useful when a build fails for a reason you have not seen before.

`version` is broader than you would expect: it reports the version number of webpack, webpack-cli, webpack-dev-server and commands. That last one is the small design choice that saves the most time, because when three packages have to agree on versions, one command that prints all of them beats reading three package pages.

Completion generated from webpack's own schema

Shell completion is the feature that reveals the architecture. The README says completions are read from webpack's own schema, so they cover whatever your webpack and webpack-dev-server versions support. The schema is the single source of truth, and completion is one consumer of it. Validation and the generated documentation are others.

Completion covers zsh, bash, fish and powershell, and it is served by a separate optional package, `@bomb.sh/tab`, which is not installed alongside webpack-cli:

npm install --save-dev @bomb.sh/tab

You then point your shell at the generated script, and the pattern differs per shell. For zsh you append a `source` line for a process substitution to `.zshrc`, for bash the same to `.bashrc`, for fish you write the output into a completions directory as a `.fish` file, and for powershell you write a `.ps1` file and source it from your profile. Once the shell restarts, completion covers commands, their aliases, options and option values, with the README showing that `webpack b` plus Tab completes to `webpack build`, and that `webpack build --mode=` plus Tab offers `development`, `production` and `none`.

That an optional package provides this is a sensible split, since nobody wants a shell integration installed by default into every webpack project.

Three exit codes and four versions of serve options

The exit code contract is documented in a small table, and it is stricter than most CLIs:

0   Success
1   Errors from webpack
2   Configuration/options problem or an internal error

The distinction between 1 and 2 is the useful part. Code 1 means webpack ran and reported errors, which is a build failure you probably want to fail a pipeline on. Code 2 means the configuration or options were wrong, or the CLI hit an internal error, which is a different class of problem and often points at a flag you mistyped. Wrap the CLI in a script and this becomes the difference between retrying a build and fixing an invocation.

The versioned documentation at the repository root is the other telling artefact. There is a base `OPTIONS.md` and then three separate files, `SERVE-OPTIONS-v4.md`, `SERVE-OPTIONS-v5.md` and `SERVE-OPTIONS-v6.md`. Maintaining three documents for three dev server majors is tedious work most projects skip, and it is the clearest evidence that cross-version correctness is treated as part of the product.

Recent releases reinforce it. Version 7.2.3 fixed resolution of the `webpack-dev-server` type from its default export so the types work with both v5 and v6, and allowed `toml@5` as a peer dependency for TOML configuration files. Version 7.2.2 enabled the Node.js compile cache to speed up CLI startup, available on Node 22.8.0 and later.

A monorepo with the tooling to match

The tree shows a workspace rather than a single package, with `packages/` at the root of the actual code and the main CLI logic in `packages/webpack-cli`. The root `package.json` declares workspaces pointing at `./packages/*`, and it is marked private with an empty version, which is what a monorepo root looks like.

The build is TypeScript driven by `tsc --build`, and the scripts read like a well-run project. `prebuild` cleans TypeScript build info files, `pretest` builds and lints before tests run, and `release` builds then publishes. Versioning uses changesets: there is a `.changeset/` directory, and the `version` script runs `changeset version` followed by a script that syncs changelogs, which is why `CHANGELOG.md` is generated rather than hand-written. Each package gets its own release, which is how `[email protected]` and `[email protected]` shipped on the same day.

The linting setup is unusually broad: `eslint.config.mjs` for flat-config linting, `prettier.config.js` with a separate `.prettierignore`, `cspell.json` for spellchecking, `.husky/` with a `lint-staged.config.js` for pre-commit checks, and `jest.config.js` with `.c8rc.json` and `.codecov.yml` for coverage. There is also a `smoketests/` directory run by its own script under c8 coverage, which suggests the maintainers test the installed package rather than only the source.

Scaffolding, and the arguments about what to ask

For a new project, the README points at `npx create-webpack-app init`, and the interesting part is what the prompt does and does not ask. It asks which features you want, naming scss, TypeScript and PWA support among others. A recent release note for `[email protected]` shows the direction of travel: it stopped asking about HTML and CSS, scaffolded TypeScript on webpack's own support, and kept one question for the CSS tools webpack does not cover, naming PostCSS, Sass, Less and Stylus and each preprocessor with PostCSS. A companion note says the init templates use webpack's native CSS and HTML support.

That is a small argument about principle rather than a feature. The tool stopped asking about things webpack handles itself, because a question the framework has already answered is a question that can only be answered wrong later.

The rest of the project structure is straightforward. Funding runs through Open Collective, the README links to GitHub Discussions and a Discord server, contribution guidance is in `.github/CONTRIBUTING.md`, and the code of conduct is a separate document. The Discussions link points at the webpack organisation rather than this repository, which tells you CLI questions are handled as part of the wider webpack project rather than in an isolated tracker.

Editorial conclusion

The design decision that makes webpack-cli pleasant is that the command surface is generated from a schema rather than hand-maintained, which is why shell completion, option validation and the docs cannot drift apart. Three files in the repository root show how seriously that is taken: a base OPTIONS.md plus three separate serve option documents for dev server v4, v5 and v6, because the same flag means different things across versions. The three exit codes, 0 for success, 1 for webpack errors and 2 for configuration or options problems, are documented in a table and are the contract worth knowing if you wire the CLI into CI. Start with `npx create-webpack-app init` for a new project, then read the version-specific serve document that matches your dev server.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. webpack/webpack-cli on GitHub