Smurf: one CLI for Docker, Helm, Kubernetes and Terraform

AI-assisted DevOps CLI that wraps Docker, Helm and Terraform behind one interface, with error diagnosis that runs free and offline against a local model, or against any OpenAI-compatible provider with your own key.

Smurf is a Go CLI that wraps Docker, Helm, Kubernetes and Terraform behind one consistent interface, using each tool's native Go SDK instead of shelling out. One binary, one config file, unified commands: build and push images to any major registry, install and upgrade Helm releases, plan and apply Terraform, or chain the whole pipeline with a single smurf deploy. When something fails, --ai explains why in plain terms, and in GitHub Actions the cause is published to the job summary rather than buried in the log. Less context switching, fewer one-off scripts, the same commands locally and in CI.

brew tap clouddrove/homebrew-tap
brew install smurf

Downloads the release archive for your OS/arch and verifies it against checksums.txt:

curl -fsSL https://raw.githubusercontent.com/clouddrove/smurf/master/install/install.sh | bash

The image bundles smurf together with docker-cli, aws-cli, gcloud, terraform, and trivy:

docker run --rm ghcr.io/clouddrove/smurf:latest version

go install github.com/clouddrove/smurf@latest

Grab the archive for your platform from the releases page, verify it against checksums.txt, and put the binary on your PATH.

    - name: Setup Smurf
      uses: clouddrove/smurf@v1.1.5

Smurf is available as an Azure DevOps Marketplace extension. Extension source and release notes live in azure-devops-extension.

steps:
  - task: Smurf@1
    displayName: Setup Smurf
    inputs:
      version: latest
      command: ""

  - script: smurf stf plan
    displayName: Terraform plan

You can also run a single Smurf command directly through the task:

steps:
  - task: Smurf@1
    inputs:
      version: latest
      command: stf plan

See the installation guide for building from source and platform notes.

# Scaffold a smurf.yaml with both sdkr and selm sections (0600, refuses to overwrite)
smurf init

# Build the Docker image described in smurf.yaml
smurf sdkr build

# Build, push, and (if selm.deployHelm is true) install/upgrade the Helm release, all from smurf.yaml
smurf deploy

smurf completion <bash|zsh|fish|powershell> generates a completion script for your shell (smurf completion --help for the full list and per-shell install instructions). Where it makes sense, completion is dynamic: Helm release-name arguments (selm upgrade/uninstall/status/history/rollback), --namespace/-n flags, and stf state-rm resource addresses complete against your current cluster/state instead of just showing static hints. If the cluster or backend isn't reachable, these simply produce no suggestions rather than erroring.

# zsh, current session
source <(smurf completion zsh)

# bash, current session
source <(smurf completion bash)

See the installation guide for persisting completion across shell sessions on bash/zsh/fish/PowerShell.

Streamline Docker image workflows:

• build, scan, tag, push, remove, init
• provision-acr/provision-ecr/provision-gcp/provision-ghcr/provision-hub → each runs (build ➝ push), prompting Proceed with push? [y/N] on a TTY unless --yes is passed
• Docker with Smurf – Usage Guide

Simplify Helm operations:

• create, install, lint, list, status, template, upgrade, uninstall, init, debug, plugin
• provision → runs (install ➝ upgrade ➝ lint ➝ template)
• Helm with Smurf – Usage Guide

Easily manage Terraform workflows:

• init, plan, apply, output, drift, validate, destroy, fmt, show, import, refresh, graph, state-list, state-rm, state-push, state-pull
• provision → runs (init ➝ plan ➝ apply ➝ output); applying requires --auto-approve (default false)
• Terraform with Smurf – Usage Guide

Reads smurf.yaml, builds the Docker image, pushes it to whichever registry is enabled, and (if selm.deployHelm is true) installs or upgrades the Helm release.

• deploy → runs (build ➝ push ➝ Helm install/upgrade), controlled by --timeout (seconds, default 600)

Add --ai to any command. When it fails, the error is explained in place: what went wrong, and what to check first.

$ smurf selm upgrade api ./chart --namespace prod --ai

🔍 ROOT CAUSE
- Image ghcr.io/acme/api:v2.3.1 does not exist in the registry.

📋 STEPS TO RESOLVE
1. Verify the image tag was published
2. Correct the image reference in your values
3. Re-run the upgrade

Point smurf at a local model and it costs nothing, needs no key, and sends nothing off the machine:

export OPENAI_BASE_URL=http://localhost:11434/v1   # Ollama
export OPENAI_MODEL=llama3.2
smurf stf apply --ai

Any OpenAI-compatible endpoint works, which is nearly all of them:

Before anything is sent, tokens, keys and password=/token=/secret= values are redacted from the error text. Responses are cached on disk, so a pipeline re-run does not pay for the same explanation twice.

In Actions the useful line is usually hundreds of lines up the log. smurf publishes the cause to the job summary instead, so it is the first thing on the run, and attaches an annotation that also shows on the pull request.

## ❌ Helm upgrade failed

**Release:** `api`  **Namespace:** `prod`

| Pod | Status | Reason |
|---|---|---|
| `api-7d9f` | ImagePullBackOff | image ghcr.io/acme/api:v2.3.1 does not exist in the registry |
| `api-7d9g` | Pending | no node can satisfy the pod's cpu, memory or placement requirements |

Nothing is printed differently in a terminal; the extra output appears only inside Actions.

smurf selm upgrade waits for the release to become ready and fails if it does not, within --timeout. A pod that cannot pull its image, cannot be scheduled, or crashes on start is a failed upgrade rather than a warning, so a broken deploy does not pass as a green job.

Use --skip-verify for a deliberate fire-and-forget rollout.

Smurf supports automatic credential fallback.
If required credentials (like username or token) are not provided via CLI or environment variables, Smurf will read them directly from your smurf.yaml file. Values also support ${ENV_VAR} interpolation.

See the full smurf.yaml field reference for every supported key.

sdkr:
  awsECR: false
  dockerHub: false
  ghcrRepo: false
  dockerfile: ""
  imageName: ""
selm:
  chartName: ""
  deployHelm: true
  fileName: ""
  namespace: ""
  releaseName: ""
  revision: 0

Push images to multiple registries from one CLI:

• Supported: AWS ECR, GCP GCR, Azure ACR, Docker Hub
• Example:

  smurf sdkr push --help

Big thanks to our contributors for elevating our project with their dedication and expertise! But, we do not wish to stop there, would like to invite contributions from the community in improving these projects and making them more versatile for better reach. Remember, every bit of contribution is immensely valuable, as, together, we are moving in only 1 direction, i.e. forward.

Want to contribute? Read CONTRIBUTING.md for the development setup, project layout, and pull request conventions, and SECURITY.md for how to report vulnerabilities privately.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Spot a bug or have thoughts to share with us? Let's squash it together! Log it in our issue tracker, feel free to drop us an email at hello@clouddrove.com.

Show some love with a ★ on our GitHub! if our work has brightened your day! – your feedback fuels our journey!

Join our vibrant open-source slack community and embark on an ever-evolving journey with CloudDrove; helping you in moving upwards in your career path. Join our vibrant Open Source Slack Community and embark on a learning journey with CloudDrove. Grow with us in the world of DevOps and set your career on a path of consistency.

🌐💬What you'll get after joining this Slack community:

• 🚀 Encouragement to upgrade your best version.
• 🌈 Learning companionship with our DevOps squad.
• 🌱 Relentless growth with daily updates on new advancements in technologies.

Join our tech elites Join Now 🚀

We provide a platform for organizations to engage with experienced top-tier DevOps & Cloud services. Tap into our pool of certified engineers and architects to elevate your DevOps and Cloud Solutions.

At CloudDrove, has extensive experience in designing, building & migrating environments, securing, consulting, monitoring, optimizing, automating, and maintaining complex and large modern systems. With remarkable client footprints in American & European corridors, our certified architects & engineers are ready to serve you as per your requirements & schedule. Write to us at business@clouddrove.com.

We are The Cloud Experts!

We ❤️ Open Source and you can check out our other modules to get help with your new Cloud ideas.