Skip to content

Advanced

Advanced topics, optional features, and troubleshooting for Smurf v1.1.9.

AI-assisted error analysis

Several stf commands accept an --ai flag that sends error output to OpenAI for analysis and suggested fixes.

Setup:

export OPENAI_API_KEY=sk-your-key-here

Usage:

smurf stf plan --ai
smurf stf apply --ai --auto-approve
smurf stf validate --ai
smurf stf show --ai

When a command fails, Smurf can provide AI-generated context about the error. This is optional and requires a valid OpenAI API key.

Credential management

Smurf supports multiple credential sources, resolved in priority order:

  1. Environment variables
  2. smurf.yaml configuration fields
  3. Cloud provider CLI defaults (AWS CLI, gcloud, Azure CLI)
Provider Environment variables
AWS ECR AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION
Docker Hub DOCKER_USERNAME, DOCKER_PASSWORD
GHCR GITHUB_USERNAME, GITHUB_TOKEN
GCP GOOGLE_APPLICATION_CREDENTIALS, GCLOUD_PROJECT
Azure ACR AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID

See Configuration for the full field reference.

Debug mode

Enable verbose output for Helm operations:

smurf selm upgrade my-release ./chart --debug

Common issues

Docker daemon not running

Cannot connect to the Docker daemon

Ensure Docker is installed and the daemon is running. On Linux, add your user to the docker group or use sudo.

Helm release conflicts

Error: release already exists

Use --install with upgrade to handle existing releases:

smurf selm upgrade my-release ./chart --install

Terraform state lock

Error acquiring the state lock

Another process holds the state lock. Wait for it to finish, or use terraform force-unlock if the lock is stale.

Invalid version in GitHub Actions

Invalid version format. Expected format: vX.Y.Z

Pin the version with a v prefix:

with:
  version: v1.1.9

smurf.yaml not found

unable to read the file

Run smurf init in the working directory or pass values via CLI flags instead.

Architecture notes

Smurf is built with:

  • Cobra — CLI framework
  • pterm — terminal formatting
  • Docker SDK — container operations
  • Helm v3 SDK — Kubernetes chart management
  • terraform-exec — Terraform programmatic execution

Each subcommand group (sdkr, selm, stf) maps to an internal package that wraps the underlying tool's SDK or binary.

Contributing

Contributions are welcome. To get started:

  1. Fork the Smurf repository
  2. Create a feature branch
  3. Make your changes with tests where applicable
  4. Update documentation if behavior changes
  5. Open a pull request

Development setup

git clone https://github.com/clouddrove/smurf.git
cd smurf
go test ./...
go build -o smurf .

License

Smurf is licensed under the Apache License 2.0.

Support