{"id":22423287,"url":"https://github.com/prantlf/grab-github-release","last_synced_at":"2025-10-10T08:35:38.569Z","repository":{"id":203793327,"uuid":"710444076","full_name":"prantlf/grab-github-release","owner":"prantlf","description":"Downloads and optionally unpacks an archive from GitHub release assets for the current platform.","archived":false,"fork":false,"pushed_at":"2024-08-11T17:31:20.000Z","size":117,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-10T08:35:21.369Z","etag":null,"topics":["assets","download","github","github-release","release"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-26T17:48:24.000Z","updated_at":"2024-09-02T16:40:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"c163f499-c947-4eec-b27f-0bcad7530e08","html_url":"https://github.com/prantlf/grab-github-release","commit_stats":{"total_commits":20,"total_committers":2,"mean_commits":10.0,"dds":"0.30000000000000004","last_synced_commit":"b82f14a6f3811185e4390dc08872a2403cc47285"},"previous_names":["prantlf/grab-github-release"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/grab-github-release","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrab-github-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrab-github-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrab-github-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrab-github-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/grab-github-release/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrab-github-release/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003277,"owners_count":26083555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assets","download","github","github-release","release"],"created_at":"2024-12-05T18:09:53.024Z","updated_at":"2025-10-10T08:35:38.553Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","readme":"# Grab GitHub Release\n\n[![Latest version](https://img.shields.io/npm/v/grab-github-release)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/grab-github-release)\n](https://www.npmjs.com/package/grab-github-release)\n[![Coverage](https://codecov.io/gh/prantlf/grab-github-release/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/grab-github-release)\n\nDownloads and optionally unpacks an archive from GitHub release assets for the current platform.\n\nIf used to install a binary executable to a NPM package, [link-bin-executable] can help.\n\n## Synopsis\n\n```js\nimport { grab } from 'grab-github-release'\n\ntry {\n  const repository = 'prantlf/v-jsonlint'\n  // downloads and unpacks the jsonlint executable to the current directory\n  await grab({ repository, unpackExecutable: true })\n} catch(err) {\n  console.error(err.message)\n  process.exitCode = 1\n}\n```\n\nThe archive with the executable is expected to be:\n\n    {name}-{platform}-{architecture}.zip\n\nwhere:\n\n* `{name}` is the name of the tool (executable)\n* `{platform}` is the name of the target platform, by default: `linux`, `darwin` (also `macos`) and `win32` (also `windows`)\n* `{architecture}` is the name of the target architecture, by default `arm64` (also `aarch64`), `riscv64` and `x64` (also `amd64`, `x86_64` or `x86`)\n\n## Installation\n\nThis package can be installed globally, if you want to use the `grab-github-release` script (or the `ggr` alias). You can install it during the first usage with `npx` too:\n\n```sh\n$ npm i -g grab-github-release\n$ npx grab-github-release ...\n```\n\nThis package can be installed locally too, if you want to use it programmatically:\n\n```sh\n$ npm i -g grab-github-release\n$ npx grab-github-release ...\n```\n\nMake sure, that you use [Node.js] version 18 or newer.\n\n## Command-line Usage\n\n    Usage: [options]\n\n    Options:\n      --clear-cache                 clears the cache, optionally for a \"name\"\n      -r|--repository \u003crepository\u003e  GitHub repository formatted \"owner/name\"\n      -i|--version-spec \u003csemver\u003e    semantic version specifier or \"latest\"\n      -n|--name \u003cfile-name\u003e         archive name without the platform suffix\n      -p|--platform-suffixes \u003cmap\u003e  platform name mapping\n      -a|--arch-suffixes \u003cmap\u003e      architecture name mapping\n      -t|--target-dir \u003cdir-name\u003e    directory to write the output files to\n      -e|--unpack-exe               unpack the executable and remove the archive\n      -c|--cache                    use ~/.cache/grabghr as cache\n      --force-cache                 use the cache to discover the latest version\n      -g|--gh-token \u003ctoken\u003e         GitHub authentication token\n      -v|--verbose                  prints extra information on the console\n      -V|--version                  print version number and exit\n      -h|--help                     print usage instructions and exit\n\n    The version specifier is \"latest\" by default. The file name will be inferred\n    from the first archive asset found for the current platform, if not specified.\n    If GitHub token is not specified, variables GITHUB_TOKEN and GH_TOKEN in the\n    process environment will be checked too.\n\n    Examples:\n      $ grab-github-release -r prantlf/v-jsonlint -p darwin=macos,win32=windows:win64 -u\n      $ grab-github-release -r prantlf/v-jsonlint -i \u003e=0.0.6\n\n## API\n\n```ts\n// map where keys are Node.js platform names and values are their replacements\n// to be used in names of archive looked for among  GitHub release assets\ntype ArchiveSuffixes = Record\u003cstring, string[]\u003e\n\ninterface GrabOptions {\n  // GitHub repository formatted \"owner/name\", mandatory\n  repository: string\n  // semantic version specifier or \"latest\"; defaults to \"latest\", if unspecified\n  version?: string\n  // archive name without the platform and architecture suffix\n  // and without the \".zip\" extension as well\n  name?: string\n  // recognised platforms organised by the Node.js platform name; defaults:\n  // - darwin: darwin, macos\n  // - linux: linux\n  // - win32: win32, windows\n  platformSuffixes?: ArchiveSuffixes\n  // recognised architectures organised by the Node.js platform name; defaults:\n  // - arm64: aarch64, arm64\n  // - riscv64: riscv64\n  // - x64: amd64, x86_64, x64, x86\n  archSuffixes?: ArchiveSuffixes\n  // directory to write the archive or executable to; if not specified,\n  // files will be written to the current directory\n  targetDirectory?: string\n  // unpack the executable and remove the archive\n  unpackExecutable?: boolean\n  // store the downloaded archives from GitHub releases to the cache\n  // in ~/.cache/grabghr; `true` is the default\n  cache?: boolean\n  // force using the cache for getting the last available version and avoid\n  // connecting to GitHub if the cache isn't empty\n  forceCache?: boolean\n  // GitHub authentication token, overrides the environment variables\n  // GITHUB_TOKEN or GH_TOKEN\n  token?: string\n  // print details about the program execution\n  verbose?: boolean\n}\n\ninterface GrabResult {\n  // actual version number as specified or picked from the list of releases\n  version: string\n  // downloaded archive name, if not removed (and the executable not unpacked)\n  archive?: string\n  // executable file name, if it was unpacked (and the archive removed)\n  executable?: string\n}\n\ninterface ClearCacheOptions {\n  // GitHub repository formatted \"owner/name\", mandatory\n  repository: string\n  // print details about the program execution\n  verbose?: boolean\n}\n\n// downloads and optionally unpacks an archive from GitHub release assets\n// for the current platform\nexport function grab(options: GrabOptions): Promise\u003cGrabResult\u003e\n\n// clears the cache used for downloading archives from GitHub releases\nexport function clearCache(options?: ClearCacheOptions): Promise\u003cvoid\u003e\n```\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style.  Add unit tests for any new or changed functionality. Lint and test your code using Grunt.\n\n## License\n\nCopyright (c) 2023-2024 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Node.js]: http://nodejs.org/\n[link-bin-executable]: https://github.com/prantlf/link-bin-executable\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fgrab-github-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fgrab-github-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fgrab-github-release/lists"}