wso2 · kanushka · Aug 11, 2026 · Aug 10, 2026 · Aug 11, 2026 · Aug 11, 2026
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,109 @@
+name: Install scripts
+
+# Publishes the install and uninstall scripts to GitHub Pages, so the command in
+# the README points at a stable URL that carries no branch name and can be
+# repointed at a WSO2-owned domain later without changing what users have already
+# copied and shared.
+#
+# What is served is what is in this repository at the commit that ran: the scripts
+# are versioned here and published from here, so there is one copy to review.
+#
+# This needs Pages enabled for the repository with GitHub Actions as its source,
+# which is a repository setting rather than something this file can turn on. Until
+# it is, this workflow fails at the deploy step and the release page remains the
+# way to install.
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'scripts/install.sh'
+      - 'scripts/install.ps1'
+      - 'scripts/uninstall.sh'
+      - 'scripts/uninstall.ps1'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deployment at a time, and a queued one is not cancelled: the last push to
+# main is what should end up published, not whichever run finished last.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish to Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    permissions:
+      # What deploying to Pages requires, and nothing else. `contents` stays read.
+      pages: write
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      # A run that published an unrunnable script would break the one command the
+      # README tells people to use, so the shell script is parsed before it goes
+      # out. The PowerShell script is proven by the Windows job on every pull
+      # request, which is a stronger check than anything available here.
+      - name: Check the scripts parse
+        run: |
+          set -euo pipefail
+          bash -n scripts/install.sh
+          bash -n scripts/uninstall.sh
+
+      - name: Assemble the site
+        run: |
+          set -euo pipefail
+          mkdir -p site
+          cp scripts/install.sh scripts/install.ps1 scripts/uninstall.sh scripts/uninstall.ps1 site/
+          # A landing page, so someone who opens the host in a browser finds out
+          # what these files are rather than a directory listing or a 404.
+          cat > site/index.html <<'HTML'
+          <!doctype html>
+          <html lang="en">
+          <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>Install the WSO2 CLI</title>
+          </head>
+          <body>
+          <h1>Install the WSO2 CLI</h1>
+          <p>macOS, Linux, and WSL:</p>
+          <pre><code>curl -fsSL https://wso2.github.io/wso2-cli/install.sh | bash</code></pre>
+          <p>Windows:</p>
+          <pre><code>iwr https://wso2.github.io/wso2-cli/install.ps1 -useb | iex</code></pre>
+          <p>
+          These scripts download a published release, verify it against the
+          checksum file published beside it, and install the binary under your WSO2
+          state root. Read either one before running it: they are plain text at the
+          URLs above.
+          </p>
+          <p>
+          <a href="https://github.com/wso2/wso2-cli/blob/main/docs/guides/installing.md">Installation guide</a>,
+          including how to install without piping a script to a shell, how to pin a
+          version, and how to uninstall.
+          </p>
+          </body>
+          </html>
+          HTML
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload the site
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to Pages
+        id: deploy
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -9,6 +9,33 @@ examples, and supporting research.
 > behavior before the corresponding implementation is available, and
 > interfaces may change until they are identified as stable.
 
+## Installation
+
+macOS, Linux, and WSL:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | bash
+```
+
+Windows:
+
+```powershell
+iwr https://wso2.github.io/wso2-cli/install.ps1 -useb | iex
+```
+
+Both scripts download a published release, verify it against the SHA-256 checksum
+file published beside it, and install the binary under your WSO2 state root.
+Neither needs administrator rights, and both are plain text at the URLs above if
+you would rather read one before running it.
+
+Released binaries are checksum-verified but not code signed or notarized.
+Supported platforms are Linux on `amd64`, `arm64`, `arm`, and `386`, and macOS and
+Windows on `amd64` and `arm64`.
+
+The [installation guide](docs/guides/installing.md) covers installing from the
+release page without running a remote script, pinning a version, release
+candidates, where files go, and how to uninstall.
+
 ## Documentation
 
 The [documentation index](docs/README.md) provides the complete reading order.

diff --git a/docs/README.md b/docs/README.md
@@ -48,6 +48,9 @@ described commands or schemas are currently available.
 
 ## Guides
 
+- [Installing](guides/installing.md) takes a first-time user from a bare machine
+  to a working `wso2`, by one command or by hand from the release page, and
+  covers pinning a version, release candidates, where files go, and uninstalling.
 - [Logging in](guides/login.md) takes a first-time user from a registered
   OAuth application, through authoring the context document and the first
   `wso2 login`, to a CI job that authenticates without one. Everything in it is

diff --git a/docs/guides/installing.md b/docs/guides/installing.md
@@ -0,0 +1,203 @@
+# Installing the WSO2 CLI
+
+**Status:** Working draft
+**Related:** [Release artifacts](../reference/release-artifacts.md),
+[distribution research](../research/root-cli-installation-distribution.md)
+**Last reviewed:** 2026-08-11
+
+This guide installs the `wso2` shell. It covers the one-command install, the
+manual alternative for anyone who will not pipe a script to a shell, and how to
+pin, upgrade, and remove it.
+
+## What this channel gives you, and what it does not
+
+The installer downloads a published release and verifies it against the SHA-256
+checksum file published beside it. A download that fails verification is not
+installed.
+
+The binaries are **not code signed or notarized**. macOS Gatekeeper and Windows
+SmartScreen may warn about them, and integrity rests on that checksum file and
+on HTTPS. Signed, per-platform channels — Homebrew, WinGet, APT, RPM — are
+the intended destination and are described in the
+[distribution research](../research/root-cli-installation-distribution.md); this
+channel exists so the CLI is installable before they are ready.
+
+Nothing in the install needs administrator rights, on any platform.
+
+## Install
+
+### macOS, Linux, and WSL
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | bash
+```
+
+### Windows
+
+```powershell
+iwr https://wso2.github.io/wso2-cli/install.ps1 -useb | iex
+```
+
+Open a new terminal afterwards, or re-source the profile the script names, and
+check what you have:
+
+```sh
+wso2 version
+```
+
+### Supported platforms
+
+| Operating system | Architectures                  |
+| ---------------- | ------------------------------ |
+| Linux            | `amd64`, `arm64`, `arm`, `386` |
+| macOS            | `amd64`, `arm64`               |
+| Windows          | `amd64`, `arm64`               |
+
+An unsupported operating system or architecture is refused, naming what was
+detected, rather than installed and left to fail later.
+
+## Read the script first
+
+Both scripts are plain text at the URLs above, and reading one before running it
+is a reasonable thing to want:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | less
+```
+
+They are versioned in this repository at
+[`scripts/install.sh`](../../scripts/install.sh) and
+[`scripts/install.ps1`](../../scripts/install.ps1), and what is served is what
+is in the repository.
+
+## Install without running a remote script
+
+Every release carries the same archives the script downloads, so nothing is lost
+by doing it by hand.
+
+1. Open the [releases page](https://github.com/wso2/wso2-cli/releases) and note
+   the tag you want.
+2. Download the archive for your platform and the `checksums.txt` beside it. The
+   naming convention is in
+   [release artifacts](../reference/release-artifacts.md).
+3. Verify the archive, and do not continue unless it passes:
+
+   ```sh
+   sha256sum --check --ignore-missing checksums.txt
+   ```
+
+   On macOS, `shasum -a 256 --ignore-missing -c checksums.txt` does the same.
+   The flag matters: `checksums.txt` lists every platform's archive, and without
+   it the check fails over the ones you did not download. On Windows,
+   `Get-FileHash -Algorithm SHA256 <archive>` prints the digest to compare
+   against the line in `checksums.txt`.
+4. Extract it and put the `wso2` binary somewhere on your `PATH`. The installer
+   uses `~/.wso2/bin`, and there is nothing special about that location.
+
+## Pin a version
+
+Installing whatever is newest is the wrong default for a build. Pass the tag:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | bash -s v0.1.0
+```
+
+```powershell
+&([scriptblock]::Create((iwr https://wso2.github.io/wso2-cli/install.ps1 -useb))) v0.1.0
+```
+
+## Install a release candidate
+
+Prereleases are skipped when resolving the newest release, so asking for one is
+explicit. Note where the variable goes: in a pipeline it has to be set on the
+`bash` that runs the script, not on the `curl` that fetches it.
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | WSO2_CLI_PRERELEASE=true bash
+```
+
+```powershell
+$env:WSO2_CLI_PRERELEASE = 'true'
+iwr https://wso2.github.io/wso2-cli/install.ps1 -useb | iex
+```
+
+## Upgrade
+
+Run the installer again. It replaces the binary in place and does not add a
+second entry to your profile or `PATH`. There is no self-update command.
+
+## Where things go, and how to change it
+
+| What                | Where                            |
+| ------------------- | -------------------------------- |
+| The binary          | `$WSO2_HOME/bin`                 |
+| State root default  | `~/.wso2`                        |
+| Contexts and state  | Under the state root             |
+
+Set `WSO2_HOME` before installing to put everything somewhere else:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | WSO2_HOME=/opt/wso2 bash
+```
+
+The installer records the state root it used, so the shell it installs and the
+state it reads cannot disagree about where they live.
+
+### Keep your shell profile to yourself
+
+By default the Unix installer appends one delimited block to the shell profile
+it detects, and the Windows installer sets your per-user `PATH` and
+`WSO2_HOME`. To install without either, and be told what to set yourself:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/install.sh | WSO2_CLI_NO_PROFILE=1 bash
+```
+
+The block is delimited and greppable, so you can always find what was added:
+
+```text
+# >>> wso2 cli >>>
+export WSO2_HOME="/home/you/.wso2"
+export PATH="/home/you/.wso2/bin:$PATH"
+# <<< wso2 cli <<<
+```
+
+## Uninstall
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/uninstall.sh | bash
+```
+
+```powershell
+iwr https://wso2.github.io/wso2-cli/uninstall.ps1 -useb | iex
+```
+
+This removes the binary, the directory the installer created for it, and the
+profile block or environment entries it added. It **keeps your configuration,
+contexts, and credentials**, and tells you where they are. To remove those too:
+
+```sh
+curl -fsSL https://wso2.github.io/wso2-cli/uninstall.sh | bash -s -- --purge
+```
+
+```powershell
+&([scriptblock]::Create((iwr https://wso2.github.io/wso2-cli/uninstall.ps1 -useb))) -Purge
+```
+
+Uninstalling when nothing is installed is not an error: it reports that there
+was nothing to do, which also makes it the way to clean up after an install that
+failed halfway.
+
+## If something goes wrong
+
+**`wso2: command not found` right after installing.** The profile change applies
+to new shells. Open a new terminal, or run the `source` command the installer
+printed.
+
+**A checksum mismatch.** The install stops and nothing is written. Retry once,
+in case the download was truncated. If it happens again, do not work around
+it — open an issue with the tag and platform, since a released archive not
+matching its published checksum is a problem worth knowing about.
+
+**Windows says it cannot replace the binary.** Something is running it. Close
+any `wso2` process and run the installer again.
diff --git a/docs/research/README.md b/docs/research/README.md
@@ -11,6 +11,7 @@ These files preserve the source material and research that informed the current
 | --- | --- |
 | [Archived original proposal](archive/original-proposal.md) | Historical proposal retained for context; it is not authoritative. |
 | [Public WSO2 CLI inventory](public-wso2-cli-inventory.md) | Inventory based only on publicly accessible WSO2 repositories and documentation. |
+| [choreo-cli-installation-distribution.md](choreo-cli-installation-distribution.md) | Primary-source research into Choreo CLI's install-script mechanics, release artifact conventions, Windows support, and the shared distribution setup it turned out to have with `wdp-cli`. |
 | [kubectl-krew.md](kubectl-krew.md) | Research into kubectl dispatch and Krew package management, including lessons adopted and gaps to improve. |
 | [cloud-cli-comparison.md](cloud-cli-comparison.md) | Primary-source comparison of Azure CLI, AWS CLI, and Google Cloud CLI. |
 | [module-architecture-options.md](module-architecture-options.md) | Evaluation of module-extension models and the recommended subprocess contract. |