CLI reference

Every command and option of @stagepass/cli, read from the CLI source.

Commands

Every command accepts -v or --verbose. stagepass --version prints the installed version and stagepass --help lists all commands.

stagepass setup

Checks for Homebrew, runs brew install caddy php dnsmasq, points *.sp to 127.0.0.1 in Dnsmasq and writes /etc/resolver/sp. Writing the resolver asks for your password. Run it once per Mac.

stagepass link

Serves the current folder at https://<domain>.sp. Without a domain, the folder name is turned into a valid domain. Unsafe roots like / or your home folder are refused. Running it again keeps stored origins unless you change them with flags.

Examples:

$ stagepass link my-project --origin www.example.com --origin example.com
$ stagepass link my-project --origin my-project.webflow.io
$ stagepass link my-project --remove-origin old.example.com
$ stagepass link my-project --no-allow-all-origins
$ stagepass link my-project --allow-all-origins   # emergency / legacy compatibility only

Re-running stagepass link keeps stored origins / allow-all setting unless you change them with flags. Omitting both --allow-all-origins and --no-allow-all-origins leaves the stored value unchanged. New projects default to allowAllOrigins: false.

If projects.json is missing an entry but a v2 Caddyfile block exists, CORS options are restored from the # stagepass-options: marker instead of being reset.

stagepass unlink

Removes the site block for the domain from the local Caddy config.

stagepass reload

Reloads the Caddy config after manual changes. Old site blocks are upgraded first.

stagepass start

Asks for your password once, checks port 443 and offers to free it if another server uses it. Then it upgrades old site blocks, restarts PHP and starts Caddy. Logs go to ~/.stagepass/server.log unless you pass -v.

stagepass stop

Stops Caddy and the PHP service.

stagepass doctor

Checks Homebrew, Caddy, PHP, Dnsmasq, the resolver, port 443, the Caddyfile, your projects, the certificates and the LaunchAgent. In a project folder it also compares the declared modules with the live site. It is read only, never uses sudo and exits with 1 if a check fails.

stagepass certs

stagepass certs check checks that the local Caddy certificate authority is valid and trusted in the System keychain, finds orphaned certificates and tests a TLS handshake for each linked domain. It never deletes keychain items or files. stagepass certs trust runs caddy trust after you confirm.

stagepass autostart

stagepass autostart on installs a LaunchAgent for your user that runs stagepass daemon at login. off removes it and status shows the state, with --json if you need it. The daemon never uses sudo. If port 443 is in use, it logs an error and exits. Run stagepass start to fix the conflict. stagepass stop reminds you when autostart is on.

$ stagepass autostart on
$ stagepass autostart status

stagepass new

Scaffolds a lean Webflow project with TypeScript and SCSS by default: a build script with content hashed files in dist/, Webflow head and footer snippets with the @2 pin, stagepass.json, AGENTS.md with the sp reference, an editor rule file and a .gitignore. The name must be DNS safe. Existing files are never overwritten.

$ stagepass new my-project --site www.example.com

stagepass build and watch

Run npm run build or npm run watch in the current project and pass on the exit code.

stagepass upgrade

Updates @stagepass/* in package.json, finds out which modules your site loads and syncs stagepass.json, the managed block in AGENTS.md, the editor rule file and compilerOptions.types. Your own text stays. Every change is printed. npm install is printed, not run. The Webflow snippets use the @2 pin.

$ stagepass upgrade --dry-run

Declared modules

Projects from stagepass new or stagepass upgrade list in stagepass.json which modules the Webflow site loads: [] for the loader only, any of inject, cookies and maintenance, or ["all"].

{ "name": "my-project", "modules": ["cookies"] }

From this list the CLI generates the sp reference in AGENTS.md between <!-- stagepass:begin --> and <!-- stagepass:end -->, the editor rule file and the types in tsconfig.json, so a module the site does not load is a type error:

{ "compilerOptions": { "types": ["@stagepass/loader", "@stagepass/modules/cookies"] } }

To read the list, the CLI fetches the live site once: https only, no cookies, nothing is executed. It only recognises loader and module tags on public npm CDN URLs. For self-hosted files, pass --site-modules. stagepass doctor warns when the list and the live site differ.

Files

Stagepass keeps its state in ~/.stagepass/: Caddyfile for the local sites, projects.json for per-project settings and server.log for the server output. In a project folder, stagepass.json lists the declared modules.

Per-domain settings live in ~/.stagepass/projects.json:

{
  "version": 1,
  "projects": {
    "my-project.sp": {
      "root": "/Users/you/Sites/my-project",
      "origins": ["www.example.com"],
      "allowAllOrigins": false
    }
  }
}

More on what the server blocks and which origins it allows: Security and CORS.