@pknx/waterfall-cli

Command-line tool for waterfall-spec workflows: change requests, stories, agent prompts (Cursor / Cline / Claude Code), sync with work trackers, and PDF export.

The executable name on your PATH is waterfall (not the last segment of the package name).

Unscoped name: waterfall-cli on npm is a different package. This project publishes as @pknx/waterfall-cli.

Requirements

• Node.js 20 or newer (22 recommended)
• Git (for branch workflows and spec init)

Heavy features (diagrams, PDF) pull in optional tooling such as Puppeteer and Pandoc-related packages; first install may take a moment.

Install

npm install -g @pknx/waterfall-cli

Then:

waterfall --help

One-off run without a global install:

npx @pknx/waterfall-cli --help

Quick start

Inside or above your spec repo:

waterfall help
waterfall spec init --title "My product" ./my-spec

Configure defaults with a .waterfall file in the project (see waterfall help and built-in comments when the file is created).

Release process (maintainers)

Releases are tag-driven and immutable via GitHub Actions (.github/workflows/publish-npm.yml).

Required setup

• Repository secret NPM_TOKEN with publish rights for @pknx/waterfall-cli.
• A pushed git tag in semver format: vX.Y.Z (for example v0.1.4).

How to release

1. Ensure develop is up to date and CI is green.

2. Create and push a release tag:

   git tag vX.Y.Z
   git push origin vX.Y.Z

3. The workflow then runs automatically and:

   • validates tag format
   • aligns package.json version in CI to the tag version
   • runs npm test
   • publishes to npm (@pknx/waterfall-cli)
   • creates a GitHub Release for that exact tag

After release

• On successful publish, a follow-up job updates develop to the next patch prerelease version:
  • v0.1.4 release -> develop becomes 0.1.5-develop
• No manual npm publish is needed for normal releases.

License

MIT — see LICENSE.