topsail

module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2026 License: MIT

README

topsail

topsail

Go Version Platform Architecture License CI CodeQL govulncheck Go Reference

A BusyBox-style multi-call binary in Go — 84 Unix utilities, one ~3 MB statically-linked executable, native on Linux, macOS, and Windows.

topsail is the Go sibling of mainsail. Same applet contract, same dispatch UX, same --list / --help formatting — but compiled to a single static binary that runs unchanged on glibc, musl/Alpine, distroless, and scratch.

Quick start

Pre-built binary

Download the appropriate archive from the latest release, verify it (see verifying signatures), then drop it on your PATH:

# Linux / macOS
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fL -o topsail.tar.gz \
  "https://github.com/Real-Fruit-Snacks/topsail/releases/latest/download/topsail_${OS}_${ARCH}.tar.gz"
tar xzf topsail.tar.gz
./topsail --list
Linux packages (.deb / .rpm / .apk)

Each release also publishes Debian, RPM, and Alpine packages. Pick the right one for your distro from the latest release:

# Debian / Ubuntu
sudo dpkg -i topsail_<arch>.deb

# Fedora / RHEL / openSUSE
sudo rpm -i topsail_<arch>.rpm

# Alpine
sudo apk add --allow-untrusted topsail_<arch>.apk

Each package installs the binary to /usr/bin/topsail, man pages under /usr/share/man/man1/, and shell completions for bash / zsh / fish in their canonical locations.

Build from source
git clone https://github.com/Real-Fruit-Snacks/topsail
cd topsail
make build
./topsail --list

Or, if you just want the binary somewhere on your GOPATH:

go install github.com/Real-Fruit-Snacks/topsail/cmd/topsail@latest
Multi-call dispatch
topsail ls -la                    # explicit dispatch
ln -s topsail ls && ./ls -la      # symlink dispatch (Unix)
copy topsail.exe ls.exe & ls -la  # copy dispatch (Windows)

The dispatcher checks argv[0]'s basename against the applet registry. Unknown invocations fall through to topsail <applet> [args] wrapper mode. .exe suffixes are stripped on Windows before lookup.

Pre-built binaries

Each release ships six platform/architecture combinations, plus a checksums file and cosign keyless signatures:

Platform Architecture Archive
Linux x86_64 topsail_<version>_Linux_amd64.tar.gz
Linux ARM64 topsail_<version>_Linux_arm64.tar.gz
macOS Intel topsail_<version>_Darwin_amd64.tar.gz
macOS Apple Silicon topsail_<version>_Darwin_arm64.tar.gz
Windows x86_64 topsail_<version>_Windows_amd64.zip
Windows ARM64 topsail_<version>_Windows_arm64.zip

Linux binaries are built with CGO_ENABLED=0 and are fully static — they run unchanged on Alpine (musl), distroless, and scratch base images.

Verifying signatures

Each release includes a checksums.txt plus a cosign Sigstore bundle (checksums.txt.sigstore.json) that combines the signature, certificate, and Rekor inclusion proof. Verify with cosign v3+:

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/Real-Fruit-Snacks/topsail/.*' \
  --certificate-oidc-issuer    https://token.actions.githubusercontent.com \
  checksums.txt

Then verify your archive:

sha256sum -c checksums.txt --ignore-missing

Features

  • One static Linux binary. CGO_ENABLED=0 go build — runs unchanged on glibc, musl/Alpine, distroless, scratch.
  • Six-platform release. Linux / macOS / Windows × amd64 / arm64. Cross-compiled from a single CI job.
  • Microsecond startup. No interpreter spin-up; pipelines feel native.
  • Multi-call dispatch. Symlink topsail to any applet name, or copy the binary on Windows. Falls through to topsail <applet> [args] for unknown names.
  • Self-registering applets. Each applet is one Go package under applets/<name>/ plus one blank import in cmd/topsail/main.go. Registry is sync.RWMutex-protected and panics loudly on duplicate names.
  • Mockable I/O. internal/ioutil exposes Stdin/Stdout/Stderr as package vars; tests swap in bytes.Buffers without subprocess plumbing.
  • Cosign-signed releases with SBOMs. Each release ships keyless cosign signatures for checksums.txt and a syft-generated SBOM per archive.
  • govulncheck on every push and weekly cron. CodeQL static analysis on top of golangci-lint v2 (errcheck, gocritic, gosec, govet, revive, staticcheck, unparam, unused, ineffassign, misspell).

Supported applets

Category Applets
Foundation cat echo true false yes printf pwd basename dirname mkdir rmdir touch mv cp rm
POSIX text head tail wc tee tac rev tr cut sort uniq seq sleep expr test (also [) expand unexpand
Heavy text / FS grep (also egrep/fgrep) sed awk (also gawk/nawk) find ls stat file du df chmod chown which xargs date realpath truncate unlink mktemp
Archives & hashing / encoding tar gzip gunzip zip unzip sha256sum sha512sum md5sum base64 xxd
Network & JSON curl (also wget) jq host (also nslookup) ping
Process & system time timeout nproc
Coreutils gap-fillers env whoami id hostname uname ln readlink nl paste fold split factor shuf comm join sum column tsort

84 registered names across 74 packages. awk and jq embed benhoyt/goawk and itchyny/gojq respectively; everything else is built on the Go standard library.

Documented divergences from POSIX and from mainsail are listed in ARCHITECTURE.md.

Architecture

topsail boils down to four moving parts:

cmd/topsail/main.go        process entry; imports applet packages, calls cli.Run
   │
   ▼
internal/cli                argv[0] basename match; multi-call vs wrapper mode
   │
   ▼
internal/applet             registry: Register, Get, All; thread-safe; panics on dup
   │
   ▼
applets/<name>/             one package per applet; init() registers; Main is the entry

See ARCHITECTURE.md for the full applet contract, dispatch flow, cross-platform shims, build identification (-ldflags), and the documented divergence list.

Development

Setting up
git clone https://github.com/Real-Fruit-Snacks/topsail
cd topsail
make ci    # full local mirror of CI

You need:

  • Go 1.25 or later (the go.mod floor; bumped from 1.23 to pick up the GO-2026-4602 fix)
  • make (any flavor)
  • goimports, golangci-lint v2, govulncheck — installed via go install (see CONTRIBUTING.md)
Adding an applet
mkdir -p applets/myapplet
$EDITOR applets/myapplet/myapplet.go applets/myapplet/myapplet_test.go
$EDITOR cmd/topsail/main.go    # add one blank import
make ci

Full step-by-step in CONTRIBUTING.md. The smallest correct applet is ~25 lines.

Running the gauntlet
make fmt       # goimports -w
make vet       # go vet
make lint      # golangci-lint run
make test      # go test -cover
make test-race # go test -race -cover (requires CGO + a C toolchain)
make vuln      # govulncheck
make cross     # cross-compile to all six release targets
make ci        # everything above, in CI order

Why a Go port of mainsail?

mainsail is great when you want a single Python file you can chmod +x and run on any box that has CPython. topsail covers the cases mainsail can't:

  • Fully-static Linux binary. No interpreter, no shared libs. Works on Alpine (musl), distroless, scratch — none of which can host a Python zipapp.
  • One-machine cross-compile. GOOS=… GOARCH=… go build for all six platforms in one job; mainsail needs per-OS CI runners for native binaries.
  • Microsecond startup. No interpreter cold-start. Pipelines that spawn 1000 instances feel native.
  • One artifact story. Replaces mainsail's binary + zipapp split with a single self-contained executable.

The two share the same applet roster, the same flag conventions, and the same exit codes. Pick mainsail when you want to embed your own Python in a custom build; pick topsail when you want one binary that runs everywhere.

Contributing

See CONTRIBUTING.md for the contributor guide. Adding an applet is one new package under applets/<name>/ plus one blank import in cmd/topsail/main.go.

Reporting a security vulnerability? Use GitHub Security Advisories — see SECURITY.md.

This project follows the Contributor Covenant 2.1 Code of Conduct.

License

MIT.

About

topsail is the Go sibling in the same family as mainsail. Same applet contract, same dispatch UX, different runtime story.

Directories

Path Synopsis
applets
awk
Package awk implements the `awk` applet by embedding benhoyt/goawk.
 Package awk implements the `awk` applet by embedding benhoyt/goawk.
base64
Package base64 implements the `base64` applet: encode/decode RFC 4648.
 Package base64 implements the `base64` applet: encode/decode RFC 4648.
basename
Package basename implements the `basename` applet: strip directory and suffix.
 Package basename implements the `basename` applet: strip directory and suffix.
cat
Package cat implements the `cat` applet: concatenate files to stdout.
 Package cat implements the `cat` applet: concatenate files to stdout.
chmod
Package chmod implements the `chmod` applet: change file permission bits.
 Package chmod implements the `chmod` applet: change file permission bits.
chown
Package chown implements the `chown` applet: change file ownership.
 Package chown implements the `chown` applet: change file ownership.
column
Package column implements a minimal `column` applet: format input into columns.
 Package column implements a minimal `column` applet: format input into columns.
comm
Package comm implements the `comm` applet: compare two sorted files.
 Package comm implements the `comm` applet: compare two sorted files.
cp
Package cp implements the `cp` applet: copy files and directories.
 Package cp implements the `cp` applet: copy files and directories.
curl
Package curl implements a minimal `curl` applet (also registered as `wget`) for HTTP(S) GETs.
 Package curl implements a minimal `curl` applet (also registered as `wget`) for HTTP(S) GETs.
cut
Package cut implements the `cut` applet: extract sections from each line.
 Package cut implements the `cut` applet: extract sections from each line.
date
Package date implements the `date` applet: print or format the current time.
 Package date implements the `date` applet: print or format the current time.
df
Package df implements a minimal `df` applet: report filesystem usage.
 Package df implements a minimal `df` applet: report filesystem usage.
dirname
Package dirname implements the `dirname` applet: strip last component.
 Package dirname implements the `dirname` applet: strip last component.
du
Package du implements the `du` applet: estimate file space usage.
 Package du implements the `du` applet: estimate file space usage.
echo
Package echo implements the `echo` applet: write arguments to stdout.
 Package echo implements the `echo` applet: write arguments to stdout.
env
Package env implements the `env` applet: print or modify the environment.
 Package env implements the `env` applet: print or modify the environment.
expand
Package expand implements the `expand` applet: convert tabs in each FILE to the proper number of spaces.
 Package expand implements the `expand` applet: convert tabs in each FILE to the proper number of spaces.
expr
Package expr implements the `expr` applet: evaluate arithmetic and string expressions.
 Package expr implements the `expr` applet: evaluate arithmetic and string expressions.
factor
Package factor implements the `factor` applet: factor integers.
 Package factor implements the `factor` applet: factor integers.
false
Package falsecmd implements the `false` applet: do nothing, exit 1.
 Package falsecmd implements the `false` applet: do nothing, exit 1.
file
Package file implements a minimal `file` applet: detect file types by examining magic bytes and content.
 Package file implements a minimal `file` applet: detect file types by examining magic bytes and content.
find
Package find implements a minimal `find` applet: walk a directory tree and print or filter entries by name, type, and depth.
 Package find implements a minimal `find` applet: walk a directory tree and print or filter entries by name, type, and depth.
fold
Package fold implements the `fold` applet: wrap each line to width.
 Package fold implements the `fold` applet: wrap each line to width.
grep
Package grep implements the `grep` applet: search files for patterns.
 Package grep implements the `grep` applet: search files for patterns.
gzip
Package gzip implements the `gzip` and `gunzip` applets.
 Package gzip implements the `gzip` and `gunzip` applets.
head
Package head implements the `head` applet: output the first part of files.
 Package head implements the `head` applet: output the first part of files.
host
Package host implements a minimal `host` applet: DNS lookups via the system resolver.
 Package host implements a minimal `host` applet: DNS lookups via the system resolver.
hostname
Package hostname implements the `hostname` applet.
 Package hostname implements the `hostname` applet.
id
Package id implements the `id` applet.
 Package id implements the `id` applet.
join
Package join implements a simplified `join` applet: relational join of two files on a key field.
 Package join implements a simplified `join` applet: relational join of two files on a key field.
jq
Package jq implements the `jq` applet by embedding itchyny/gojq.
 Package jq implements the `jq` applet by embedding itchyny/gojq.
ln
Package ln implements the `ln` applet: create file links.
 Package ln implements the `ln` applet: create file links.
ls
Package ls implements a minimal `ls` applet.
 Package ls implements a minimal `ls` applet.
md5sum
Package md5sum implements the `md5sum` applet.
 Package md5sum implements the `md5sum` applet.
mkdir
Package mkdir implements the `mkdir` applet: make directories.
 Package mkdir implements the `mkdir` applet: make directories.
mktemp
Package mktemp implements the `mktemp` applet: create a unique temporary file or directory and print its path.
 Package mktemp implements the `mktemp` applet: create a unique temporary file or directory and print its path.
mv
Package mv implements the `mv` applet: move (rename) files.
 Package mv implements the `mv` applet: move (rename) files.
nl
Package nl implements a simplified `nl` applet: number lines.
 Package nl implements a simplified `nl` applet: number lines.
nproc
Package nproc implements the `nproc` applet: print the number of processing units available to the current process.
 Package nproc implements the `nproc` applet: print the number of processing units available to the current process.
paste
Package paste implements the `paste` applet: merge lines of files.
 Package paste implements the `paste` applet: merge lines of files.
ping
Package ping implements a `ping`-like applet using TCP probes.
 Package ping implements a `ping`-like applet using TCP probes.
printf
Package printf implements the `printf` applet: formatted output.
 Package printf implements the `printf` applet: formatted output.
pwd
Package pwd implements the `pwd` applet: print the working directory.
 Package pwd implements the `pwd` applet: print the working directory.
readlink
Package readlink implements the `readlink` applet.
 Package readlink implements the `readlink` applet.
realpath
Package realpath implements the `realpath` applet: print the resolved (absolute, symlink-free) path of each operand.
 Package realpath implements the `realpath` applet: print the resolved (absolute, symlink-free) path of each operand.
rev
Package rev implements the `rev` applet: reverse characters on each line.
 Package rev implements the `rev` applet: reverse characters on each line.
rm
Package rm implements the `rm` applet: remove files and directories.
 Package rm implements the `rm` applet: remove files and directories.
rmdir
Package rmdir implements the `rmdir` applet: remove empty directories.
 Package rmdir implements the `rmdir` applet: remove empty directories.
sed
Package sed implements a useful subset of `sed`: addresses, ranges, multi-command scripts, and the s/d/p/q commands.
 Package sed implements a useful subset of `sed`: addresses, ranges, multi-command scripts, and the s/d/p/q commands.
seq
Package seq implements the `seq` applet: print numeric sequences.
 Package seq implements the `seq` applet: print numeric sequences.
sha256sum
Package sha256sum implements the `sha256sum` applet.
 Package sha256sum implements the `sha256sum` applet.
sha512sum
Package sha512sum implements the `sha512sum` applet.
 Package sha512sum implements the `sha512sum` applet.
shuf
Package shuf implements the `shuf` applet: shuffle lines.
 Package shuf implements the `shuf` applet: shuffle lines.
sleep
Package sleep implements the `sleep` applet: pause for a duration.
 Package sleep implements the `sleep` applet: pause for a duration.
sort
Package sort implements the `sort` applet: sort lines of files.
 Package sort implements the `sort` applet: sort lines of files.
split
Package split implements a minimal `split` applet: split a file by lines.
 Package split implements a minimal `split` applet: split a file by lines.
stat
Package stat implements a minimal `stat` applet.
 Package stat implements a minimal `stat` applet.
sum
Package sum implements the legacy `sum` applet (BSD checksum).
 Package sum implements the legacy `sum` applet (BSD checksum).
tac
Package tac implements the `tac` applet: print files in reverse line order.
 Package tac implements the `tac` applet: print files in reverse line order.
tail
Package tail implements the `tail` applet: output the last part of files.
 Package tail implements the `tail` applet: output the last part of files.
tar
Package tar implements a minimal `tar` applet: create, extract, list.
 Package tar implements a minimal `tar` applet: create, extract, list.
tee
Package tee implements the `tee` applet: copy stdin to stdout and files.
 Package tee implements the `tee` applet: copy stdin to stdout and files.
test
Package test implements the `test` applet (and its `[` alias): the POSIX conditional-expression evaluator.
 Package test implements the `test` applet (and its `[` alias): the POSIX conditional-expression evaluator.
time
Package time implements the `time` applet: run a command and report how long it took.
 Package time implements the `time` applet: run a command and report how long it took.
timeout
Package timeout implements the `timeout` applet: run a command with a wall-clock deadline.
 Package timeout implements the `timeout` applet: run a command with a wall-clock deadline.
touch
Package touch implements the `touch` applet: change file timestamps.
 Package touch implements the `touch` applet: change file timestamps.
tr
Package tr implements the `tr` applet: translate, delete, or squeeze characters.
 Package tr implements the `tr` applet: translate, delete, or squeeze characters.
true
Package truecmd implements the `true` applet: do nothing, exit 0.
 Package truecmd implements the `true` applet: do nothing, exit 0.
truncate
Package truncate implements the `truncate` applet: shrink or extend a file to a specified size.
 Package truncate implements the `truncate` applet: shrink or extend a file to a specified size.
tsort
Package tsort implements the `tsort` applet: topological sort.
 Package tsort implements the `tsort` applet: topological sort.
uname
Package uname implements the `uname` applet: print system information.
 Package uname implements the `uname` applet: print system information.
unexpand
Package unexpand implements the `unexpand` applet: convert leading (or all) blank runs to tabs.
 Package unexpand implements the `unexpand` applet: convert leading (or all) blank runs to tabs.
uniq
Package uniq implements the `uniq` applet: filter adjacent duplicate lines.
 Package uniq implements the `uniq` applet: filter adjacent duplicate lines.
unlink
Package unlink implements the `unlink` applet: remove a single file via the unlink(2) system call.
 Package unlink implements the `unlink` applet: remove a single file via the unlink(2) system call.
wc
Package wc implements the `wc` applet: count lines, words, bytes, chars.
 Package wc implements the `wc` applet: count lines, words, bytes, chars.
which
Package which implements the `which` applet: locate a command in PATH.
 Package which implements the `which` applet: locate a command in PATH.
whoami
Package whoami implements the `whoami` applet.
 Package whoami implements the `whoami` applet.
xargs
Package xargs implements the `xargs` applet: build and execute commands from standard input.
 Package xargs implements the `xargs` applet: build and execute commands from standard input.
xxd
Package xxd implements the `xxd` applet: hex-dump or hex-revert.
 Package xxd implements the `xxd` applet: hex-dump or hex-revert.
yes
Package yes implements the `yes` applet: print a string repeatedly.
 Package yes implements the `yes` applet: print a string repeatedly.
zip
Package zip implements `zip` and `unzip` applets via archive/zip.
 Package zip implements `zip` and `unzip` applets via archive/zip.
cmd
gendocs command
Command gendocs writes shell completions and man pages for every registered applet to an output directory.
 Command gendocs writes shell completions and man pages for every registered applet to an output directory.
topsail command
Command topsail is the multi-call BusyBox-like binary entry point.
 Command topsail is the multi-call BusyBox-like binary entry point.
internal
applet
Package applet defines the contract every topsail applet implements and the registry used by the dispatcher to look them up by name or alias.
 Package applet defines the contract every topsail applet implements and the registry used by the dispatcher to look them up by name or alias.
applets
Package applets imports every applet package for side effects, so a binary that needs the full registry only needs to import this package instead of duplicating the per-package import list.
 Package applets imports every applet package for side effects, so a binary that needs the full registry only needs to import this package instead of duplicating the per-package import list.
cli
Package cli implements the multi-call dispatcher: argv[0] basename resolution, the topsail wrapper command, and global flags (--help, --version, --list).
 Package cli implements the multi-call dispatcher: argv[0] basename resolution, the topsail wrapper command, and global flags (--help, --version, --list).
filemode
Package filemode parses file mode strings — both octal (e.g.
 Package filemode parses file mode strings — both octal (e.g.
hashing
Package hashing provides shared logic for the md5sum / sha256sum / sha512sum applets.
 Package hashing provides shared logic for the md5sum / sha256sum / sha512sum applets.
ioutil
Package ioutil provides binary-safe, mockable wrappers around the process standard streams.
 Package ioutil provides binary-safe, mockable wrappers around the process standard streams.
platform
Package platform centralizes OS-specific behavior so applets stay portable.
 Package platform centralizes OS-specific behavior so applets stay portable.
testutil
Package testutil provides shared test helpers for topsail.
 Package testutil provides shared test helpers for topsail.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.