Awesome

The binary package manager for Node

Manage and run binaries via npm. CLI and API interfaces.

Table of Contents

• Introduction
• Quickstart
• CLI
  • gobot <app> [gobotOptions] [appOptions]
  • gobot inspect <app> [gobotOptions]
• Official Gobot Apps
• Why?
• Technical Notes
  • Repository API Rate Limits
    • Github API
• Adding your app to the Gobot registry
• Contributing

Introduction

Gobot installs binary apps anywhere npm is available. It transparently downloads, installs, and runs binary apps (including semver ranges) for the current operating system and architecture.

Works on Windows, Linux, OS X.

Features

• Run any version of official apps and many unofficial apps from github.
• Binaries are intelligently downloaded and cached
• New binary versions are automatically detected and downloaded
• Efficient - downloads only what is needed

Inspired by esbuild and other packages that install binary dependencies

Quickstart

Run an official app from anywhere

npx gobot <app>

List of official apps

Try running an unofficial app using github user/repo

Gobot will examine releases from Github and attempt to decipher versions, platforms, and architectures.

gobot <user>/<repo> --help

Install gobot globally

npm i -g gobot

gobot pocketbase --help
gobot caddy --help
gobot act --help

Use a Gobot app programmatically

npm i gobot

import { gobot } from 'gobot'
const bot = await gobot(`pocketbase`)
const exitCode = await bot.run([`--help`])

Pass environment variables

In API mode, Gobot does not forward environment variables by default.

import { gobot } from 'gobot'
const bot = await gobot(`pocketbase`, {
  env: process.env,
})
const exitCode = await bot.run([`--help`])

Use a specific version of a Gobot app

const bot = await gobot(`pocketbase`, {
  version: `0.19.3`,
})
const exitCode = await bot.run([`--help`])

Access the child process

import { gobot } from 'gobot'
const bot = await gobot(`pocketbase`, {
  env: process.env,
})
const exitCode = await bot.run(
  [`--help`],
  { cwd: `./foo` }, // SpawnOptions
  (proc) => {
    // ChildProcess
    proc.stdout.on('exit', (code) => {
      console.log(`process has exited`)
    })
  },
)

Add an official app as a project dependency

npm i gobot-<app>[@version]

Gobot will automatically select the specific version of <app> you installed and it will stay locked according to your package.json constraints.

npm i gobot-pocketbase@0.19.3

import { gobot } from 'gobot'
const bot = await gobot(`pocketbase`)
const exitCode = await bot.run([`--help`])

CLI

Note: All Gobot options begin with --g- so as not to conflict with app option switches. Every unrecognized option is passed through to the app binary.

Global options

These options are available on every command:

gobot <appName> [options]

Run a binary app. The app will be downloaded if it has not been downloaded yet. After that, you must run 'gobot update <appName>' to make Gobot look for new versions.

Options

gobot inspect [appName]

Display Gobot registry information. If [appName] is specified, Gobot will display release information. Otherwise, Gobot will display an overview of current registry information

gobot download <appName> [options]

Download versions of <appName>. Gobot will download and cache the specific platform, architecture, and versions you request, defaulting to downloading the latest version for the host platform and architecture.

Options

gobot export <appName><format>

Export app version information

gobot update <appName>

Pull the latest release history for <appName>, optionally.

gobot reset [appName]

Reset caches. If [appName] is specified, only that app's cache is reset. Otherwise, all caches are reset. Caches include release history and binary downloads. Use 'gobot inspect' to learn more about host-specific cache locations and contents.

API

Full API Docs

Official Gobot Apps

Gobot supports 53 apps using bin names. They also have npm helper packages to assist with version locking.

Running unofficial apps

Gobot can run many apps hosted on github. Gobot will examine the releases and attempt to decipher binaries based on version, platform, and architecture.

gobot <user>/<repo>

Example

# Run PocketBase as a direct repo name
# rather than the `pocketbase` alias
gobot pocketbase/pocketbase --help

or API:

const bot = await gobot(`pocketbase/pocketbase`)
const exitCode = await bot.run([`--help`])

The above command format may run the app you have in mind. If it doesn't and you want more information, use

gobot inspect <user>/<repo>

As long as the project uses the github Releases feature and includes statically linked binaries with zero dependencies, Gobot can probably run it.

Go apps work flawlessly, if the releases are named well. Gobot was originally named and conceived to support Go apps.

Getting Help

Join our Discord community.

Why?

If you are writing a nodejs application that depends upon binaries being present (like PocketHost does), you can add this package as a dependency and execute the binary via CLI or programmatically. This package will make sure your desired external binaries are always available.

If you just want to grab a binary quickly for your own use, npx gobot@latest <app> is quite a bit easier than manually downloading zips and installing binaries in shell paths. Gobot handles it all for you effortlessly.

Adding your app to the Gobot registry

We want to add native support for lots of binary apps!

If you use publish statically linked binary releases on github, you are already 98% compatible with Gobot. In fact, Gobot may already know how to work with it.

To see what initial support looks like:

npx gobot inspect <user>/<repo>

This will index all the releases from your repo and show you exactly what Gobot sees.

If you see everything you expect, you're golden. If things are missing, it may mean some custom programming. Either way, jump on Discord and let us know your results.

If you have the flexibility or are starting a new project, make sure your release names follows these rules:

• Ends in .zip, .tgz, .tar.gz, .bz2
• Include the version (semver recommended)
• Include the platform (freebsd, darwin, linux, win32)
• Include the architecture (arm64, x64, ia32, arm)

Note: GoReleaser is a great option if you're publish a Go-based project.

Contributing

We could use help testing and making sure this works across lots of platforms.

To test a build locally:

pnpm test