Skip to content

Getting started

Follow this guide to install babyctl, hook it up to Terraformer and kubectl, and run your first commands.

Prerequisites

  • Go 1.20+ for building from source.
  • kubectl in your $PATH for Kubernetes resource discovery.
  • terraformer (optional but recommended) for Terraform provider discovery.
  • A POSIX shell environment (macOS, Linux, or WSL2) with make.

Installation

make install
Installs the babyctl binary into $GOBIN (defaults to $(go env GOPATH)/bin).

go install ./cmd/babyctl
Produces the same binary without invoking the Makefile helpers.

After installing, ensure $GOBIN (or $GOPATH/bin) is on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Verifying the installation

babyctl version
babyctl api-resources | head

If Terraformer is present, you will see additional API groups (e.g. terraformer.aws/v0.8.30).

Bootstrapping discovery data

babyctl api-resources shells out to kubectl and Terraformer when available. To experiment without Terraformer you can use the sample discovery definitions that ship with the repo:

mkdir -p ~/.babyctl
cp -r examples/api-definitions/apis ~/.babyctl/

This enables the API server integration and provides a richer dataset for demos.

First commands

# List the merged resource catalog
babyctl api-resources

# Filter for Terraformer resources
babyctl api-resources --source terraformer

# Explain the schema for a resource
babyctl explain deployments

# Convert between formats
babyctl convert -f terraform.tf -oyaml

Applying configuration

babyctl apply intentionally mirrors kubectl:

# Apply a manifest from disk
babyctl apply -f infrastructure.yaml

# Apply from stdin (pairs well with Kustomize, Helm, or ytt)
kustomize build overlays/prod | babyctl apply -f-

Use babyctl diff before applying to preview the impact and babyctl edit for quick emergency changes. The current implementation targets the bundled babyctl.dev/v1alpha1 Widget resource when you run against the local API definitions (--path), and it honours $BABYCTL_EDITOR, $KUBE_EDITOR, $VISUAL, and $EDITOR (defaulting to vi).

Troubleshooting

  • Use babyctl --help or babyctl <command> --help to inspect flags.
  • Run with --v=4 (or higher) for verbose logs coming from Cobra and underlying helpers.
  • When Terraformer resources are missing, confirm terraformer is installed and on your PATH.
  • If the API server is not showing custom resources, ensure the files under ~/.babyctl/apis are well-formed and restart babyctl api-server.