Shell interpreter for docopt, the command-line interface description language.
Go Shell Python Makefile
Switch branches/tags
Nothing to show
Clone or download
Sylvain303 docopts go version merge (#13)
After many years, this is the first alpha release merge.

A totally rewrite of the python's code in go.
This is a transitional version for passing from python to go.

Please report issue, they will be fixed!
Latest commit 031ceb2 Jun 18, 2018


docopt for shell - make beautifull CLI with ease.

Status: Alpha - work is done.

This is the golang version of docopts : the command line wrapper for bash.

See the Reference manual for how to use docopts old README.rst.

This is a transitional release: 0.6.2

This release will be maintained for compatibity, only fix will be provided.

The develop branch is abandoned!

The current go version is 100% compatible with python's docopts. Please report any non working code with issue and examples.

A new shell API is proposed

Starting at release: 0.7.0 a new lib API based on JSON will be introduced:

See and contribute on the docopts Wiki.


You only have to drop the binary, and eventually the lib helper, in your PATH. The binary is standalone and staticaly linked. So it runs everywhere.

See build section.

With root privileges you could:

cp docopts /usr/local/bin

pre-built binary

Pre-built binary are attached to releases.

Download and rename it as docopts and put it in your PATH.

mv docopts-32bit docopts
cp docopts /usr/local/bin

You are strongly encouraged to build your own binary. Find a local golang developper in whom you trust and ask her, in exchange of a beer or two, if she could build it for you. ;)


See manual and Examples


With a go workspace.

local build

go get
go get
cd src/
go build docopts.go

cross compile for 32btis

env GOOS=linux GOARCH=386 go build docopts.go

or via Makefile (generate 64bits, 32bits, arm and OSX-64bits version of docopts)

cd src/
make all
make test

Tested built on: go version go1.10.2 linux/amd64


Warning: may be not up-to-date feature list.

The is an extra bash library that you can source in your CLI script. This library provides some bash helpers and is not required in order to use docopts.

You don't need a python interpreter anymore, so it works on any legacy system.

As of 2018-05-22

  • docopts is able to reproduce 100% of the python version.
  • unit test for go are provided, so hack as you wish.
  • 100% passed (GNU/Linux 64bits)


All python related stuff has been removed, excepted

If you want to clone this repository and hack docopts:

Use git clone --recursive, to get submodules only required for testing with bats. bats or bats-core installed in your PATH should work too.

Fetch the extra golang version of docopt-go (required for building docopts)

go get

If you forgot --recursive, you can also run it afterward:

git submodule init
git submodule update

Current folder structure:

├── docopts.go - main source code
├── docopts_test.go - go unit tests
├── - library wrapper and helpers
├── examples - many ported examples in bash, all must be working
├── - old python JSON tester still used with
├── old_README.rst - copied README
├── PROGRESS.mda - what I'm working on
├── testcases.docopt - agnostic testcases copied from python's docopt
├── - bash wrapper to convert docopts output to JSON (now use
├── tests - unit and functional testing written in bats (require submodule)
└── - Some todo list on this golang version of docopts


Some tests are coded along this code base.

  • bats bash unit tests and functionnal testing.
  • (old python wrapper, full docopt compatibily tests)
  • See Also: docopt.go own tests in golang.
  • docopts_test.go go unit test for docopts.go

Runing tests

make test


cd ./tests
. bats.alias
bats .


This script was provided with the original docopts. I fixed number/string output parsing failure with an extra function for bash in docopt_get_raw_value(). This is a hack to get 100% pass, and it is not very efficient.

python ./

golang docopt.go (golang parser lib)

This lib is outside this project, but it is the base of the docopt parsing for this wrapper.

cd PATH/to/go/src/
go test -v .

golang docopts (our bash wrapper)

go test -v