Skip to content

Replace dw.phar install instructions with the CLI 2.5.0 migration #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
rmcdaniel wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Replace dw.phar install instructions with the CLI 2.5.0 migration #457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6cf90f6
Replace dw.phar install instructions with the 2.5.0 migration
rmcdaniel Nov 4, 2026
d0f4ec9
Offer the macOS Intel CLI binary that 2.5.0 adds
rmcdaniel Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/polyglot/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ canonical `input` array.
| `dw debug workflow <workflow-id>` | Capture stuck-run diagnostics for one workflow: state, pending tasks, queue facts, failures, and compatibility metadata. | `--run-id`, global options, `--json` |
| `dw server:start-dev` | Serve an existing, configured Laravel project's HTTP application. Requires external PHP. | `--port`, `--host` (default `127.0.0.1`), `--db=sqlite\|mysql\|pgsql` |
| `dw watch workflow <workflow-id>` | Poll a workflow until terminal or until a configured polling limit. | `--run-id`, `--interval`, `--max-polls`, global options |
| `dw upgrade` | Replace the running standalone `dw` binary with a newer (or pinned) release. Refuses to rewrite Composer vendor, Homebrew cellar, and PHAR installs. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |
| `dw upgrade` | Replace the running standalone `dw` binary with a newer (or pinned) release. Refuses to rewrite Composer vendor and Homebrew cellar installs. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |

Use `server:info` when validating contract shape, `doctor` when explaining why
a CLI cannot talk to a server, and `debug workflow` when support needs one
Expand All @@ -84,9 +84,8 @@ interfaces. MySQL and PostgreSQL modes require project Compose services named
return nonzero. Compose services remain running when the HTTP process ends.

POSIX native binaries forward SIGINT and SIGTERM to the active child and wait
up to five seconds for its process group to stop. Source and PHAR installs
require PHP's `pcntl` and `posix` extensions for this forwarding. Windows uses
its console interruption behavior.
up to five seconds for its process group to stop. Windows uses its console
interruption behavior.

For a standalone Durable Workflow Server using published images, follow the
[service quickstart](/docs/quickstart).
Expand Down Expand Up @@ -197,13 +196,14 @@ prose:
| `upgraded` | Binary replaced with `target_version`. |
| `noop` | `current_version` already matches `target_version`; `--force` bypasses this. |
| `dry-run` | `--dry-run` resolved `target_version`, `asset_url`, and `checksum_url` without downloading. |
| `refused` | Install kind is not a standalone release binary (Composer vendor, Homebrew cellar, or PHAR), or the platform has no published asset. |
| `refused` | Install kind is not a standalone release binary (Composer vendor or Homebrew cellar), or the platform has no published asset. |
| `permission-denied` | The install directory is not writable; the payload includes a `hint` with the recommended next step. |
| `error` | Release catalog fetch, checksum mismatch, or filesystem error. |

For refusals, the JSON payload's `installation.kind` identifies the managing
tool (`composer-vendor`, `homebrew`, `phar`, or `binary`) and `reason` names
the right owner to use instead. For public, source-free automation, reinstall
tool (`composer-vendor`, `homebrew`, `binary`, or `unknown`) and `reason` names
the right owner to use instead. Only a 2.x PHAR, running its own 2.x code,
reports `phar`. For public, source-free automation, reinstall
a pinned release through `https://durable-workflow.com/install.sh`; for
tap-managed Homebrew installs, use `brew upgrade durable-workflow/tap/dw`.

Expand Down
51 changes: 38 additions & 13 deletions docs/polyglot/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,21 +93,46 @@ that directory to the user `PATH`.
</details>

<details>
<summary><b>PHAR</b> (portable, requires PHP 8.2+)</summary>
<summary><b>Moving from <code>dw.phar</code></b></summary>

From CLI 2.5.0, releases ship no PHAR. If you run `php dw.phar`, switch to the
standalone binary, which needs no PHP, with the shell or PowerShell installer
above. Then delete `dw.phar`. The installers check the binary against the
release's `SHA256SUMS` before installing it.

If you don't pipe scripts into a shell, download the release and verify it
first. Pick your platform's asset: `dw-linux-x86_64`, `dw-linux-aarch64`,
`dw-macos-aarch64`, `dw-macos-x86_64` or `dw-windows-x86_64.exe`.

```bash
VERSION=<release-tag>
curl -fsSL -o dw.phar \
"https://github.com/durable-workflow/cli/releases/download/${VERSION}/dw.phar"
curl -fsSL -o SHA256SUMS \
"https://github.com/durable-workflow/cli/releases/download/${VERSION}/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
chmod +x dw.phar
./dw.phar --version
mkdir release
gh release download %%artifact.cliVersion%% --repo durable-workflow/cli --dir release
sh release/verify-release.sh --attest release/
install -m 0755 release/dw-linux-x86_64 ~/.local/bin/dw
```

On Windows, download, verify and copy without running a script:

```powershell
New-Item -ItemType Directory -Force release | Out-Null
gh release download %%artifact.cliVersion%% --repo durable-workflow/cli --dir release
$expected = ((Select-String -Path release\SHA256SUMS -Pattern ' dw-windows-x86_64\.exe$').Line -split '\s+')[0]
$actual = (Get-FileHash release\dw-windows-x86_64.exe -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected) { throw 'dw-windows-x86_64.exe does not match SHA256SUMS' }
gh attestation verify release\dw-windows-x86_64.exe --repo durable-workflow/cli --signer-workflow durable-workflow/cli/.github/workflows/release-rust.yml
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\dw" | Out-Null
Copy-Item release\dw-windows-x86_64.exe "$env:LOCALAPPDATA\Programs\dw\dw.exe"
```

The PHAR works wherever PHP 8.2 or newer is already available and is the
recommended artifact for shared CI runners that already ship PHP.
Add `%LOCALAPPDATA%\Programs\dw` to your `PATH` if it isn't there already.

In a 2.x PHAR install, `dw upgrade` still answers "Download the matching PHAR
manually". That message comes from the old release and can't be changed, so
use the commands above instead. Standalone-binary installs upgrade as usual
with `dw upgrade`.

On an Intel Mac, move from 2.x with the shell installer. Published 2.x
`dw upgrade` has no macOS x86_64 asset to move to.

</details>

Expand All @@ -123,8 +148,8 @@ dw upgrade --tag=<release-tag> # pin to a specific release tag
dw upgrade --dry-run # resolve the target release without downloading
```

`dw upgrade` refuses to rewrite Composer vendor, Homebrew cellar, and PHAR
installs because those paths are owned by another tool. Reinstall a pinned
`dw upgrade` refuses to rewrite Composer vendor and Homebrew cellar installs
because those paths are owned by another tool. Reinstall a pinned
public release with the installer, update the owning package manager, or use
`brew upgrade durable-workflow/tap/dw` for tap-managed Homebrew installs. See the
[CLI reference](./cli-reference.md#self-upgrade) for the full stable option
Expand Down
14 changes: 7 additions & 7 deletions i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ weiterhin das kanonische Array `input` erhält.
| `dw debug workflow <workflow-id>` | Diagnose eines festhängenden Workflow-Laufs erfassen: Zustand, ausstehende Tasks, Warteschlangenangaben, Fehler und Kompatibilitätsmetadaten. | `--run-id`, globale Optionen, `--json` |
| `dw server:start-dev` | HTTP-Anwendung eines bestehenden konfigurierten Laravel-Projekts bereitstellen. Benötigt externes PHP. | `--port`, `--host` (Standard `127.0.0.1`), `--db=sqlite\|mysql\|pgsql` |
| `dw watch workflow <workflow-id>` | Workflow bis zum terminalen Zustand oder bis zur konfigurierten Abfragegrenze beobachten. | `--run-id`, `--interval`, `--max-polls`, globale Optionen |
| `dw upgrade` | Laufende eigenständige `dw`-Binärdatei durch ein neueres oder festgelegtes Release ersetzen. Verweigert das Überschreiben von Composer-vendor-, Homebrew-cellar- und PHAR-Installationen. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |
| `dw upgrade` | Laufende eigenständige `dw`-Binärdatei durch ein neueres oder festgelegtes Release ersetzen. Verweigert das Überschreiben von Composer-vendor- und Homebrew-cellar-Installationen. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |

Verwenden Sie `server:info` zur Vertragsprüfung, `doctor` zur Erklärung von
CLI-Verbindungsproblemen und `debug workflow`, wenn Support eine maschinenlesbare
Expand All @@ -86,9 +86,8 @@ Compose-Dienste des Projekts namens `mysql` beziehungsweise `pgsql` sowie
ungleich null. Compose-Dienste laufen nach Ende des HTTP-Prozesses weiter.

Native POSIX-Binärdateien leiten SIGINT und SIGTERM an das aktive Kind weiter
und warten bis zu fünf Sekunden auf das Ende seiner Prozessgruppe.
Quellcode- und PHAR-Installationen benötigen dafür PHPs Erweiterungen `pcntl`
und `posix`. Windows verwendet sein Konsolen-Unterbrechungsverhalten.
und warten bis zu fünf Sekunden auf das Ende seiner Prozessgruppe. Windows
verwendet sein Konsolen-Unterbrechungsverhalten.

Für einen eigenständigen Durable Workflow Server mit veröffentlichten Images
folgen Sie dem [Service-Schnellstart](/docs/quickstart).
Expand Down Expand Up @@ -193,13 +192,14 @@ Prosaauswertung:
| `upgraded` | Binärdatei durch `target_version` ersetzt. |
| `noop` | `current_version` entspricht bereits `target_version`; `--force` umgeht dies. |
| `dry-run` | `--dry-run` hat `target_version`, `asset_url` und `checksum_url` ohne Download aufgelöst. |
| `refused` | Installation ist keine eigenständige Release-Binärdatei (Composer vendor, Homebrew cellar oder PHAR), oder für die Plattform ist kein Artefakt veröffentlicht. |
| `refused` | Installation ist keine eigenständige Release-Binärdatei (Composer vendor oder Homebrew cellar), oder für die Plattform ist kein Artefakt veröffentlicht. |
| `permission-denied` | Installationsverzeichnis nicht beschreibbar; die Nutzlast enthält einen `hint` mit empfohlenem nächsten Schritt. |
| `error` | Fehler beim Abruf des Release-Katalogs, abweichende Prüfsumme oder Dateisystemfehler. |

Bei Ablehnungen benennt `installation.kind` das verwaltende Werkzeug
(`composer-vendor`, `homebrew`, `phar` oder `binary`) und `reason` den richtigen
zuständigen Weg. Für öffentliche Automatisierung ohne Quellcode installieren
(`composer-vendor`, `homebrew`, `binary` oder `unknown`) und `reason` den richtigen
zuständigen Weg. Nur ein 2.x-PHAR, das seinen eigenen 2.x-Code ausführt, meldet
`phar`. Für öffentliche Automatisierung ohne Quellcode installieren
Sie ein festgelegtes Release über `https://durable-workflow.com/install.sh`
erneut. Für Tap-verwaltete Homebrew-Installationen verwenden Sie
`brew upgrade durable-workflow/tap/dw`.
Expand Down
55 changes: 42 additions & 13 deletions i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,21 +96,50 @@ Benutzer-`PATH`.
</details>

<details>
<summary><b>PHAR</b> (portabel, erfordert PHP 8.2+)</summary>
<summary><b>Umstieg von <code>dw.phar</code></b></summary>

Ab CLI 2.5.0 enthalten Releases kein PHAR mehr. Wenn Sie `php dw.phar`
ausführen, wechseln Sie mit der obigen Shell- oder PowerShell-Installation zur
eigenständigen Binärdatei, die kein PHP benötigt. Löschen Sie anschließend
`dw.phar`. Die Installationsskripte prüfen die Binärdatei vor der Installation
gegen die `SHA256SUMS` des Release.

Wenn Sie keine Skripte an eine Shell weiterleiten, laden Sie das Release
herunter und prüfen Sie es zuerst. Wählen Sie das Artefakt Ihrer Plattform:
`dw-linux-x86_64`, `dw-linux-aarch64`, `dw-macos-aarch64`, `dw-macos-x86_64` oder `dw-windows-x86_64.exe`.

```bash
VERSION=<release-tag>
curl -fsSL -o dw.phar \
"https://github.com/durable-workflow/cli/releases/download/${VERSION}/dw.phar"
curl -fsSL -o SHA256SUMS \
"https://github.com/durable-workflow/cli/releases/download/${VERSION}/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
chmod +x dw.phar
./dw.phar --version
mkdir release
gh release download %%artifact.cliVersion%% --repo durable-workflow/cli --dir release
sh release/verify-release.sh --attest release/
install -m 0755 release/dw-linux-x86_64 ~/.local/bin/dw
```

Unter Windows laden Sie herunter, prüfen und kopieren, ohne ein Skript
auszuführen:

```powershell
New-Item -ItemType Directory -Force release | Out-Null
gh release download %%artifact.cliVersion%% --repo durable-workflow/cli --dir release
$expected = ((Select-String -Path release\SHA256SUMS -Pattern ' dw-windows-x86_64\.exe$').Line -split '\s+')[0]
$actual = (Get-FileHash release\dw-windows-x86_64.exe -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected) { throw 'dw-windows-x86_64.exe does not match SHA256SUMS' }
gh attestation verify release\dw-windows-x86_64.exe --repo durable-workflow/cli --signer-workflow durable-workflow/cli/.github/workflows/release-rust.yml
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\dw" | Out-Null
Copy-Item release\dw-windows-x86_64.exe "$env:LOCALAPPDATA\Programs\dw\dw.exe"
```

Das PHAR funktioniert überall, wo PHP 8.2 oder neuer bereits verfügbar ist.
Es ist das empfohlene Artefakt für gemeinsame CI-Runner mit vorhandenem PHP.
Ergänzen Sie `%LOCALAPPDATA%\Programs\dw` in Ihrem `PATH`, falls es dort noch
nicht steht.

In einer 2.x-PHAR-Installation antwortet `dw upgrade` weiterhin mit "Download the
matching PHAR manually". Diese Meldung stammt aus dem alten Release und lässt
sich nicht ändern; verwenden Sie stattdessen die obigen Befehle. Installationen
der eigenständigen Binärdatei aktualisieren sich wie gewohnt mit `dw upgrade`.

Auf einem Intel-Mac wechseln Sie von 2.x mit der Shell-Installation. Das
veröffentlichte `dw upgrade` aus 2.x hat kein macOS-x86_64-Artefakt, zu dem es
wechseln könnte.

</details>

Expand All @@ -127,8 +156,8 @@ dw upgrade --tag=<release-tag> # pin to a specific release tag
dw upgrade --dry-run # resolve the target release without downloading
```

`dw upgrade` verweigert das Überschreiben von Composer-vendor-, Homebrew-cellar-
und PHAR-Installationen, da diese Pfade von anderen Werkzeugen verwaltet werden.
`dw upgrade` verweigert das Überschreiben von Composer-vendor- und
Homebrew-cellar-Installationen, da diese Pfade von anderen Werkzeugen verwaltet werden.
Installieren Sie ein festgelegtes öffentliches Release erneut mit dem
Installationsprogramm, aktualisieren Sie den zuständigen Paketmanager oder
verwenden Sie für Tap-verwaltete Homebrew-Installationen
Expand Down
4 changes: 2 additions & 2 deletions i18n/de/source-hashes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@
"polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a",
"polyglot/cancellation.md": "a08aca914d8211d32184fd76f14e4f8bf47d40656e55364923013e3cece3b70d",
"polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be",
"polyglot/cli-reference.md": "dc637af2ab17abc3f7e0233aeaacccc61dd1bbe7c94330e550a531ed1d8e48f8",
"polyglot/cli.mdx": "5c4b80e371705aaf37cb39eb9bc6375ca2496522dbeb161046707324190cef13",
"polyglot/cli-reference.md": "269039ffae9df115f2a2a5586b51c9ca8b273d193bfce427819e50fd2f64793a",
"polyglot/cli.mdx": "c0ab3a8f3f2568335b76cc57a890f5d60a93d6d3e78690aa2b4e74f35e08b42a",
"polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e",
"polyglot/deployment-modes.md": "7b508db4be86c92de76cfd8dfd946d93941c8a6f0a601a161d4d3fd1711bf97f",
"polyglot/embedded-to-server.md": "21a7e4c9439a73db3a97fd9b0610749faabf7c449806fe0ad55a0924f50d3b80",
Expand Down
8 changes: 4 additions & 4 deletions i18n/es/docusaurus-plugin-content-docs/current/polyglot/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ La entrada JSON de inicios de workflow, señales, consultas, actualizaciones, pr
| `dw debug workflow <workflow-id>` | Capturar diagnósticos de una ejecución atascada: estado, tareas pendientes, cola, fallos y compatibilidad. | `--run-id`, opciones globales, `--json` |
| `dw server:start-dev` | Servir la aplicación HTTP de un proyecto Laravel existente y configurado. Requiere PHP externo. | `--port`, `--host` (predeterminado `127.0.0.1`), `--db=sqlite\|mysql\|pgsql` |
| `dw watch workflow <workflow-id>` | Sondear hasta estado terminal o un límite configurado de sondeos. | `--run-id`, `--interval`, `--max-polls`, opciones globales |
| `dw upgrade` | Reemplazar el binario independiente actual de `dw` por otra publicación posterior o fijada. Rechaza modificar Composer vendor, Homebrew cellar y PHAR. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |
| `dw upgrade` | Reemplazar el binario independiente actual de `dw` por otra publicación posterior o fijada. Rechaza modificar Composer vendor y Homebrew cellar. | `--tag`, `--dry-run`, `--force`, `--output=table\|json` |

Utiliza `server:info` para validar estructuras de contrato, `doctor` para explicar por qué la CLI no se conecta y `debug workflow` si soporte necesita una captura de ejecución legible por máquinas.

Expand All @@ -64,7 +64,7 @@ Ejecuta `dw server:start-dev` desde el directorio de un proyecto Laravel instala

El comando utiliza loopback por defecto. Usa explícitamente `--host=0.0.0.0` para todas las interfaces. Los modos MySQL y PostgreSQL requieren servicios Compose del proyecto llamados `mysql` o `pgsql`, respectivamente, y `redis`. Los fallos de dependencias o procesos HTTP devuelven un código distinto de cero. Los servicios Compose permanecen activos al terminar HTTP.

Los binarios nativos POSIX reenvían SIGINT y SIGTERM al hijo activo y esperan hasta cinco segundos a que termine su grupo de procesos. Las instalaciones desde código y PHAR requieren las extensiones PHP `pcntl` y `posix` para reenviar señales. Windows utiliza su interrupción de consola.
Los binarios nativos POSIX reenvían SIGINT y SIGTERM al hijo activo y esperan hasta cinco segundos a que termine su grupo de procesos. Windows utiliza su interrupción de consola.

Para Durable Workflow Server independiente con imágenes publicadas, sigue el [inicio rápido del servicio](/docs/quickstart).

Expand Down Expand Up @@ -118,11 +118,11 @@ El comando rechaza modificar instalaciones gestionadas por otra herramienta. La
| `upgraded` | Binario reemplazado por `target_version`. |
| `noop` | `current_version` ya coincide con `target_version`; `--force` evita esta omisión. |
| `dry-run` | `--dry-run` resolvió `target_version`, `asset_url` y `checksum_url` sin descargar. |
| `refused` | La instalación no es un binario independiente (Composer vendor, Homebrew cellar o PHAR), o no hay artefacto publicado para la plataforma. |
| `refused` | La instalación no es un binario independiente (Composer vendor o Homebrew cellar), o no hay artefacto publicado para la plataforma. |
| `permission-denied` | No se puede escribir en el directorio de instalación; la carga incluye `hint` con el paso recomendado. |
| `error` | Fallo al obtener el catálogo, checksum no coincidente o error del sistema de archivos. |

En rechazos, `installation.kind` identifica la herramienta gestora (`composer-vendor`, `homebrew`, `phar` o `binary`) y `reason` indica el responsable correcto. Para automatización pública sin código fuente, reinstala una publicación fijada mediante `https://durable-workflow.com/install.sh`; para Homebrew por tap, utiliza `brew upgrade durable-workflow/tap/dw`.
En rechazos, `installation.kind` identifica la herramienta gestora (`composer-vendor`, `homebrew`, `binary` o `unknown`) y `reason` indica el responsable correcto. Solo un PHAR 2.x, al ejecutar su propio código 2.x, informa `phar`. Para automatización pública sin código fuente, reinstala una publicación fijada mediante `https://durable-workflow.com/install.sh`; para Homebrew por tap, utiliza `brew upgrade durable-workflow/tap/dw`.

## Perfiles de entorno {#environment-profiles}

Expand Down
Loading
Loading