Wand

Wand is a library to wrap Go functions as executable binaries. It supports:

• hierarchy of subcommands
• binding of command line options
• binding of environment variables
• binding of configuration entries
• positional arguments
• automatically generated help and documentation from go doc

Example:

package main

import (
	"strings"
	"code.squareroundforest.org/arpio/wand"
)

func main() {
	wand.Exec(strings.Split)
}

Lib docs:

• ./lib.go
• go docs html

wand tool

The wand tool helps with the following tasks:

• generating code from the go doc of the library that is converted into an executable binary by wand
• generating man (roff) or markdown documentation
• executing arbitrary Go functions in the command line addressed by their go path

Generating code with the docs of the wrapped library is particularly useful, because this way the automatically generated help can be based on the go docs. This is an important part of the attempt to achieve that ideal situation, where a solution to a problem is presented both as a library and a command line tool, and there is only a single place ("source of truth") of documentation.

Executing arbitrary Go functions in the command line is only a lucky side effect of the way wand was built. While it's not the primary function of the tool, it can be useful when just quickly trying out some Go functions or expressions, without having to create a throwaway main.go file.

wand tool installation

sudo make install

or in the current user's home:

prefix=~/.local make install

(See the recommended way below on how to use the locked version in the build tooling of a project.)

wand tool usage

Let's consider a project hierarchy where in the root we have a library (mylib), and in the ./cmd directory we have a main package, wrapping one or more functions of that library with wand as an executable binary:

./cmd/main.go
./lib.go

Generating the compiled docs from the go doc of a library:

wand docreflect mylib .

Generating a man page for the command:

wand manpages --date-string 2026-01-07 --version v1.0.0 ./cmd

wand tool bonus usage

wand --import strings strings.Split 1:2:3 :

wand tool docs

• ./cmd/wand/readme.md

When installed:

man wand

When not installed with man pages:

wand help

wand tool usage with go.mod version

When generating the docs for a shared project, we may want to ensure that the same version of wand is used for both docreflect and manpages in every environment. It is best to use the version that is defined in go.mod. This can be achieved using some trivial scripts. The example below shows docreflect:

package main

import (
	"code.squareroundforest.org/arpio/wand/tools"
	"log"
	"os"
)

func main() {
	if len(os.Args) < 2 {
		log.Fatalln("expected package name")
	}

	if err := tools.Docreflect(os.Stdout, os.Args[1], os.Args[2:]...); err != nil {
		log.Fatalln(err)
	}
}

and calling it, e.g. from a Makefile, with go run like:

go run script/gendocs.go mylib . gopath.to/me/mylib > docs.gen.go

---

Made in Berlin, DE