We’ve Used TDK CLI (Including Private Source) for 2 Years: Here’s Why You Need to Know

#automation #cli #devops #docker

Two years ago our team was drowning in local setup. Every new service meant another Dockerfile, another entry in a sprawling Compose file, another set of Traefik rules, another paragraph in the onboarding wiki, and another “it works on my machine” ticket. We adopted TDK CLI early—core MIT parts plus the private/premium source for the extra generators and registry features—and never went back.

TDK is simple in concept: one service.json per service becomes a full local Docker + Tilt stack. You run tdk up. Production stays on Helm. Local development does not require Kubernetes.

The Mental Model We Actually Use

flowchart TD
    A[service.json<br/>name, type, port, dependsOn, framework] --> B[tdk up]
    B --> C[Generated artifacts]
    C --> D[Dockerfile<br/>golden L1-L4 layers]
    C --> E[Tiltfile + live update]
    C --> F[Traefik routing]
    C --> G[Health checks + env wiring]
    D --> H[Docker containers]
    E --> H
    F --> H
    G --> H
    H --> I[Hot reload while you code]
    H --> J[Local domains<br/>*.localhost]

That single diagram captures 80 % of why the tool stuck. We stopped maintaining the wiring.

How the Hierarchy Scales

We organize everything as Project → Stack → Resource. After two years this still feels natural:

graph LR
    P[Project<br/>.tdk/project.json] --> S1[Stack: identity]
    P --> S2[Stack: orders]
    P --> S3[Stack: frontend]
    S1 --> R1[auth-api<br/>service.json]
    S1 --> R2[user-db<br/>Postgres]
    S2 --> R3[order-api]
    S2 --> R4[order-worker]
    S3 --> R5[web<br/>Vite + React]
    S1 -.->|dependsOn| S2

tdk up identity brings up only what we need. New services are discovered automatically. Phases (pre_alpha, alpha, beta) let us grow the system without starting everything every time.

Why the Two-Year Perspective Matters

Config debt stayed flat. Adding a service is still one service.json plus a short tdk resource command. The generated files are treated as a contract; we run tdk config verify in CI.
Onboarding collapsed. New engineers run tdk doctor, clone an example or our private template, then tdk up. The old multi-page wiki is gone. We still have domain knowledge to learn, but not the plumbing.
Hot reload is reliable. Tilt watches the code and live-updates containers. After the first image build, iteration is fast. Our 14–20 service stacks stay responsive on normal developer machines.
Private/premium pieces paid for themselves. We use the licensed generators, Verdaccio local registry, and a few extra scaffolding features. The core stays free and MIT; the paid parts removed work we were doing by hand. At roughly $19 per developer per month it was cheaper than the hours spent fighting Compose drift.
Local ≠ production, and that is intentional. We never tried to make Docker match the cluster. Production remains Helm/Argo. The separation is documented and enforced; it reduced the temptation to “just test in prod.”
Agent workflows fit naturally. Because topology and AGENTS.md are generated from the same manifests, coding agents can run tdk doctor and tdk up without inventing commands. We have been using the MCP server and skills for over a year.

Sequence We Follow Every Day

sequenceDiagram
    participant Dev
    participant TDK
    participant Docker
    participant Tilt
    Dev->>TDK: tdk doctor
    TDK-->>Dev: missing pieces or all clear
    Dev->>TDK: edit service.json
    Dev->>TDK: tdk up my-stack
    TDK->>TDK: generate / regenerate configs
    TDK->>Tilt: tilt up
    Tilt->>Docker: build & start in dependency order
    Docker-->>Tilt: healthy
    Tilt-->>Dev: URLs + live update ready
    Dev->>Dev: code
    Note over Tilt,Docker: file changes trigger live update

Honest Limits After Two Years

Windows developers still need WSL2 Ubuntu for full runtime; native Windows is inspection-only.
You must accept the generators. Heavy customization outside them creates drift that tdk config regenerate will overwrite.
Warm-start numbers are excellent once images exist; cold starts and heavy real-world dependencies still take minutes and memory. Plan capacity accordingly.
It is not magic if your existing Compose or Tilt setup already works well. We switched because ours did not.

Bottom Line

After two years of daily use—including private source features—TDK CLI removed the local-development tax that used to grow with every new service.

The manifest stays the single source of truth, Docker + Tilt do the running, and production stays where it belongs. If your team still spends days writing and maintaining local wiring, or if onboarding still requires a long wiki, this is the tool worth evaluating.

Start with the public example, measure it on your own services, and decide. For us the decision was obvious and has stayed obvious.

Top comments (2)

tdk-cli • Oct 19

Honest Limits After Two Years
Windows developers still need WSL2 Ubuntu for full runtime; native Windows is inspection-only.
You must accept the generators. Heavy customization outside them creates drift that tdk config regenerate will overwrite.
Warm-start numbers are excellent once images exist; cold starts and heavy real-world dependencies still take minutes and memory. Plan capacity accordingly.
It is not magic if your existing Compose or Tilt setup already works well. We switched because ours did not.

tdk-cli • Oct 19

nice!