dockerctl

dockerctl is a command line client for docker REST API generated by go-swagger using docker engine open-api specification swagger.yaml. The command used to generate dockerctl:

# using cloned spec in this repo
$ swagger generate cli --target=. --spec=api/swagger.yaml

or

# using spec in docker engine repo directly
$ swagger generate cli --target=. --spec=https://raw.githubusercontent.com/docker/engine/master/api/swagger.yaml

dockerctl is a showcase for go-swagger's CLI (command line tool) generation capability, and is not intended to replace docker native CLI. Details of how to generate CLI using go-swagger, and more CLI features can be found here.

Install

go get -u github.com/go-swagger/dockerctl

Using dockerctl

Since docker is using unix socket instead of tcp, exposing it on tcp is needed. (We may support unix socket later.) For example, use socat to expose docker socket on localhost:12345, running in background:

$ socat TCP-LISTEN:12345,bind=127.0.0.1,reuseaddr,fork,range=127.0.0.0/8 UNIX-CLIENT:/var/run/docker.sock &

Note: exposing your docker socket like this is a security risk. In our development, we use docker-in-docker, running a dind on a private docker network, and then expose the socket in the private docker network. See Development page for more details.

Example

Equivalent of docker image ls:

$ dockerctl --hostname=localhost:12345 image ImageList
[{"Containers":-1,"Created":1616710788,"Id":"sha256:d1bb6234ef26de7a1976176b36eb0f518b3d3d9e6a46e2da2ae6eb0b4d99d87d","Labels":null,"ParentId":"","RepoDigests":["alpine@sha256:f2fa517acf6123318bc893c411f34570cea193367b33bd3be1d90c7fbefe72a5"],"RepoTags":["alpine:3.10.7"],"SharedSize":-1,"Size":5576298,"VirtualSize":5576298}]

Shell Completion

Generate auto completion for bash, zsh, fish or PowerShell. Bash example:

# temporary completion in current shell
$ source <(dockerctl completion bash)
# add completion permanently to your system
$ dockerctl completion bash > /etc/bash_completion.d/dockerctl

Example of completion:

$ dockerctl <tab> <tab>
completion    container     exec          image         node          secret        session       system        volume        
config        distribution  help          network       plugin        service       swarm         task 

Use Config File

Use config file to avoid passing hostname and scheme in every command. Values in config file will be used in command line flag are not set. Default config file path is cat $HOME/.config/<CLI exe name>/config.yaml. One can also set config file name by using --config flag.

$ cat $HOME/.config/dockerctl/config.yaml
hostname: "localhost:12345"
scheme: http

Using config file, the docker image ls command becomes:

dockerctl image ImageList

Dev MISC

go-swagger commit used: 45b969382a41474fda96a24dde7bc768023a5b83