What Really Happens When You Type tdk up: A Sequence Diagram of TDK CLI

A developer documented the execution sequence of TDK CLI's `tdk up` command, tracing the flow from host and container-runtime checks through a drift check against saved snapshots, Tilt startup, Starlark-based discovery and per-service file generation, Docker builds, and readiness reporting. The writeup identifies four points where a start can halt — a failed host check, hand-edited generated files, readiness failures, and a first failed resource that blocks dependents — and notes that `up` returns before the stack is ready, so agents calling the CLI over MCP must poll `tdk status --json` until readiness is true.

The first architecture diagram showed the parts of TDK CLI. This one shows time: what happens, in order, after you type tdk up . Knowing the order tells you where a start can stop, and which message to read when it does. The sequence below follows the repo's documented behaviour: the host check, the drift check before Tilt starts, the Starlark generation at Tilt load time, readiness, and the JSON result. Some steps are summarised, so check them against the code and the docs before you rely on one exact message. sequenceDiagram autonumber actor Dev as Developer participant Agent as AI agent over MCP participant CLI as tdk CLI TypeScript participant Host as Host and container runtime participant Snap as Snapshots in .tdk-contract participant Tilt as Tilt participant Disc as Discovery Starlark participant Eng as Engine generators Starlark participant Dock as Docker participant Svc as Service containers Dev- CLI: tdk up or agent calls up Agent- CLI: up MCP tool runs tdk up --json CLI- Host: check host type and container runtime alt canUp is false Host-- CLI: no Docker, WebContainer, or Windows opt-in missing CLI-- Dev: exit non-zero, tell the reason, do not spawn Tilt else canUp is true CLI- Snap: compare generated files with saved snapshots alt a generated file was hand-edited Snap-- CLI: drift found, name the file CLI-- Dev: block the start, fix the source and retry else no drift CLI- Tilt: spawn Tilt with the project Tiltfile Tilt- Disc: load service.json files Disc-- Tilt: resources, stacks, dependsOn Tilt- Eng: generate per-service runtime files Eng-- Tilt: write .autogenerated and service.yaml Tilt- Dock: build images, start containers in order Dock- Svc: start proxy, Postgres, services Svc-- Tilt: health route answers Tilt-- CLI: resources report ready or failed CLI-- Agent: ok true, or ok false with errors CLI-- Dev: TDK is up, with URLs and ports end end Note over Agent,CLI: The agent polls status until readiness.ready is true Agent- CLI: status CLI-- Agent: readiness ready, pending, or failures Dev- CLI: tdk down CLI- Tilt: stop resources Tilt- Dock: stop and remove containers Four steps can stop a start, and each one tells you something different. The host check. If canUp is false, the machine is the problem. No change to your project will help until the host has a working container runtime. The command exits without starting Tilt. The drift check. A hand edit to a file under .autogenerated/ blocks the start and names the file. The fix is upstream: change service.json or the generator, then start again. This check runs before Tilt is spawned, so nothing has been built yet. Readiness. up returns before the stack is ready, because a build can take longer than one command. The result tells you whether every resource is built, running, and healthy, or which one failed. tdk status --json answers the same question at any time. The first failed resource. A failure in one service usually stops the ones that depend on it. Read the logs for the first failed resource, not the last. tdk logs --json --service <name --tail 200 returns a bounded snapshot. An agent does not replace this sequence. It calls the same commands through the MCP server. The useful part for the agent is the loop: call up , poll status until ready, read logs for any failure, then stop. The sequence above shows why the poll is needed. up returns before readiness. tdk down reverses the lifecycle: Tilt stops the resources, and Docker removes the containers. Run it when you finish. A stack left running keeps its ports, and the next up may refuse to start while an old Tilt still answers on its port. One tdk up is a short chain of checks before any container starts: host, drift, then generation and readiness. Each check has its own message, and each message points at the fix. Read them in order, and most starts become a matter of reading the first line that failed.