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

• 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

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

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`])

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:

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

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

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

Export app version information

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

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.

Full API Docs

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

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.

Join our Discord community.

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.

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.

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

To test a build locally:

pnpm test