feat: add npm distribution with platform-specific packages

.github/workflows/release.yml

@@ -7,9 +7,12 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   release:
+    # MUST use GitHub-hosted public runners — npm --provenance requires OIDC id-token
+    # from a trusted CI environment (GitHub Actions on public runners).
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -25,3 +28,20 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Smoke test npm packages
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          VERSION="$VERSION" scripts/npm-smoke-test.sh
+
+      - name: Publish to npm
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          VERSION="$VERSION" scripts/npm-publish.sh
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -1,5 +1,5 @@
 # Binaries
-cg
+/cg
 *.exe
 *.exe~
 *.dll
@@ -29,6 +29,13 @@ Thumbs.db
 # Build
 dist/
 
+# npm platform binaries (copied during CI publish)
+npm/cg-*/cg
+npm/cg-*/cg.exe
+
+# npm umbrella README (copied from root during CI publish)
+npm/cg/README.md
+
 # Secrets
 .env
 .env.*

README.md

@@ -42,6 +42,14 @@ brew tap coingecko/coingecko-cli
 brew install cg
 ```
 
+### npm
+
+```sh
+npm install -g @coingecko/cg
+```
+
+Works on macOS, Linux, and Windows (x64 and arm64). Requires Node.js >= 20. The right native binary for your platform is fetched via npm `optionalDependencies`; no build step.
+
 ### Shell script
 
 ```sh

npm/cg-darwin-arm64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-darwin-arm64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-darwin-arm64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (macOS ARM64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["darwin"],
+  "cpu": ["arm64"],
+  "files": ["cg"]
+}

npm/cg-darwin-x64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-darwin-x64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-darwin-x64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (macOS x64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["darwin"],
+  "cpu": ["x64"],
+  "files": ["cg"]
+}

npm/cg-linux-arm64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-linux-arm64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-linux-arm64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (Linux ARM64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["linux"],
+  "cpu": ["arm64"],
+  "files": ["cg"]
+}

npm/cg-linux-x64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-linux-x64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-linux-x64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (Linux x64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["linux"],
+  "cpu": ["x64"],
+  "files": ["cg"]
+}

npm/cg-win32-arm64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-win32-arm64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-win32-arm64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (Windows ARM64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["win32"],
+  "cpu": ["arm64"],
+  "files": ["cg.exe"]
+}

npm/cg-win32-x64/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg-win32-x64/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@coingecko/cg-win32-x64",
+  "version": "0.0.0",
+  "description": "CoinGecko CLI - Real Time & Historical Crypto Data (Windows x64)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coingecko/coingecko-cli.git"
+  },
+  "homepage": "https://github.com/coingecko/coingecko-cli",
+  "bugs": {
+    "url": "https://github.com/coingecko/coingecko-cli/issues"
+  },
+  "license": "MIT",
+  "os": ["win32"],
+  "cpu": ["x64"],
+  "files": ["cg.exe"]
+}

npm/cg/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Gecko Labs Pte. Ltd. and/or its affiliates. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npm/cg/bin/cg.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const os = require("os");
+
+// Map Node.js platform/arch to npm package names
+const PLATFORMS = {
+  "darwin arm64": "@coingecko/cg-darwin-arm64",
+  "darwin x64": "@coingecko/cg-darwin-x64",
+  "linux arm64": "@coingecko/cg-linux-arm64",
+  "linux x64": "@coingecko/cg-linux-x64",
+  "win32 arm64": "@coingecko/cg-win32-arm64",
+  "win32 x64": "@coingecko/cg-win32-x64",
+};
+
+function getBinaryPath() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const key = `${platform} ${arch}`;
+  const pkg = PLATFORMS[key];
+
+  if (!pkg) {
+    throw new Error(
+      `Unsupported platform: ${platform} ${arch}. ` +
+        `Supported: ${Object.keys(PLATFORMS).join(", ")}`
+    );
+  }
+
+  const binary = platform === "win32" ? "cg.exe" : "cg";
+
+  try {
+    // resolve the platform package from this package's location
+    const pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
+    return path.join(pkgDir, binary);
+  } catch {
+    throw new Error(
+      `The platform package ${pkg} is not installed. ` +
+        `This usually means your package manager excluded optional dependencies. ` +
+        `Try reinstalling with: npm install @coingecko/cg`
+    );
+  }
+}
+
+const binary = getBinaryPath();
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  if (err.status !== undefined) {
+    process.exit(err.status);
+  }
+  throw err;
+}