feat: package CLI for PyPI and npm

.github/ci-path-filters.yml

@@ -59,7 +59,10 @@ rust_package:
   - 'crates/ffi/nemo_relay.h'
   - 'crates/ffi/src/**'
   - 'justfile'
+  - 'packages/cli-bin/**'
+  - 'python/cli-bin/**'
   - 'rust-toolchain.toml'
+  - 'scripts/package-cli-bin.py'
 
 node_package:
   - 'Cargo.lock'
@@ -79,8 +82,10 @@ node_package:
   - 'justfile'
   - 'package.json'
   - 'package-lock.json'
+  - 'packages/cli-bin/**'
   - 'pyproject.toml'
   - 'rust-toolchain.toml'
+  - 'scripts/package-cli-bin.py'
   - 'uv.lock'
 
 python_package:
@@ -96,8 +101,10 @@ python_package:
   - 'crates/python/src/**'
   - 'justfile'
   - 'pyproject.toml'
+  - 'python/cli-bin/**'
   - 'python/nemo_relay/**'
   - 'rust-toolchain.toml'
+  - 'scripts/package-cli-bin.py'
   - 'uv.lock'
 
 python_integration_langchain:
@@ -124,7 +131,9 @@ dependencies:
   - 'integrations/**/package.json'
   - 'package.json'
   - 'package-lock.json'
+  - 'packages/cli-bin/**'
   - 'pyproject.toml'
+  - 'python/cli-bin/**'
   - 'scripts/licensing/**'
   - 'uv.lock'
 

.github/workflows/ci.yaml

@@ -400,6 +400,13 @@ jobs:
           name: plugin-wheel
           path: dist/
 
+      - name: Download CLI wheel artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: cli-wheel-*
+          merge-multiple: true
+          path: dist/
+
       - name: Publish to PyPI with trusted publishing
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
@@ -440,6 +447,13 @@ jobs:
           name: openclaw-npm
           path: openclaw-package/
 
+      - name: Download CLI npm artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: cli-npm-*
+          merge-multiple: true
+          path: cli-packages/
+
       - name: Select npm dist-tag
         run: |
           set -e
@@ -462,6 +476,25 @@ jobs:
           ls -la combined/package/*.node
           npm publish ./combined/package --access public --tag "${NEMO_RELAY_NPM_DIST_TAG}"
 
+      - name: Publish CLI packages to npm
+        run: |
+          set -euo pipefail
+          version="${{ github.ref_name }}"
+          for pkg in cli-packages/nemo-relay-cli-bin-{linux-x64,linux-arm64,darwin-arm64,win32-x64,win32-arm64}-${version}.tgz; do
+            name="$(tar xOf "$pkg" package/package.json | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).name')"
+            if npm view "${name}@${version}" version --registry https://registry.npmjs.org >/dev/null 2>&1; then
+              echo "${name} ${version} already exists on npm; skipping"
+              continue
+            fi
+            npm publish "$pkg" --access public --tag "${NEMO_RELAY_NPM_DIST_TAG}"
+          done
+          launcher="cli-packages/nemo-relay-cli-bin-${version}.tgz"
+          if npm view "nemo-relay-cli-bin@${version}" version --registry https://registry.npmjs.org >/dev/null 2>&1; then
+            echo "nemo-relay-cli-bin ${version} already exists on npm; skipping"
+          else
+            npm publish "$launcher" --access public --tag "${NEMO_RELAY_NPM_DIST_TAG}"
+          fi
+
       - name: Publish OpenClaw plugin package to npm
         run: |
           set -euo pipefail

.github/workflows/ci_check.yml

@@ -220,3 +220,7 @@ jobs:
             fi
             pre-commit run --from-ref "$base_ref" --to-ref HEAD --show-diff-on-failure
           fi
+
+      - name: Test CLI package assembly
+        working-directory: ${{ env.NEMO_RELAY_CI_WORKSPACE }}
+        run: uv run --no-project python -m unittest scripts.tests.test_package_cli_bin

.github/workflows/ci_rust.yml

@@ -278,9 +278,50 @@ jobs:
           mkdir -p "${NEMO_RELAY_CI_WORKSPACE_TMP}/cli"
           cp "$source" "${NEMO_RELAY_CI_WORKSPACE_TMP}/cli/${asset}"
 
+      - name: Package CLI binary for PyPI and npm
+        working-directory: ${{ env.NEMO_RELAY_CI_WORKSPACE }}
+        run: |
+          set -euo pipefail
+          target="${{ matrix.target }}"
+          binary="nemo-relay"
+          if [ "${{ runner.os }}" = "Windows" ]; then
+            binary="${binary}.exe"
+          fi
+          source="${NEMO_RELAY_CI_WORKSPACE}/target/${target}/release/${binary}"
+          version="${{ github.ref_name }}"
+          if [ "${{ github.ref_type }}" != "tag" ]; then
+            version="$(sed -n 's/^version = "\(.*\)"$/\1/p' Cargo.toml | head -n1)+${GIT_COMMIT::8}"
+          fi
+          rm -rf "${NEMO_RELAY_CI_WORKSPACE_TMP}/cli-packages"
+          mkdir -p "${NEMO_RELAY_CI_WORKSPACE_TMP}/cli-packages"
+          args=(
+            --binary "$source"
+            --target "$target"
+            --version "$version"
+            --output-dir "${NEMO_RELAY_CI_WORKSPACE_TMP}/cli-packages"
+          )
+          if [ "${{ matrix.platform }}" = "linux-amd64" ]; then
+            args+=(--npm-launcher)
+          fi
+          python scripts/package-cli-bin.py "${args[@]}"
+
       - name: Upload CLI binary artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: cli-${{ matrix.platform }}
           path: ${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}/cli/*
           if-no-files-found: error
+
+      - name: Upload CLI wheel artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: cli-wheel-${{ matrix.platform }}
+          path: ${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}/cli-packages/*.whl
+          if-no-files-found: error
+
+      - name: Upload CLI npm artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: cli-npm-${{ matrix.platform }}
+          path: ${{ env.NEMO_RELAY_CI_WORKSPACE_TMP }}/cli-packages/*.tgz
+          if-no-files-found: error

.gitlab-ci.yml

@@ -68,7 +68,7 @@ collect:github-artifacts:
       fi
       export GH_TOKEN="${NEMO_RELAY_CI_GITHUB_TOKEN}"
 
-      mkdir -p collected/wheels collected/node downloaded
+      mkdir -p collected/wheels collected/node collected/cli-npm downloaded
 
       tag="${CI_COMMIT_TAG:-}"
       if [ -z "$tag" ]; then
@@ -132,10 +132,14 @@ collect:github-artifacts:
       fi
 
       gh run download "$run_id" --repo "$NEMO_RELAY_CI_GITHUB_REPOSITORY" --pattern 'wheel-*' --dir downloaded/wheels
+      gh run download "$run_id" --repo "$NEMO_RELAY_CI_GITHUB_REPOSITORY" --pattern 'cli-wheel-*' --dir downloaded/cli-wheels
+      gh run download "$run_id" --repo "$NEMO_RELAY_CI_GITHUB_REPOSITORY" --pattern 'cli-npm-*' --dir downloaded/cli-npm
       gh run download "$run_id" --repo "$NEMO_RELAY_CI_GITHUB_REPOSITORY" --name 'plugin-wheel' --dir downloaded/wheels
       gh run download "$run_id" --repo "$NEMO_RELAY_CI_GITHUB_REPOSITORY" --name npm-consolidated --dir downloaded/node
 
       find downloaded/wheels -type f -name '*.whl' -exec cp {} collected/wheels/ \;
+      find downloaded/cli-wheels -type f -name '*.whl' -exec cp {} collected/wheels/ \;
+      find downloaded/cli-npm -type f -name '*.tgz' -exec cp {} collected/cli-npm/ \;
       node_zip="$(find downloaded/node -type f -name consolidated.zip -print -quit)"
       if [ -z "$node_zip" ]; then
         echo "Error: collected GitHub npm-consolidated artifact did not contain consolidated.zip." >&2
@@ -167,6 +171,7 @@ collect:github-artifacts:
     paths:
       - collected/wheels/*.whl
       - collected/node/consolidated.zip
+      - collected/cli-npm/*.tgz
       - collected/github-run.json
 
 publish:artifactory:wheels:
@@ -330,3 +335,6 @@ publish:artifactory:npm:
       npm config set "${registry_key}:_auth" "$npm_auth"
 
       npm publish --tag dev collected/node/consolidated/package
+      for package in collected/cli-npm/*.tgz; do
+        npm publish --tag dev "$package"
+      done

README.md

@@ -52,7 +52,23 @@ trajectories.
 
 #### 1. Install the CLI
 
-Run the installer for your platform:
+Install the prebuilt CLI with Python or npm:
+
+```bash
+pip install nemo-relay-cli-bin
+```
+
+```bash
+npm install --global nemo-relay-cli-bin
+```
+
+Python API users can install the matching CLI through the optional extra:
+
+```bash
+pip install "nemo-relay[cli]"
+```
+
+Alternatively, run the installer for your platform:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | sh

RELEASING.md

@@ -31,8 +31,8 @@ The release pipeline publishes these package surfaces from a tag push:
 | Ecosystem | Published Surface |
 |---|---|
 | crates.io | `nemo-relay-types`, `nemo-relay-plugin`, `nemo-relay-worker-proto`, `nemo-relay-worker`, `nemo-relay`, `nemo-relay-adaptive`, `nemo-relay-pii-redaction`, `nemo-relay-switchyard`, `nemo-relay-ffi`, `nemo-relay-cli` |
-| PyPI | `nemo-relay`, `nemo-relay-plugin` |
-| npm | `nemo-relay-node`, `nemo-relay-openclaw` |
+| PyPI | `nemo-relay`, `nemo-relay-plugin`, `nemo-relay-cli-bin` |
+| npm | `nemo-relay-node`, `nemo-relay-openclaw`, `nemo-relay-cli-bin`, and its five platform packages |
 | GitHub Releases | CLI binaries and `SHA256SUMS` |
 | Fern | The documentation site |
 
@@ -61,6 +61,9 @@ NeMo Relay versions are anchored on the workspace SemVer in the repository root
   lock entries and must be updated with it.
 - `integrations/openclaw/package.json` carries the base npm version for the
   OpenClaw plugin package and must stay aligned with the same release version.
+- `packages/cli-bin/package.json` and `python/cli-bin/pyproject.toml` carry the
+  base CLI package versions. The `nemo-relay[cli]` extra must pin the same
+  PEP 440 version.
 - The Python package version is derived at packaging time. `pyproject.toml`
   stays `dynamic = ["version"]` in the repository, and the packaging recipe
   writes a concrete version into `pyproject.toml` and `crates/python/Cargo.toml`
@@ -141,6 +144,12 @@ Before you create a release tag, confirm the following:
      [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml) workflow
    - GitHub Actions `id-token: write` access is available for the top-level npm publish job
    - GitHub Actions `id-token: write` access for the top-level PyPI publish job
+   - Pending or existing PyPI trusted publishing is configured for
+     `nemo-relay-cli-bin`
+   - npm trusted publishers are configured for `nemo-relay-cli-bin` and
+     `nemo-relay-cli-bin-linux-x64`, `nemo-relay-cli-bin-linux-arm64`,
+     `nemo-relay-cli-bin-darwin-arm64`, `nemo-relay-cli-bin-win32-x64`, and
+     `nemo-relay-cli-bin-win32-arm64`
 5. The GitHub Release entry is ready to become the only canonical release-notes
    surface.
 
@@ -167,6 +176,8 @@ The helper updates:
 4. [`integrations/openclaw/package.json`](integrations/openclaw/package.json)
    and the `integrations/openclaw` entry in the root
    [`package-lock.json`](package-lock.json) to the same release version.
+5. The Python and npm `nemo-relay-cli-bin` metadata, including the exact
+   `nemo-relay[cli]` dependency version.
 Review docs and snippets that mention explicit versions, including:
 
 - [`README.md`](README.md)
@@ -243,6 +254,9 @@ The release pipeline then:
    - `package-openclaw` packs the npm OpenClaw plugin package.
    - `package-python` builds platform `nemo-relay` wheels.
    - `package-python-plugin` builds the `nemo-relay-plugin` wheel.
+   - The Rust CLI matrix packages each prebuilt binary as a
+     `nemo-relay-cli-bin` wheel and npm platform package, and creates the npm
+     launcher package once.
    - The CLI release-asset job uploads each platform `nemo-relay` binary and
      includes those binaries in `SHA256SUMS`.
 4. Publishes packages from the top-level workflow after the reusable packaging
@@ -254,11 +268,11 @@ The release pipeline then:
      `nemo-relay-switchyard`, `nemo-relay-ffi`, and `nemo-relay-cli` through
      trusted publishing from
      the top-level workflow
-   - `publish-python` downloads both the `nemo-relay` and `nemo-relay-plugin`
-     wheel artifacts and uploads them to PyPI with trusted publishing from the
-     top-level workflow
-   - `publish-npm` publishes the Node.js and OpenClaw plugin npm packages
-     through npm trusted publishing from the top-level workflow
+   - `publish-python` downloads the `nemo-relay`, `nemo-relay-plugin`, and
+     `nemo-relay-cli-bin` wheel artifacts and uploads them to PyPI with trusted
+     publishing from the top-level workflow
+   - `publish-npm` publishes the Node.js, OpenClaw, and CLI npm packages through
+     npm trusted publishing from the top-level workflow
      - Stable tags publish to the npm `latest` dist-tag
      - Prerelease tags such as `0.1.0-rc.1` publish to the npm `next`
        dist-tag so they do not become the default upgrade target
@@ -291,9 +305,9 @@ NVIDIA Artifactory publication for the same tag:
 npm trusted publishing has its own registry-side constraints:
 
 - Each npm package can only have one trusted publisher configured at a time.
-- Because this repository publishes `nemo-relay-node` and `nemo-relay-openclaw`,
-  configure trusted publishers for both packages
-  before pushing a release tag.
+- Configure trusted publishers for `nemo-relay-node`, `nemo-relay-openclaw`,
+  `nemo-relay-cli-bin`, and all five CLI platform packages before pushing a
+  release tag.
 - npm trusted publishing currently supports GitHub-hosted runners, not
   self-hosted runners.
 
@@ -324,9 +338,10 @@ After the release is live, verify:
    `nemo-relay-pii-redaction`, `nemo-relay-switchyard`, `nemo-relay-ffi`, and
    `nemo-relay-cli` crates
    are visible on crates.io.
-2. The `nemo-relay` wheel is visible on PyPI.
-3. The `nemo-relay-node` and `nemo-relay-openclaw` packages
-   are visible on npm.
+2. The `nemo-relay` and `nemo-relay-cli-bin` wheels are visible on PyPI, and
+   `pip install "nemo-relay[cli]"` exposes `nemo-relay`.
+3. The `nemo-relay-node`, `nemo-relay-openclaw`, `nemo-relay-cli-bin`, and CLI
+   platform packages are visible on npm.
 4. The Unix and Windows installers resolve the new stable tag and verify
    matching CLI release asset checksums on their supported platforms.
 5. The Fern documentation site shows the expected version and release notes.

crates/cli/README.md

@@ -62,6 +62,24 @@ The CLI provides these capabilities:
 
 ## Installation Options
 
+PyPI:
+
+```bash
+pip install nemo-relay-cli-bin
+```
+
+npm:
+
+```bash
+npm install --global nemo-relay-cli-bin
+```
+
+Python API package extra:
+
+```bash
+pip install "nemo-relay[cli]"
+```
+
 Cargo:
 
 ```bash

docs/getting-started/installation.mdx

@@ -33,6 +33,24 @@ coding-agent hook and LLM gateway observability.
 Install the latest stable release:
 
 <Tabs>
+<Tab title="Python">
+```bash
+pip install nemo-relay-cli-bin
+```
+
+To install the Python API and matching CLI together:
+
+```bash
+pip install "nemo-relay[cli]"
+```
+</Tab>
+
+<Tab title="npm">
+```bash
+npm install --global nemo-relay-cli-bin
+```
+</Tab>
+
 <Tab title="Unix shell">
 ```bash
 curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | sh
@@ -47,9 +65,10 @@ irm https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.ps1 | iex
 
 </Tabs>
 
-These commands intentionally download the installer from `main` and install the
-latest stable CLI release. The version of this documentation page does not
-select the CLI version; set `NEMO_RELAY_VERSION` to install a specific release.
+The shell installer commands intentionally download the installer from `main`
+and install the latest stable CLI release. The version of this documentation
+page does not select the CLI version; set `NEMO_RELAY_VERSION` to install a
+specific release.
 
 The Unix installer downloads the matching GitHub Release binary to
 `$HOME/.local/bin`. The PowerShell installer downloads `nemo-relay.exe` to
@@ -158,9 +177,9 @@ new download before replacing the binary in the selected installation directory.
 
 ### Alternative Installation Methods
 
-Use the installers on a supported platform when you want a prebuilt release
-asset. Use Cargo on unsupported platforms or when you prefer to build from
-source:
+The PyPI, npm, and installer methods all install the same release binary on
+supported platforms. Use Cargo on unsupported platforms or when you prefer to
+build from source:
 
 ```bash
 cargo install nemo-relay-cli