The binary package manager for Node

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

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:

Name	Default	Discussion
`--g-version`		output the version number
`--g-v`	`true`	Show informational output
`--g-vv`	`false`	Show even more output
`--g-vvv`	`false`	Show even more output
`--g-cache-path`	`host specific`	The cache path to use

`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

Name	Default	Discussion
`--g-use-version`	`*`	Run a specific binary version (format: x.y.z semver or x.y.* semver range)
`--g-os`	`host specific`	Specify OS/Platform
`--g-arch`	`host specific`	Specify OS/Platform

`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

Name	Default	Discussion
`--g-use-version`	`latest`	Download a specific binary version (format: x.y.z semver or x.y.* semver range)
`--g-os`	`host specific`	Specify OS/Platform
`--g-arch`	`host specific`	Specify OS/Platform
`--g-force`	`false`	Force re-downloading and replacing even if version already exists

`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.

`<app>`	What is it?
`act`	Run your GitHub Actions locally 🚀	npm
`AdGuardHome`	Network-wide ads & trackers blocking DNS server	npm
`age`	A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.	npm
`aperture`	Rate limiting, caching, and request prioritization for modern workloads	npm
`backrest`	Backrest is a web UI and orchestrator for restic backup.	npm
`caddy`	Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS	npm
`centrifugo`	Scalable real-time messaging server in a language-agnostic way. Self-hosted alternative to Pubnub, Pusher, Ably. Set up once and forever.	npm
`chezmoi`	Manage your dotfiles across multiple diverse machines, securely.	npm
`constellation`	Constellation is the first Confidential Kubernetes. Constellation shields entire Kubernetes clusters from the (cloud) infrastructure using confidential computing.	npm
`croc`	Easily and securely send things from one computer to another 🐊 📦	npm
`cue`	The home of the CUE language! Validate and define text-based and dynamic configuration	npm
`dasel`	Select, put and delete data from JSON, TOML, YAML, XML and CSV files with a single tool. Supports conversion between formats and can be used as a Go package.	npm
`dnscryptproxy`	dnscrypt-proxy 2 - A flexible DNS proxy, with support for encrypted DNS protocols.	npm
`duf`	Disk Usage/Free Utility - a better 'df' alternative	npm
`etcd`	Distributed reliable key-value store for the most critical data of a distributed system	npm
`ferretdb`	A truly Open Source MongoDB alternative	npm
`filebrowser`	📂 Web File Browser	npm
`fzf`	🌸 A command-line fuzzy finder	npm
`gitea`	Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD	npm
`gocryptfs`	Encrypted overlay filesystem written in Go	npm
`gokapi`	Lightweight self-hosted Firefox Send alternative without public upload. AWS S3 supported.	npm
`gotify`	A simple server for sending and receiving messages in real-time per WebSocket. (Includes a sleek web-ui)	npm
`gotifyc`	A command line interface for pushing messages to gotify/server.	npm
`gotop`	A terminal based graphical activity monitor inspired by gtop and vtop	npm
`gotty`	Share your terminal as a web application	npm
`gptscript`	Natural Language Programming.	npm
`hugo`	The world’s fastest framework for building websites.	npm
`incus`	Powerful system container and virtual machine manager	npm
`kopia`	Cross-platform backup tool for Windows, macOS & Linux with fast, incremental backups, client-side end-to-end encryption, compression and data deduplication. CLI and GUI included.	npm
`kubo`	An IPFS implementation in Go	npm
`lazygit`	simple terminal UI for git commands	npm
`lf`	Terminal file manager	npm
`litefs`	FUSE-based file system for replicating SQLite databases across a cluster of machines	npm
`litestream`	Streaming replication for SQLite.	npm
`loki`	Like Prometheus, but for logs.	npm
`mc`	The Object Store for AI Data Infrastructure (client)	npm
`micro`	A modern and intuitive terminal-based text editor	npm
`minio`	The Object Store for AI Data Infrastructure (server)	npm
`natsd`	High-Performance server for NATS.io, the cloud and edge native messaging system.	npm
`ollama`	Get up and running with Llama 2, Mistral, Gemma, and other large language models.	npm
`pocketbase`	Open Source realtime backend in 1 file	npm
`prometheus`	The Prometheus monitoring system and time series database.	npm
`pulumi`	Pulumi - Infrastructure as Code in any programming language. Build infrastructure intuitively on any cloud using familiar languages 🚀	npm
`rclone`	rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Yandex Files	npm
`restic`	Fast, secure, efficient backup program.	npm
`reviewdog`	🐶 Automated code review tool integrated with any code analysis tools regardless of programming language	npm
`sftpgo`	Fully featured and highly configurable SFTP server with optional HTTP/S, FTP/S and WebDAV support - S3, Google Cloud Storage, Azure Blob	npm
`syncthing`	Open Source Continuous File Synchronization	npm
`temporal`	Temporal service	npm
`tinygo`	Go compiler for small places. Microcontrollers, WebAssembly (WASM/WASI), and command-line tools. Based on LLVM.	npm
`transfersh`	Easy and fast file sharing from the command-line.	npm
`weaviate`	Weaviate is an open source vector database that stores both objects and vectors, allowing for combining vector search with structured filtering with the fault-tolerance and scalability of a cloud-native database, all accessible through GraphQL, REST, and various language clients.	npm
`weed`	SeaweedFS is a fast distributed storage system for blobs, objects, files, and data lake, for billions of files! Blob store has O(1) disk seek, cloud tiering. Filer supports Cloud Drive, cross-DC active-active replication, Kubernetes, POSIX FUSE mount, S3 API, S3 Gateway, Hadoop, WebDAV, encryption, Erasure Coding.	npm

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

Name		Name	Last commit message	Last commit date
Latest commit History 528 Commits
assets		assets
docs		docs
locktest		locktest
packages/decompress-tar-z		packages/decompress-tar-z
patches		patches
plop		plop
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.runifchanged.checksum		.runifchanged.checksum
cspell.json		cspell.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
readme.md		readme.md
release.md		release.md
test.ts		test.ts
tsconfig.json		tsconfig.json
tsconfig.typedoc.json		tsconfig.typedoc.json
tsup.config.ts		tsup.config.ts
typedoc.json		typedoc.json
verdaccio.config.yaml		verdaccio.config.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

The binary package manager for Node

Table of Contents

Introduction

Quickstart

CLI

`gobot <appName> [options]`

`gobot inspect [appName]`

`gobot download <appName> [options]`

`gobot export <appName><format>`

`gobot update <appName>`

`gobot reset [appName]`

API

Official Gobot Apps

Running unofficial apps

Getting Help

Why?

Adding your app to the Gobot registry

Contributing

About

Releases

Packages

Contributors 2

Languages

benallfree/gobot

Folders and files

Latest commit

History

Repository files navigation

The binary package manager for Node

Table of Contents

Introduction

Quickstart

CLI

gobot <appName> [options]

gobot inspect [appName]

gobot download <appName> [options]

gobot export <appName><format>

gobot update <appName>

gobot reset [appName]

API

Official Gobot Apps

Running unofficial apps

Getting Help

Why?

Adding your app to the Gobot registry

Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

`gobot <appName> [options]`

`gobot inspect [appName]`

`gobot download <appName> [options]`

`gobot export <appName><format>`

`gobot update <appName>`

`gobot reset [appName]`

Packages