From eb125eaffbd5873cc47b8f6e7de0c3662482bd7d Mon Sep 17 00:00:00 2001 From: Alessandro Digilio Date: Fri, 11 Sep 2026 22:29:34 +0200 Subject: [PATCH 1/5] docs: add concise tagged install commands --- README.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 214 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3336f8d..264cc8f 120000 --- a/README.md +++ b/README.md @@ -1 +1,214 @@ -README.en.md \ No newline at end of file +# Nginx Proxy Manager SSL CLI + +English | [Italiano](README.it.md) + +[![CI](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/actions/workflows/tests.yml) +[![Latest release](https://img.shields.io/github/v/release/alsd4git/nginx-proxy-manager-ssl-cli)](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases) +[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE) + +Inspect and update security settings for proxy hosts in +[Nginx Proxy Manager](https://github.com/NginxProxyManager/nginx-proxy-manager). +The package and executable retain the historical name `npm-ssl-updater`. + +## Requirements + +- Node.js 20 or newer +- a reachable Nginx Proxy Manager instance +- Nginx Proxy Manager administrator credentials + +## Installation + +Run a tagged version directly from GitHub without cloning the repository: + +```bash +npx -y github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 --help +``` + +Or install that tagged version globally: + +```bash +npm install -g github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 +npm-ssl-updater --help +``` + +GitHub Releases also contain the exact `npm pack` tarball for each version. This +is useful when you want to install the published release artifact itself: + +```bash +npm install -g https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases/download/v1.0.0/npm-ssl-updater-1.0.0.tgz +``` + +The examples are intentionally pinned to a tag. Replace `v1.0.0` with the +version you want instead of relying on the current default branch. + +For development from a checkout: + +```bash +git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git +cd nginx-proxy-manager-ssl-cli +npm ci +npm start -- --help +``` + +## Credentials + +Create `.env` in the directory where you run the command: + +```dotenv +NPM_HOST=http://localhost:81 +NPM_EMAIL=admin@example.com +NPM_PASSWORD=change-me +``` + +Command-line flags override environment variables. Prefer `.env` or +`--password-stdin` over `--password`, because process arguments may appear in +shell history and process listings. + +```bash +printf '%s\n' "$NPM_PASSWORD" | npm-ssl-updater \ + --host http://localhost:81 \ + --email admin@example.com \ + --password-stdin \ + --dry-run +``` + +`--password-stdin` reads exactly one newline-terminated password. It does not +open an interactive password prompt. + +Never commit `.env` or paste credentials into logs, issues, or screenshots. + +## Common operations + +List proxy hosts without changing them: + +```bash +npm-ssl-updater +``` + +Preview proposed changes: + +```bash +npm-ssl-updater --block-exploits --enable-websockets --dry-run +``` + +Apply every proposed change without interactive prompts: + +```bash +npm-ssl-updater --block-exploits --enable-websockets --yes +``` + +For an interactive review, store the credentials in `.env` and run: + +```bash +npm-ssl-updater \ + --hsts-subdomains \ + --cache-assets \ + --block-exploits \ + --enable-websockets \ + --request-timeout 15000 +``` + +Interactive confirmation requires a terminal. A command using +`--password-stdin` must also use `--yes` or `--dry-run`, because piped stdin is +not a TTY: + +```bash +printf '%s\n' "$NPM_PASSWORD" | npm-ssl-updater \ + --host http://localhost:81 \ + --email admin@example.com \ + --password-stdin \ + --block-exploits \ + --enable-websockets \ + --yes +``` + +The security switches include Force SSL, HTTP/2, HSTS, HSTS subdomains, asset +caching, common-exploit blocking, and WebSocket support. Run +`npm-ssl-updater --help` for the complete option list and aliases. + +`npm-ssl-updater --print-advanced` only prints each host's current +`advanced_config`. It does not assess or update the security fields in that +run. + +## Certificates and access lists + +```bash +npm-ssl-updater --list-certificates +npm-ssl-updater --list-access-lists +``` + +These commands are read-only and help locate IDs or named access lists for +automation. + +## Create or update a proxy host + +```bash +npm-ssl-updater \ + --upsert-proxy-host \ + --proxy-domain app.example.com \ + --proxy-forward-host app \ + --proxy-forward-port 3000 \ + --proxy-access-list-name local-only \ + --proxy-advanced-config-file ./media/NPM-extraconf.conf \ + --proxy-dry-run +``` + +The helper looks up a matching exact or wildcard certificate unless +`--proxy-certificate-id` overrides it. Remove `--proxy-dry-run` only after +reviewing the generated operation. + +## Update one advanced configuration + +```bash +npm-ssl-updater \ + --advanced-config-host-id 36 \ + --advanced-config-file ./media/NPM-extraconf.conf \ + --advanced-config-dry-run +``` + +This path sends a minimal payload for one host. It avoids resending unrelated +proxy fields when only `advanced_config` must change. + +## Block-exploits exception + +The tool leaves `block_exploits` disabled for Tinyauth hosts because that option +can break the forwarded host and query parameters used by Tinyauth. Other hosts +follow the requested setting. + +## Example output + +```text +Proxy: example.duckdns.org + - ssl_forced no -> yes + - http2_support no -> yes + - allow_websocket_upgrade no -> yes +Apply changes? ([y]es / [n]o / [a]ll): y + Change applied. + +Completed. Updated 1 host(s). +``` + +This is the format printed by the script. It lists only fields whose values +would change. Fields that already match the requested state are omitted. A +fully compliant host is reported as `Already compliant: example.duckdns.org`. +With `--dry-run`, the prompt and update message are replaced by +`Dry-run mode: no changes applied.` + +## Development + +```bash +npm ci +npm test +npm pack --dry-run +``` + +CI runs the test suite on current supported Node.js release lines. Releases +attach the packed npm tarball to GitHub and do not publish it to the npm +registry. + +See [CHANGELOG.md](CHANGELOG.md) and +[GitHub releases](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases). + +## License + +MIT. See [LICENSE](LICENSE). From edb44b91e0003c7b807cf97a9b50bae482fab68d Mon Sep 17 00:00:00 2001 From: Alessandro Digilio Date: Fri, 11 Sep 2026 22:29:50 +0200 Subject: [PATCH 2/5] docs: add concise tagged install commands (it) --- README.it.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/README.it.md b/README.it.md index 20bf77c..ecb7acb 100644 --- a/README.it.md +++ b/README.it.md @@ -18,20 +18,38 @@ Il pacchetto e il comando mantengono il nome storico `npm-ssl-updater`. ## Installazione +Esegui direttamente una versione taggata da GitHub, senza clonare la repository: + ```bash -git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git -cd nginx-proxy-manager-ssl-cli -npm ci +npx -y github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 --help ``` -Esegui il tool dal checkout con `npm start --`, oppure installa il comando -globalmente: +Oppure installa globalmente la stessa versione: ```bash -npm install -g . +npm install -g github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 npm-ssl-updater --help ``` +Le GitHub Release contengono anche il tarball esatto prodotto da `npm pack`, +utile se vuoi installare direttamente l'artefatto pubblicato: + +```bash +npm install -g https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases/download/v1.0.0/npm-ssl-updater-1.0.0.tgz +``` + +Gli esempi sono intenzionalmente bloccati a un tag. Sostituisci `v1.0.0` con la +versione desiderata invece di affidarti al branch di default corrente. + +Per lo sviluppo da checkout: + +```bash +git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git +cd nginx-proxy-manager-ssl-cli +npm ci +npm start -- --help +``` + ## Credenziali Crea `.env` nella directory da cui esegui il comando: From 7a5564e80d88b39937f2f8fd898f3205367a2f8b Mon Sep 17 00:00:00 2001 From: Alessandro Digilio Date: Fri, 11 Sep 2026 22:29:57 +0200 Subject: [PATCH 3/5] ci: smoke-test packed npm artifact --- .github/workflows/release.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 552218e..4487e67 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,12 @@ jobs: - run: npm test - name: Build package run: npm pack + - name: Smoke-test packed artifact + run: | + PACKAGE_TGZ="$(ls ./*.tgz)" + PREFIX="$(mktemp -d)" + npm install --global --prefix "$PREFIX" "$PACKAGE_TGZ" + "$PREFIX/bin/npm-ssl-updater" --help - name: Create GitHub release env: GH_TOKEN: ${{ github.token }} From 849ec18e02ddae381472021a6e0bb28003802377 Mon Sep 17 00:00:00 2001 From: Alessandro Digilio Date: Fri, 11 Sep 2026 22:34:24 +0200 Subject: [PATCH 4/5] docs: add concise tagged install commands --- README.en.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/README.en.md b/README.en.md index 8077a81..264cc8f 100644 --- a/README.en.md +++ b/README.en.md @@ -18,19 +18,38 @@ The package and executable retain the historical name `npm-ssl-updater`. ## Installation +Run a tagged version directly from GitHub without cloning the repository: + ```bash -git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git -cd nginx-proxy-manager-ssl-cli -npm ci +npx -y github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 --help ``` -Run from the checkout with `npm start --`, or install the command globally: +Or install that tagged version globally: ```bash -npm install -g . +npm install -g github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 npm-ssl-updater --help ``` +GitHub Releases also contain the exact `npm pack` tarball for each version. This +is useful when you want to install the published release artifact itself: + +```bash +npm install -g https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases/download/v1.0.0/npm-ssl-updater-1.0.0.tgz +``` + +The examples are intentionally pinned to a tag. Replace `v1.0.0` with the +version you want instead of relying on the current default branch. + +For development from a checkout: + +```bash +git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git +cd nginx-proxy-manager-ssl-cli +npm ci +npm start -- --help +``` + ## Credentials Create `.env` in the directory where you run the command: From 0d6a5d4763735410d38a288dcb1b2c2748387dc7 Mon Sep 17 00:00:00 2001 From: Alessandro Digilio Date: Fri, 11 Sep 2026 22:34:29 +0200 Subject: [PATCH 5/5] fix: restore README symlink target --- README.md | 215 +----------------------------------------------------- 1 file changed, 1 insertion(+), 214 deletions(-) diff --git a/README.md b/README.md index 264cc8f..3336f8d 120000 --- a/README.md +++ b/README.md @@ -1,214 +1 @@ -# Nginx Proxy Manager SSL CLI - -English | [Italiano](README.it.md) - -[![CI](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/actions/workflows/tests.yml) -[![Latest release](https://img.shields.io/github/v/release/alsd4git/nginx-proxy-manager-ssl-cli)](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases) -[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE) - -Inspect and update security settings for proxy hosts in -[Nginx Proxy Manager](https://github.com/NginxProxyManager/nginx-proxy-manager). -The package and executable retain the historical name `npm-ssl-updater`. - -## Requirements - -- Node.js 20 or newer -- a reachable Nginx Proxy Manager instance -- Nginx Proxy Manager administrator credentials - -## Installation - -Run a tagged version directly from GitHub without cloning the repository: - -```bash -npx -y github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 --help -``` - -Or install that tagged version globally: - -```bash -npm install -g github:alsd4git/nginx-proxy-manager-ssl-cli#v1.0.0 -npm-ssl-updater --help -``` - -GitHub Releases also contain the exact `npm pack` tarball for each version. This -is useful when you want to install the published release artifact itself: - -```bash -npm install -g https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases/download/v1.0.0/npm-ssl-updater-1.0.0.tgz -``` - -The examples are intentionally pinned to a tag. Replace `v1.0.0` with the -version you want instead of relying on the current default branch. - -For development from a checkout: - -```bash -git clone https://github.com/alsd4git/nginx-proxy-manager-ssl-cli.git -cd nginx-proxy-manager-ssl-cli -npm ci -npm start -- --help -``` - -## Credentials - -Create `.env` in the directory where you run the command: - -```dotenv -NPM_HOST=http://localhost:81 -NPM_EMAIL=admin@example.com -NPM_PASSWORD=change-me -``` - -Command-line flags override environment variables. Prefer `.env` or -`--password-stdin` over `--password`, because process arguments may appear in -shell history and process listings. - -```bash -printf '%s\n' "$NPM_PASSWORD" | npm-ssl-updater \ - --host http://localhost:81 \ - --email admin@example.com \ - --password-stdin \ - --dry-run -``` - -`--password-stdin` reads exactly one newline-terminated password. It does not -open an interactive password prompt. - -Never commit `.env` or paste credentials into logs, issues, or screenshots. - -## Common operations - -List proxy hosts without changing them: - -```bash -npm-ssl-updater -``` - -Preview proposed changes: - -```bash -npm-ssl-updater --block-exploits --enable-websockets --dry-run -``` - -Apply every proposed change without interactive prompts: - -```bash -npm-ssl-updater --block-exploits --enable-websockets --yes -``` - -For an interactive review, store the credentials in `.env` and run: - -```bash -npm-ssl-updater \ - --hsts-subdomains \ - --cache-assets \ - --block-exploits \ - --enable-websockets \ - --request-timeout 15000 -``` - -Interactive confirmation requires a terminal. A command using -`--password-stdin` must also use `--yes` or `--dry-run`, because piped stdin is -not a TTY: - -```bash -printf '%s\n' "$NPM_PASSWORD" | npm-ssl-updater \ - --host http://localhost:81 \ - --email admin@example.com \ - --password-stdin \ - --block-exploits \ - --enable-websockets \ - --yes -``` - -The security switches include Force SSL, HTTP/2, HSTS, HSTS subdomains, asset -caching, common-exploit blocking, and WebSocket support. Run -`npm-ssl-updater --help` for the complete option list and aliases. - -`npm-ssl-updater --print-advanced` only prints each host's current -`advanced_config`. It does not assess or update the security fields in that -run. - -## Certificates and access lists - -```bash -npm-ssl-updater --list-certificates -npm-ssl-updater --list-access-lists -``` - -These commands are read-only and help locate IDs or named access lists for -automation. - -## Create or update a proxy host - -```bash -npm-ssl-updater \ - --upsert-proxy-host \ - --proxy-domain app.example.com \ - --proxy-forward-host app \ - --proxy-forward-port 3000 \ - --proxy-access-list-name local-only \ - --proxy-advanced-config-file ./media/NPM-extraconf.conf \ - --proxy-dry-run -``` - -The helper looks up a matching exact or wildcard certificate unless -`--proxy-certificate-id` overrides it. Remove `--proxy-dry-run` only after -reviewing the generated operation. - -## Update one advanced configuration - -```bash -npm-ssl-updater \ - --advanced-config-host-id 36 \ - --advanced-config-file ./media/NPM-extraconf.conf \ - --advanced-config-dry-run -``` - -This path sends a minimal payload for one host. It avoids resending unrelated -proxy fields when only `advanced_config` must change. - -## Block-exploits exception - -The tool leaves `block_exploits` disabled for Tinyauth hosts because that option -can break the forwarded host and query parameters used by Tinyauth. Other hosts -follow the requested setting. - -## Example output - -```text -Proxy: example.duckdns.org - - ssl_forced no -> yes - - http2_support no -> yes - - allow_websocket_upgrade no -> yes -Apply changes? ([y]es / [n]o / [a]ll): y - Change applied. - -Completed. Updated 1 host(s). -``` - -This is the format printed by the script. It lists only fields whose values -would change. Fields that already match the requested state are omitted. A -fully compliant host is reported as `Already compliant: example.duckdns.org`. -With `--dry-run`, the prompt and update message are replaced by -`Dry-run mode: no changes applied.` - -## Development - -```bash -npm ci -npm test -npm pack --dry-run -``` - -CI runs the test suite on current supported Node.js release lines. Releases -attach the packed npm tarball to GitHub and do not publish it to the npm -registry. - -See [CHANGELOG.md](CHANGELOG.md) and -[GitHub releases](https://github.com/alsd4git/nginx-proxy-manager-ssl-cli/releases). - -## License - -MIT. See [LICENSE](LICENSE). +README.en.md \ No newline at end of file