{"slug": "what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli", "title": "What Really Happens When You Type tdk up: A Sequence Diagram of TDK CLI", "summary": "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.", "body_md": "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.\n\nThe 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.\n\n```\nsequenceDiagram\n    autonumber\n    actor Dev as Developer\n    participant Agent as AI agent over MCP\n    participant CLI as tdk CLI (TypeScript)\n    participant Host as Host and container runtime\n    participant Snap as Snapshots in .tdk-contract\n    participant Tilt as Tilt\n    participant Disc as Discovery (Starlark)\n    participant Eng as Engine generators (Starlark)\n    participant Dock as Docker\n    participant Svc as Service containers\n\n    Dev->>CLI: tdk up (or agent calls up)\n    Agent->>CLI: up (MCP tool runs tdk up --json)\n\n    CLI->>Host: check host type and container runtime\n    alt canUp is false\n        Host-->>CLI: no Docker, WebContainer, or Windows opt-in missing\n        CLI-->>Dev: exit non-zero, tell the reason, do not spawn Tilt\n    else canUp is true\n        CLI->>Snap: compare generated files with saved snapshots\n        alt a generated file was hand-edited\n            Snap-->>CLI: drift found, name the file\n            CLI-->>Dev: block the start, fix the source and retry\n        else no drift\n            CLI->>Tilt: spawn Tilt with the project Tiltfile\n            Tilt->>Disc: load service.json files\n            Disc-->>Tilt: resources, stacks, dependsOn\n            Tilt->>Eng: generate per-service runtime files\n            Eng-->>Tilt: write .autogenerated and service.yaml\n            Tilt->>Dock: build images, start containers in order\n            Dock->>Svc: start proxy, Postgres, services\n            Svc-->>Tilt: health route answers\n            Tilt-->>CLI: resources report ready or failed\n            CLI-->>Agent: ok true, or ok false with errors\n            CLI-->>Dev: TDK is up, with URLs and ports\n        end\n    end\n\n    Note over Agent,CLI: The agent polls status until readiness.ready is true\n    Agent->>CLI: status\n    CLI-->>Agent: readiness ready, pending, or failures\n    Dev->>CLI: tdk down\n    CLI->>Tilt: stop resources\n    Tilt->>Dock: stop and remove containers\n```\n\nFour steps can stop a start, and each one tells you something different.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\nAn 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.\n\n`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.\n\nOne `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.", "url": "https://wpnews.pro/news/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli", "canonical_source": "https://dev.to/tdk-cli/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli-ib4", "published_at": "2026-10-18 17:41:50+00:00", "updated_at": "2026-10-18 17:47:27.625659+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["TDK CLI", "Tilt", "Docker", "Starlark", "MCP", "Postgres"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli", "markdown": "https://wpnews.pro/news/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli.md", "text": "https://wpnews.pro/news/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli.txt", "jsonld": "https://wpnews.pro/news/what-really-happens-when-you-type-tdk-up-a-sequence-diagram-of-tdk-cli.jsonld"}}