@tdk-landscape/tdk-cli-core

TDK CLI — start services on your laptop

English | 简体中文 | 繁體中文 | 日本語 | 한국어

TDK CLI starts your services on your laptop. It is not a deploy and not a Compose file: define each service in service.json, then run tdk up. No Kubernetes is needed on the machine.

Stability: 1.x local dev. Generated files are a contract; verify with tdk config verify. Core CLI is MIT and needs no key. Premium is optional.

Docker runs the containers. Tilt watches services and live-updates containers while you code. TDK CLI writes the configuration Tilt uses. Production deployment stays with Helm, Argo CD, or Kustomize.

Website · Quickstart · Examples · Awesome TDK · Demo · Report a bug

Who uses TDK

No teams are listed yet. Be the first: tell us you use TDK or add a row to ADOPTERS.md.

Quick start

mkdir shop && cd shop
tdk project --yes
tdk resource orders-api --type backend --stack shop --yes
tdk up shop
curl http://api.shop.localhost/api/orders-api/health

Scaffolding a backend and frontend, then listing the stack.

If Helm, Compose, or your existing Tilt setup already gives you a working local environment, keep using it. TDK CLI is for engineers managing several services who want a clear local service contract and one command to start the stack.

See how TDK CLI works alongside Helm, the service schema, and the project configuration schema.

Installation

Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):

npm install -g @tdk-landscape/tdk-cli-core
# or install the prebuilt binary
curl -fsSL https://tdk-landscape.github.io/install.sh | sh

tdk up shop --dry-run previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; TDK's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the one-backend example.

When not to use TDK

• Your existing Compose or Tilt workflow already gives you a working local environment.
• Helm is your whole development workflow and you do not want local services on Docker.
• You do not want service.json manifests and generated local configuration.

Docs

• Documentation index
• Pilot TDK on a real repository
• FAQ for agencies and multi-client teams
• Working alongside Helm
• Scope: local development, and what does not carry over to production
• Gradual adoption: adding TDK to an existing repository
• Troubleshooting: tdk and Tilt error messages and their fixes
• Layout and ownership: services in several repositories
• Local data: reset, seed, snapshot
• Upgrading and version pinning
• Security: network calls, secrets and supply chain
• Pilot scorecard
• Bring-your-own resources
• Configuration and editor schemas
• Runnable one-backend example
• Runnable Python backend example
• Full multi-service example
• Features and license limits
• Honest comparison and known limits
• Public claims registry
• Show HN draft
• Architecture and repository map
• Scale fixture measurements and caveats

History

TDK is older than this repository and its npm package suggest. Development started on 21 April 2026 in tdk-landscape/tdk, now archived and kept as read-only history; its first commit is 1714637 ("Initial commit: TDK specs, generators, CLI, and standards"). This repository, tdk-cli-core, was created on 19 September 2026 and is where development continues; the @tdk-landscape/tdk-cli-core package on npm was first published on 21 September 2026. So the code lineage is about five months older than the repository and package dates that you will see on GitHub and npm.

Requirements and support

For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20+) and Tilt. Bun 1.2+ is used by the default generated services. TDK selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to override them. TDK supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run tdk doctor to check local readiness. See WSL2 setup.

On native Windows, tdk --version, tdk doctor, and tdk up --dry-run are inspect-only commands. tdk up exits 2 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”

License matrix

Capability	Free	Premium
tdk up, scaffold, Traefik, Postgres, Tilt live update, golden layers	yes	yes
Verdaccio, DDD scaffold, Sablier idle stop	no	key
Playwright, C4, AGENTS.md	free if generated in-repo	only if the implementation is downloaded with a key

Core stays free. Premium is a separate key for the extras above; no key required to run tdk up.

Ecosystem map: examples, articles, related tools, and notes live in awesome-tdk-framework. Star this repo (tdk-cli-core) if the CLI is what you run; use the awesome list to browse the rest.

Contributing and license

Contributions are welcome. Start with CONTRIBUTING.md and the contributor guide. Report security issues using SECURITY.md.

TDK is MIT-licensed; see LICENSE. The license boundary says which code is MIT and which is downloaded with a key.

Project governance: GOVERNANCE.md, MAINTAINERS.md, ADOPTERS.md.