Projects

initree

Repository · PyPI · Docs

Every universal scaffolder dies the same way. Someone wants Go instead of Python, GitLab instead of GitHub, Kubernetes instead of a VPS — and now there’s a template for every combination. N languages × M CI systems × K deploy targets. The grid explodes, the maintainer burns out, the project rots.

initree refuses that trade. It ships small independent layers — language, framework, container, ci, deploy, notify — and builds a project by composing them. Breadth costs N + M + K layers you add up, never N × M × K templates you maintain.

N × M × KN + M + K27 templates9 layersexample: 3 languages, 3 CI, 3 deploy targets
# same six slots, two completely different stacks
initree new api --recipe python+fastapi+docker+gh-actions+vps-ssh
initree new api --recipe go+gin+docker+gitlab-ci+k8s+slack

The capability bus

The composition only works because layers never call each other. They exchange data over a typed capability bus.

The deploy layer needs to know which port the container exposes. It does not ask Docker — it has never heard of Docker. It asks the bus for container.exposed_port, and whichever layer filled that slot provides it. So swapping docker → podman, or gh-actions → gitlab-ci, changes exactly one layer and touches nothing else.

That’s the whole design. Everything good about initree falls out of it, and every feature request that would have required two layers to know about each other got refused.

capability buslanguagepythongoframeworkfastapigincontainerdockercigh-actionsgitlab-cideployvps-sshk8snotify—slackcontainer.exposed_port

What a run produces

created ./myapp
  order: go -> gin -> docker -> k8s -> slack -> gitlab-ci
  + .gitignore
  + go.mod
  + cmd/server/main.go
  + internal/handler/handler.go
  + .dockerignore
  + Dockerfile
  + k8s/deployment.yaml
  + k8s/kustomization.yaml
  + k8s/service.yaml
  + .gitlab-ci.yml
  secrets: INITREE_SECRETS.md (provision before first deploy)

A working Go service, a multi-stage Dockerfile, Kubernetes manifests, a GitLab pipeline that builds and deploys, and a Slack notification on success — each written by a layer that knows nothing about the others. Note the resolved order: it’s derived from what each layer declares it needs, not from the order you typed.

the order you typedgogindockergitlab-cik8sslackgogindockerk8sslackgitlab-ciresolved: what each layer declares it needs

Secrets are a checklist, never a value

INITREE_SECRETS.md is built from the secret purposes the recipe’s layers declare. For the recipe above: registry credentials and a Slack webhook URL.

No secret value ever enters the build. The generated file tells you what to set in your CI store and why, before the first deploy. A scaffolder that prompts for a token and writes it somewhere is a scaffolder that eventually commits one.

Validation before prompting

initree new validates the composition first, then prompts for each layer’s inputs. It sounds like a small ordering detail, and it’s the difference between answering nine questions and then being told k8s and vps-ssh are incompatible, versus being told immediately.

Stack

Python, on PyPI, MIT. uv tool install initree or pipx install initree; uvx initree to try it without installing anything. CI on GitHub Actions, docs on GitHub Pages.