frappe-setup-cli

v1.0.1

Published

13 days ago

One-command, guided and verified Frappe Framework / ERPNext development environment installer (launches the bundled Python installer)

0High
0Medium
0Low

ajaybaskers

frappe erpnext bench installer cli setup

Frappe Setup CLI

One command to get a working, verified Frappe Framework development environment.

npx frappe-setup-cli

That's it. The wizard checks your machine, installs what's missing (it asks before using sudo), creates the bench and site, installs the apps you picked, and checks that the site actually answers in a browser. At the end it prints the exact commands to start working:

source ~/.local/share/frappe-setup/env/frappe-bench-<id>.sh   # path is printed by the installer
cd ~/frappe-projects/frappe-bench
bench start
# open http://localhost:8000  →  login: Administrator / the password you chose

npx frappe-setup-cli works once version 1.0.0 is published to the npm registry (see Release and publishing). Until then, or if you prefer git, use:
git clone https://github.com/ajaybasker/frappe-bench-setup.git
cd frappe-bench-setup
./install.sh
Both start the same installer and accept the same commands and options (./install.sh check = npx frappe-setup-cli check, and so on).
Before publication, npx frappe-setup-cli fails with npm error 404 Not Found, because the registry has no such package yet. To try the npm launcher from a checkout without publishing it:
npm pack                                                     # creates frappe-setup-cli-1.0.0.tgz
npx --package ./frappe-setup-cli-1.0.0.tgz frappe-setup-cli  # same as `npx frappe-setup-cli`

Three ways to run it

| Method | Command | When to use | |--------|---------|-------------| | npx (no install) | npx frappe-setup-cli | One-off setup; always uses the latest published version | | Global npm install | npm install -g frappe-setup-cli then frappe-setup-cli | You run it often (frappe-setup-cli status, doctor, resume) | | Git checkout | ./install.sh | Development of this tool, or machines without Node.js |

Every command shown below as ./install.sh <command> works the same as npx frappe-setup-cli <command> or frappe-setup-cli <command>. Messages from the installer name the command you actually used.

What the npm package needs vs. what Frappe needs

| | Needed before you start | Installed for you (with permission) | |---|---|---| | npm launcher | Linux, Node.js ≥ 18 with npm/npx, bash, Python ≥ 3.10 (preinstalled on Ubuntu 24.04 and 26.04) | python3-venv if missing (asks first) and a private Python environment for the installer in ~/.local/share/frappe-setup/npm-runtime/ | | Frappe itself | Ubuntu 24.04 or 26.04 x86_64, a regular user with sudo | build tools, MariaDB, Redis, a compatible Python, Node.js and Yarn for the bench, the Bench CLI — see Prerequisites |

The Node.js that runs npx is only used to launch the installer. The bench gets the Node.js version its Frappe branch requires (e.g. 24 for v16), installed in user space if your system Node.js doesn't fit; your system Node.js is never replaced.

What it does

| Step | What happens | Changes your system? | |------|--------------|----------------------| | System check | OS, CPU, RAM, disk, Python, pip, Node.js, npm, Yarn, MariaDB/PostgreSQL, Redis, build tools, existing benches, sudo, ports | No | | Version resolution | Verifies the Frappe branch and every app branch against the real GitHub repositories and reads their actual requirements (requires-python, engines.node, app dependencies) | No | | Dependencies | Installs only what is missing or incompatible, shows every sudo command first | Yes, after you confirm | | Database | Checks the superuser login; on a fresh MariaDB it can enable password login for root (socket login keeps working) | Only if you confirm | | Bench | bench init with the chosen branch and a compatible Python, then validates the result | Creates the bench folder | | Apps | bench get-app in dependency order (e.g. ERPNext before HRMS) | Adds apps to the bench | | Site | bench new-site, installs the apps, enables developer mode, makes it the default site | Creates the site and its database | | Verification | Starts the bench briefly and checks /api/method/ping answers pong | No lasting change |

Design rules: nothing is overwritten or deleted, system Python and system Node.js are never replaced, passwords never appear on the command line or in logs, and every step can be safely rerun.

Supported environments

| Platform | Status | |----------|--------| | Ubuntu 24.04 LTS, x86_64 | Supported (see verified results) | | Ubuntu 26.04 LTS, x86_64 | Supported (see verified results); wkhtmltopdf is not packaged there | | Ubuntu 24.04 / 26.04 aarch64, Debian 12/13 | In the matrix but untested — refused unless --allow-untested-platform | | Anything else (other distros, macOS, WSL1, Ubuntu ≤ 22.04, interim releases such as 25.10) | Not supported — use an Ubuntu 24.04 or 26.04 VM/container |

| Frappe branch | Python | Node.js | MariaDB | Redis | Source | |---------------|--------|---------|---------|-------|--------| | version-15 | ≥3.10, <3.15 | ≥18 | ≥10.6.6 | ≥6 | docs.frappe.io + upstream pyproject.toml/package.json | | version-16 | 3.14 | ≥24 | 11.8 | ≥6 | same | | develop (v17 pre-release) | 3.14 | ≥24 | 11.8 | ≥6 | same |

These are read live from the branch at install time; config/version-matrix.yaml keeps the documented values, the versions upstream CI uses, what this tool installs, and — separately — what this project has actually tested.

Resources: at least 2 GB RAM (4 GB RAM+swap recommended), 4 GB free disk for Frappe alone, about 2 GB more per large app such as ERPNext.

Prerequisites

Ubuntu 24.04 or 26.04 (x86_64) with a regular user that can use sudo (do not run as root).
python3 ≥ 3.10 (preinstalled on Ubuntu) and an internet connection (GitHub, PyPI, npm registry, nodejs.org, Ubuntu mirrors).
For npx / npm install -g: Node.js ≥ 18 with npm. For the git method: git.

Everything else (build tools, MariaDB, Redis, a compatible Python, Node.js, Yarn, Bench CLI) is detected and installed for you if needed.

The wizard, step by step

╔══════════════════════════════════════════════╗
║               FRAPPE SETUP CLI               ║
║  Guided Development Environment Installer    ║
╚══════════════════════════════════════════════╝

Step 1/10: System compatibility       what's installed, which Frappe versions are feasible here
Step 2/10: Installation directory     default ~/frappe-projects
Step 3/10: Bench configuration        default frappe-bench; detects existing benches
Step 4/10: Frappe version             version-15 / version-16 / develop
Step 5/10: Site configuration         site name, database, passwords (hidden input), developer mode
Step 6/10: Applications               none / ERPNext / official apps / custom Git URLs
Step 7/10: Review                     summary; nothing has been changed yet
Step 8/10: Dependency installation    shows the plan and every sudo command, asks first
Step 9/10: Bench and site provisioning
Step 10/10: Environment verification  starts the bench, pings the site, prints how to start

Press Enter to accept a default. Ctrl-C at any point stops safely; continue later with ./install.sh resume.

Beginner example — accept every default:

Parent directory for the bench [~/frappe-projects]:  ⏎
Bench name [frappe-bench]:                           ⏎
Frappe version [1]:                                  ⏎   (version-15)
Site name [dev.localhost]:                           ⏎
Database engine [1]:                                 ⏎   (MariaDB)
Database superuser [root]:                           ⏎
root password (existing password, or a new one to set if MariaDB is fresh): ********
Administrator password for the new site: ********
Enable developer mode on the site? [Y/n]:            ⏎
Applications [1]:                                    2   (Frappe + ERPNext)
Start the installation? [Y/n]:                       ⏎

Choosing a Frappe version

version-15 — mature stable release; works with Ubuntu 24.04's own Python 3.12, Node 18+ and MariaDB 10.11, and with Ubuntu 26.04's own Python 3.14 and MariaDB 11.8.
version-16 — current stable release; needs Python 3.14, Node 24 and MariaDB 11.8. The installer gets Python 3.14 via uv and Node 24 from nodejs.org in your home directory. On Ubuntu 24.04 without MariaDB it uses the official MariaDB 11.8 repository (key fingerprint verified). Ubuntu 26.04 already ships Python 3.14 and MariaDB 11.8, so its own packages are used. If an older MariaDB is already installed, it stops and explains your options instead of upgrading your database server.
develop — unstable pre-release; may break at any time.

The installer verifies the branch exists upstream and never silently switches to another one.

Bench and site configuration

| Setting | Default | Notes | |---------|---------|-------| | Parent directory | ~/frappe-projects | ~ expanded; system folders (/etc, /usr, /var, …) refused | | Bench name | frappe-bench | letters, digits, -, _; bench path = parent/name | | Site name | dev.localhost | *.localhost works in browsers without editing /etc/hosts | | Database | MariaDB on 127.0.0.1:3306, user root | PostgreSQL is experimental (existing server only) | | Developer mode | on | --no-developer-mode to disable | | Default site | yes | so http://localhost:8000 serves it |

Existing things are handled safely:

Existing bench at the target path → reused after compatibility checks (branch and Python must match), never re-initialised.
Existing site with the same name → reused, never recreated or dropped; only missing apps are installed.
A folder that is not a bench → refused; pick another name.
A half-created bench from an interrupted run → you choose: rename it aside (default), delete it, or stop.

ERPNext, official and custom apps

In the wizard pick one of: Frappe only · Frappe + ERPNext · Frappe + selected official apps · Frappe + custom Git URLs.

Official apps offered (repository URLs only; branches are resolved live): ERPNext, Frappe HR (hrms), Payments, CRM, Helpdesk, Telephony, Learning (lms), Education, Wiki, Builder, Insights, Drive, Print Designer — see config/app-catalog.yaml.

Before anything long-running, each app is checked:

the branch exists (default: same name as the Frappe branch, e.g. version-15; if the app has no such branch you are asked to pick one — nothing is guessed);
the app's declared Frappe range ([tool.bench.frappe-dependencies]) matches your Frappe version;
its required_apps (read from the app's hooks.py) are selected too — e.g. Education → ERPNext, HRMS → ERPNext, Helpdesk → Telephony, LMS → Payments. Chains are followed (a required app's own requirements are checked too) and apps already in the bench count as present;
install order is sorted so dependencies come first.

When something does not fit, the wizard asks instead of stopping:

| Situation | Interactive wizard | --non-interactive | |-----------|--------------------|---------------------| | An app needs an official app you did not select (Education → ERPNext) | Add ERPNext (erpnext) … and install it before education? [Y/n] | Stops before any change: add --app erpnext … or rerun with --yes; with --yes it is added automatically | | An app needs an app that is not in the catalog | Uses the repository named in hooks.py (org/repo → GitHub) and asks; otherwise asks for its Git URL | Stops with --app-url <Git URL of …>; unknown repositories are never guessed | | The branch you typed does not exist | Shows the repository's branches to pick from (or type another) | Stops and lists the available branches | | The app has no branch named like your Frappe branch | Asks which branch to use | Stops: pass --app NAME@BRANCH | | The app's branch declares another Frappe version | Offers another branch, or skip | Stops and explains | | The repository cannot be reached / does not exist | Try again · enter a different URL · skip · cancel | Stops with the git error | | A MariaDB-only app (ERPNext, HRMS, Education) on PostgreSQL | Skip it · cancel | Stops and explains | | You decline a required app | Skip only the app that needs it · cancel | — |

All of this happens before anything is installed. Answers like maybe are rejected and asked again, and at "Add custom apps by Git URL as well?" you can paste the URL directly.

Custom apps: give an https:// or SSH URL and a branch/tag. Private repos work with an SSH key or a git credential helper; URLs with embedded tokens are refused (they'd end up in .git/config and logs).

After installation: everyday Bench commands

Always start a new terminal with the generated environment script so the right Node.js/Yarn/Bench are used:

source ~/.local/share/frappe-setup/env/frappe-bench-<id>.sh   # path shown at the end of install / in `status`
cd ~/frappe-projects/frappe-bench

(You may add that source line to ~/.bashrc; the installer does not edit your shell files.)

Run and develop

| Command | What it does | |---------|--------------| | bench start | Start web server, workers, Redis, socket.io and the asset watcher (Ctrl-C stops) | | bench --site dev.localhost console | Python console inside the site | | bench --site dev.localhost mariadb | SQL shell on the site database | | bench build / bench build --app erpnext | Rebuild frontend assets | | bench --site dev.localhost clear-cache | Clear the site cache | | bench --site dev.localhost migrate | Apply schema changes / patches after pulling code | | bench new-app my_app | Scaffold a new custom app in apps/ | | bench version | Show versions of all apps in the bench |

Sites

| Command | What it does | |---------|--------------| | bench new-site site2.localhost | Create another site (prompts for DB root and Administrator passwords) | | bench use site2.localhost | Make a site the default | | bench --site dev.localhost list-apps | Apps installed on a site | | bench --site dev.localhost set-config developer_mode 1 | Set a site config value | | bench --site dev.localhost backup --with-files | Backup to sites/dev.localhost/private/backups | | bench --site dev.localhost restore <file.sql.gz> | Restore a backup | | bench drop-site site2.localhost | Remove a site (moves it to archived_sites, drops the DB — careful) |

Apps

| Command | What it does | |---------|--------------| | bench get-app --branch version-15 https://github.com/frappe/hrms | Download an app into the bench | | bench --site dev.localhost install-app hrms | Install it on a site (keep bench start running in another terminal: apps such as ERPNext need the bench's Redis) | | bench --site dev.localhost uninstall-app hrms | Remove it from a site (deletes its data) | | bench update | Pull all apps, migrate all sites, rebuild — do this deliberately, after a backup |

Or simply rerun ./install.sh with more apps selected: existing bench and site are reused and only the new apps are added.

All frappe-setup commands

Run them via ./install.sh <command> or directly as .venv/bin/frappe-setup <command>.

| Command | Purpose | Modifies the system? | |---------|---------|----------------------| | ./install.sh | Interactive wizard (same as install) | after confirmation | | ./install.sh check | Compatibility report for all branches (-b version-16 for one, --json, --offline) | no | | ./install.sh install | Wizard; or fully scripted with --non-interactive | after confirmation / --yes | | ./install.sh status | Known benches/sites, phase status of past runs, start command (--json) | no | | ./install.sh doctor | Diagnose services, bench, site, PATH, last failure; --share report.json writes a redacted report | no | | ./install.sh resume | Continue the last unfinished installation (asks for passwords again) | after confirmation | | ./install.sh logs | Show the latest log (--list, --show FILE, -n 200, --path) — secrets redacted | no |

npm package details

frappe-setup-cli on npm is a thin launcher around the same Python installer that ./install.sh runs; it contains no installation logic of its own and has no npm dependencies.

What happens when you run npx frappe-setup-cli [command] [options]:

The launcher (bin/frappe-setup-cli.js) prints its version, platform and Python version (to stderr, so check --json output stays clean), and checks: Linux, Node.js ≥ 18, bash, Python ≥ 3.10, and that the package files are complete. If something is missing it explains how to fix it and stops — nothing is changed.
It runs the bundled install.sh with bash, passing your arguments unchanged (as an argument list, never through a shell), in your current directory (so relative paths such as --config ./my.yaml work).
install.sh creates (once) a private Python environment in ~/.local/share/frappe-setup/npm-runtime/venv — not inside the npm package, which may be read-only (global installs) or cleaned up (npx cache) — and reinstalls it automatically when a new package version arrives.
The Python installer runs with your terminal attached: the wizard, hidden password prompts and progress work exactly as with ./install.sh. Ctrl+C reaches the installer, which stops safely and tells you how to resume.
The launcher exits with the installer's exit code (0 success, 1 failure, 2 invalid input, 130 interrupted).

Installing globally instead of using npx:

npm install -g frappe-setup-cli     # or, without root: npm install -g --prefix ~/.local frappe-setup-cli
frappe-setup-cli                     # wizard
frappe-setup-cli status              # same commands as ./install.sh
npm uninstall -g frappe-setup-cli    # remove the launcher
rm -rf ~/.local/share/frappe-setup/npm-runtime   # optional: remove its Python environment

Uninstalling the launcher never touches your benches, sites or databases.

The package contains only: the launcher (bin/, lib/), install.sh, the Python sources (src/frappe_setup/*.py), pyproject.toml, config/*.yaml, documentation and the license. No tests, virtualenvs, caches, logs or secrets.

Non-interactive / advanced usage

All wizard answers are available as flags; passwords only via files (mode 600) or environment variables.

umask 077
printf '%s' 'Admin-password-here' > ~/.frappe-admin.pw
printf '%s' 'MariaDB-root-password' > ~/.frappe-db.pw

./install.sh install --non-interactive --yes \
  --frappe-branch version-15 \
  --parent-dir ~/frappe-projects --bench-name erp-bench \
  --site erp.localhost \
  --app erpnext --app hrms \
  --app-url [email protected]:my-org/my_custom_app.git@develop \
  --admin-password-file ~/.frappe-admin.pw \
  --db-root-password-file ~/.frappe-db.pw

Useful flags: --db-host/--db-port/--db-root-user, --db-engine postgres, --no-developer-mode, --no-set-default, --no-verify-http, --wkhtmltopdf (PDF printing), --backups, --reuse-existing-bench, --cleanup quarantine|delete|abort, --verbose. Environment variables FRAPPE_SETUP_ADMIN_PASSWORD / FRAPPE_SETUP_DB_ROOT_PASSWORD work instead of the files. Safety overrides (use knowingly): --allow-untested-platform, --allow-db-version-mismatch, --allow-root (disposable containers only).

A YAML file can hold the non-secret settings — see config/example-install.yaml:

./install.sh install --config my-setup.yaml --admin-password-file ~/.frappe-admin.pw

--yes pre-authorizes the displayed sudo commands. Without cached sudo credentials a non-interactive run stops and tells you to run sudo -v first.

Logs, resume and recovery

Logs: ~/.local/state/frappe-setup/logs/ (one file per run, mode 600, secrets masked). Every error shows its log path.
Run state: ~/.local/state/frappe-setup/runs/ (configuration and phase status — never passwords).
Managed runtimes and env scripts: ~/.local/share/frappe-setup/; Python/Bench via uv in ~/.local/share/uv, ~/.local/bin/bench.

Every failure reports the phase, the command (redacted), the exit code, the log file, the likely cause (when the output shows it), a fix, and whether retrying is safe.

Interrupted or failed? Fix the cause and run ./install.sh resume. Each step re-checks the real state first, so finished work (packages, bench, site, apps) is reused, not repeated or duplicated.

Troubleshooting

See docs/troubleshooting.md. The quickest checks:

./install.sh doctor          # what is wrong and how to fix it
./install.sh logs -n 150     # the end of the last log

Security

Summary (details in docs/security.md): no password flags; secrets reach Frappe through its own hidden prompts; logs/state/reports are redacted; all commands run without a shell; sudo commands are shown and confirmed; Git URLs are validated; existing benches, sites, databases and files are never deleted or overwritten; nothing disables firewalls or database authentication. Developer mode is a development-only setting — don't expose this bench to untrusted networks.

Development and testing

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                         # unit tests (mocked system commands, safe on any machine)
.venv/bin/ruff check src tests && .venv/bin/ruff format --check src tests
.venv/bin/mypy
FRAPPE_SETUP_NETWORK_TESTS=1 .venv/bin/pytest -m network      # read-only checks against GitHub
tests/integration/run_e2e.sh version-15                      # full install in a disposable Docker container
tests/integration/run_e2e.sh version-16 --erpnext

npm test                                                      # npm launcher tests (fake installer; no changes made)
npm run test:pack                                             # npm pack -> global install + npx from the tarball (isolated HOME)
E2E_VIA=npx tests/integration/run_e2e.sh version-15 --erpnext   # full install via npx on a clean container

On networks that block some plain-HTTP Ubuntu downloads, prefix the Docker tests with E2E_APT_MIRROR=https://mirrors.edge.kernel.org/ubuntu.

The end-to-end script builds a clean Ubuntu 24.04 image, runs ./install.sh as a non-root sudo user, checks status/doctor, reruns the install to prove idempotency, and scans all logs/state/output for the passwords. It never touches the host. Project layout: docs/architecture.md.

Test results

Unit tests (executed): 345 Python tests passed, 1 skipped (the opt-in network test); 17 npm launcher tests passed (npm test); npm run test:pack (tarball → global install + npx, isolated HOME) passed. ruff and mypy clean.

End-to-end (executed, 2026-10-23, clean Ubuntu 24.04.5 x86_64 Docker container, non-root sudo user):

| Frappe | Apps | Runtimes used | Result | |--------|------|---------------|--------| | version-16 (16.53.0) | frappe | Python 3.14.9 (uv), Node 24.22.1, MariaDB 11.8.9 (official repo) | PASS — fresh install 6 min 17 s, site answered /api/method/ping, rerun reused everything (15 s), no passwords in logs/state/output | | version-15 (15.124.0) | frappe + ERPNext 15.124.1 | Python 3.12.3 (Ubuntu), Node 20.20.2, MariaDB 10.11.14 (Ubuntu) | PASS — fresh one-command install 6 min 7 s, ERPNext installed on the site, ping OK, rerun reused everything (19 s), no passwords leaked | | version-15 (15.124.0) | frappe + ERPNext (version-15) — via npx from the packed npm tarball (only the tarball and Node.js 20.20.2 copied into the container, no git checkout) | Python 3.12.3 (Ubuntu), Node 20.20.2, MariaDB 10.11.14 (Ubuntu) | PASS — fresh install 6 min 33 s, ERPNext installed, ping OK, status/doctor via npx, rerun reused everything (27 s), no passwords in logs/state/npm cache/runtime venv | | version-15 (15.124.0) | frappe | Python 3.12.3 (Ubuntu), Node 20.20.2, MariaDB 10.11.14 (Ubuntu) | PASS via resume — the first run exposed a Yarn-detection bug (fixed + regression test); resume then completed, ping OK, rerun 20 s, doctor clean, no passwords leaked |

End-to-end (executed, 2026-10-23, clean Ubuntu 26.04.1 LTS x86_64 Docker container, non-root sudo user):

| Frappe | Apps | Runtimes used | Result | |--------|------|---------------|--------| | version-16 (16.53.0) | frappe | Python 3.14.4 (Ubuntu), Node 24.22.1, MariaDB 11.8.6 (Ubuntu — no external repo needed) | PASS — fresh install 8 min 48 s, ping OK, status/doctor OK, rerun reused everything (45 s), no passwords leaked | | version-16 (16.53.0) | only --app education selected → ERPNext added automatically as its required app (--yes), installed before Education | Python 3.14.4 (Ubuntu), Node 24.22.1, MariaDB 11.8.6 (Ubuntu) | PASS — fresh install 7 min 41 s, erpnext and education installed on the site, ping OK, rerun reused everything (26 s), no passwords leaked | | version-15 (15.124.0) | frappe + ERPNext (version-15) | Python 3.14.4 (Ubuntu), Node 20.20.2, MariaDB 11.8.6 (Ubuntu) | PASS — fresh one-command install 15 min 21 s, ERPNext installed on the site, ping OK, rerun reused everything (40 s), no passwords leaked |

Also executed: the interactive wizard through a real terminal (PTY) on a provisioned Ubuntu 24.04 machine, up to the final confirmation (declined → nothing changed); check against live upstream branches.

Not yet verified: a physical/VM Ubuntu (24.04 or 26.04) with systemd, the npm launcher on 26.04, --wkhtmltopdf on 26.04 (not packaged there), the develop branch, PostgreSQL, --wkhtmltopdf, Debian/aarch64. See docs/supported-platforms.md.

Known limitations

Only Ubuntu 24.04 and 26.04 x86_64 are tested. Other platforms are refused by default.
Ubuntu 26.04 no longer packages wkhtmltopdf: --wkhtmltopdf stops with instructions there (install the patched-Qt build from https://github.com/wkhtmltopdf/packaging/releases yourself).
Development setups only — no production setup (nginx, supervisor, TLS).
PostgreSQL: experimental, Frappe-only, requires an existing server; not tested end-to-end.
An already-installed MariaDB older than the branch requires (e.g. 10.11 for v16) is not upgraded.
wkhtmltopdf from Ubuntu is built without patched Qt (some PDF features differ).
Default Bench ports (8000, 9000, 11000, 13000) are shared with other benches on the machine; only one can run at a time unless you change ports.
The managed Node.js/Yarn are only on PATH after source-ing the generated env script.

Contributing

Open an issue describing the problem or platform you want to support.
Keep changes covered by unit tests (pytest), and run ruff and mypy.
For a new platform or Frappe branch: update config/version-matrix.yaml with sources, run tests/integration/run_e2e.sh on that platform, and add the result to the tested section only after it passes.
Never add flags that take secrets as arguments, and never add shell=True.

License: MIT (see LICENSE).

Release and publishing

Publishing is always a manual, human decision; no script in this repository publishes anything.

Bump the version in both package.json and pyproject.toml/src/frappe_setup/__init__.py (npm test fails if they differ), and update the test results above.

Run every check:

.venv/bin/pytest && .venv/bin/ruff check src tests && .venv/bin/mypy
npm test
npm run test:pack
E2E_VIA=npx tests/integration/run_e2e.sh version-15 --erpnext
tests/integration/run_e2e.sh version-16

Inspect what will be published:

npm pkg get name version bin files engines
npm pack --dry-run
npm view frappe-setup-cli          # "404 Not Found" = the name is still free; otherwise check ownership

npm login
npm whoami
npm publish --dry-run              # final check of the exact upload
npm publish --access public        # irreversible for this version number

Verify from a clean shell: npx [email protected] --version and npx frappe-setup-cli check.
Tag the release: git tag v1.0.0 && git push origin v1.0.0.

A published version can be deprecated (npm deprecate) but not replaced; fix mistakes with a new version.