Writing a Docker plugin

Do you have Bash functions for Docker tasks like cleanup or maintenance? Why not turn them into a Docker cli plugin and make them feel like first-class Docker commands?

Let’s take this Bash alias:

function docker_clean() {
    echo "Cleaning up Docker resources..."
    docker system prune -f
    docker volume prune -f
    docker network prune -f
}

Simple and useful, but what if we could run this like a native command?

docker clean

That’s the magic of Docker cli plugins! Let’s convert that bash snippet into a powerful, user-friendly “native” Docker plugin.

🚀 Step-by-Step: Create a Docker plugin

1 - File structure: Docker plugins live in your $HOME/.docker/cli-plugins/ and are named like docker-<COMMAND>. For example:

 ~/.docker/cli-plugins/docker-clean

2 - Make it executable:

chmod +x ~/.docker/cli-plugins/docker-clean

3 - Add plugin metadata: Docker requires your cli plugins to provide metadata when executed with a special command-argument docker-cli-plugin-metadata. So, we must handle that argument and return the Docker metadata to describe our plugin:

docker_cli_plugin_metadata() {
  cat <<EOF
{
  "SchemaVersion": "0.1.0",
  "Vendor": "Jorge F. Sánchez",
  "Version": "1.0.0",
  "ShortDescription": "Clean up Docker resources (containers, images, volumes, networks)"
}
EOF
  exit 0
}

✅ Full Example: docker-clean

#!/bin/bash

# docker-clean: Clean up Docker resources
# Usage: docker clean [--full] [--dry] [--help|-h]

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

DRY_RUN=false
FULL=false

show_help() {
  echo -e "${GREEN}docker clean${NC} - Clean up Docker resources"
  echo
  echo -e "Usage: ${YELLOW}docker clean [--full] [--dry] [--help|-h]${NC}"
  echo
  echo "Options:"
  echo "  --full        Run a full cleanup (containers, images, volumes, networks)"
  echo "  --dry         Show what would be executed without actually running it"
  echo "  --help, -h    Show this help message"
  exit 0
}

docker_cli_plugin_metadata() {
  cat <<EOF
{
  "SchemaVersion": "0.1.0",
  "Vendor": "Jorge F. Sánchez <mail@jfsanchez.net>",
  "Version": "1.0.0",
  "ShortDescription": "Clean up Docker resources (containers, images, volumes, networks)"
}
EOF
  exit 0
}

# Argument parsing
for arg in "$@"; do
  case $arg in
    docker-cli-plugin-metadata)
      docker_cli_plugin_metadata
      ;;
    clean)
      continue
      ;;
    --full)
      FULL=true
      ;;
    --dry)
      DRY_RUN=true
      ;;
    --help|-h)
      show_help
      ;;
    *)
      echo -e "${RED}❌ Unknown option: $arg${NC}"
      echo "Run ${YELLOW}docker clean --help${NC} for usage."
      exit 1
      ;;
  esac
done

# Utility functions
dry_echo() {
  echo -e "${YELLOW}[DRY-RUN] Would run: $*${NC}"
}

run() {
  if [ "$DRY_RUN" = true ]; then
    dry_echo "$@"
  else
    eval "$@"
  fi
}

regular_clean() {
  echo -e "${YELLOW}🧹 Docker cleanup...${NC}"
  run "docker container prune -f"
  run "docker image prune -f"
  run "docker network prune -f"
  run "docker volume prune -f"
  echo -e "${GREEN}✅ completed.${NC}"
}

full_clean() {
  echo -e "${RED}🧨 Full Docker cleanup...${NC}"
  run "docker system prune -a --volumes -f"
  echo -e "${GREEN}✅ completed.${NC}"
}

# Main execution
if [ "$FULL" = true ]; then
  full_clean
else
  regular_clean
fi

💡 Bonus Tips

• Discoverability: docker clean --help just works!

• Extensibility: Add more parameters like docker clean --images-only

📦 Summary

With just a bit of structure and metadata, your Bash utilities can become native-feeling Docker commands. It's an elegant way to level up your cli tools while keeping everything simple and transparent.

🙋 Need ideas for your own Docker plugin? Try automating:

• Container log backups

• Image size audits

• Network inspections