Tilt — Kubernetes Dev Toolkit
Tilt automates the local Kubernetes development loop: watch files, build images, deploy to cluster. Configuration lives in a Tiltfile (Starlark, a Python dialect). A resource bundles an image build + k8s deploy (or a local command) into a single manageable unit.
CLI Operations
The commands an agent uses to interact with a running Tilt instance.
Lifecycle
| Task | Command |
|---|---|
| Start dev environment | tilt up [-- <Tiltfile args>] |
| Start with terminal log streaming | tilt up --stream |
| Start specific resources only | tilt up frontend backend |
| Run in CI/batch mode (exits on success/failure) | tilt ci --timeout 30m |
| Stop and delete deployed resources | tilt down |
| Change runtime Tiltfile args | tilt args -- --flag value |
| Change runtime args (clear all) | tilt args --clear |
On Ctrl+C from tilt up: K8s and Docker Compose resources keep running. Local serve_cmd processes stop. Use tilt down to clean up.
Viewing Logs
| Task | Command |
|---|---|
| Stream all logs | tilt logs -f |
| Stream logs for one resource | tilt logs -f <resource> |
| Show only errors | tilt logs --level error |
| Show build logs only | tilt logs --source build |
| Show runtime logs only | tilt logs --source runtime |
| Logs since 5 minutes ago | tilt logs --since 5m |
| Last 100 lines | tilt logs --tail 100 |
| JSON output (for parsing) | tilt logs --json |
Resource Management
| Task | Command |
|---|---|
| List all resources | tilt get uiresources |
| Resource status as JSON | tilt get uiresources -o json |
| Describe a resource in detail | tilt describe uiresource <name> |
| Force rebuild a resource | tilt trigger <resource> |
| Enable a disabled resource | tilt enable <resource> |
| Disable a resource | tilt disable <resource> |
| Wait for resource readiness | tilt wait --for=condition=Ready uiresource/<name> |
Inspection & Debugging
| Task | Command |
|---|---|
| Diagnostics (versions, cluster) | tilt doctor |
| Inspect file watches | tilt get filewatches |
| Describe a specific file watch | tilt describe filewatch <name> |
| Full engine state dump (JSON) | tilt dump engine |
| Full UI state dump | tilt dump webview |
| Test Docker build as Tilt would | tilt docker -- build <args> |
| List API resource types | tilt api-resources |
The Tilt API server runs on localhost:10350 by default. All tilt get/describe/trigger commands talk to it.
Build Strategy Selector
| Situation | Function | Key detail |
|---|---|---|
| Standard Dockerfile | docker_build(ref, context) | Watches context dir, auto-injects into k8s |
| Custom toolchain (Bazel, ko, Buildpacks) | custom_build(ref, cmd, deps) | Must tag with $EXPECTED_REF env var |
| Non-Docker builder (Buildah, kaniko) | custom_build(..., skips_local_docker=True) | Builder handles push independently |
| Docker Compose services | docker_compose(configPaths) | Manages compose lifecycle |
| Helm charts | k8s_yaml(helm('./chart')) | Renders locally, deploys to cluster |
| Kustomize overlays | k8s_yaml(kustomize('./overlay')) | Renders locally, deploys to cluster |
Live Update Decision Tree
Live update replaces full image rebuilds with in-place container file syncs — seconds instead of minutes.
| Step | Purpose | Ordering |
|---|---|---|
fall_back_on(files) | Force full rebuild when these files change | Must come first |
sync(local, remote) | Copy changed files into running container | After fall_back_on |
run(cmd, trigger=files) | Execute command in container (e.g., install deps) | After sync |
restart_container() | Restart the container process | Must come last |
docker_build('myapp', '.', live_update=[
fall_back_on(['requirements.txt']),
sync('./src', '/app/src'),
run('pip install -r requirements.txt', trigger=['requirements.txt']),
])
When live update breaks: Changes to files outside the docker_build context trigger a full rebuild. Changes outside any sync() path also trigger a full rebuild. First tilt up always does a full build — live update requires a running container.
Resource Configuration
# Kubernetes resource with port forwarding and dependencies
k8s_resource('frontend',
port_forwards=['3000:3000'],
resource_deps=['api', 'database'],
labels=['web'],
trigger_mode=TRIGGER_MODE_MANUAL,
)
# Local resource (build tool, test runner, code generator)
local_resource('codegen',
cmd='make generate',
deps=['./proto'],
labels=['tools'],
)
# Local server (runs continuously)
local_resource('storybook',
serve_cmd='npm run storybook',
deps=['./src/components'],
allow_parallel=True,
readiness_probe=probe(http_get=http_get_action(port=6006)),
)
Parallelism: Local resources run serially by default. Set allow_parallel=True for independent resources. Image builds default to 3 concurrent — adjust with update_settings(max_parallel_updates=N).
Dependencies: resource_deps gates on first-ever readiness only — once a dependency is ready once, dependents unlock permanently for that session.
Debugging Flow
Service crashing? → tilt logs -f <resource> --source runtime
Build failing? → tilt logs -f <resource> --source build
tilt docker -- build <args> (reproduces Tilt's exact build)
Wrong files rebuild? → tilt get filewatches
tilt describe filewatch <name>
Check .tiltignore, watch_settings(ignore=), ignore= param
Force a rebuild? → tilt trigger <resource>
Resource stuck? → tilt describe uiresource <name>
Check resource_deps chain
For CRDs: pod_readiness='ignore'
General diagnostics? → tilt doctor
Full state dump? → tilt dump engine | jq .
Top 10 Pitfalls
| Pitfall | Fix |
|---|---|
local() calls don't track file deps | Wrap with read_file() or add watch_file() |
| Live update paths outside docker_build context | Ensure sync local paths fall within context dir |
| Local resources block each other | Set allow_parallel=True on independent resources |
resource_deps doesn't re-gate on updates | It only checks first-ever readiness, not current version |
| Starlark has no while/try-except/class/recursion | Use for loops, fail() for errors, dicts for state |
.tiltignore doesn't affect Docker build context | Use .dockerignore to exclude from both rebuild triggers AND context |
$EXPECTED_REF not used in custom_build | Build script MUST tag the image with this env var |
run() trigger files not in a sync() step | Trigger paths must also be covered by a sync step |
First tilt up always does full build | Live update cannot work until a container is running |
| CRD pods stuck in pending | Set pod_readiness='ignore' on CRD resources |
Additional Resources
Reference Files
For detailed API signatures and advanced patterns, consult:
references/api-reference.md— Complete Tiltfile API catalog organized by category, Starlark language notes, ignore mechanism comparisonreferences/patterns.md— Multi-service architectures, environment config, CI integration, performance optimization, programmatic Tilt interaction, extension ecosystem