Tilt Cheat Sheet

Overview

Tilt is a development environment tool for teams building microservices on Kubernetes. It watches files, rebuilds containers, and updates running services in real-time. Tilt provides a web-based dashboard showing build status, logs, and resource health across all your services, making it easy to develop multi-service applications.

Tilt uses a Starlark-based configuration file (Tiltfile) that defines how to build, deploy, and manage services. It supports smart rebuilds that sync only changed files rather than rebuilding entire containers, live_update for sub-second code reload, and extensible functions for custom workflows.

Installation

# macOS
brew install tilt-dev/tap/tilt

# Linux
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash

# Windows
scoop install tilt

# Go install
go install github.com/tilt-dev/tilt/cmd/tilt@latest

# Verify
tilt version

Core Commands

Command	Description
tilt up	Start Tilt (builds, deploys, watches)
tilt down	Tear down all resources
tilt ci	Run in CI mode (exits on completion)
tilt demo	Run the demo project
tilt logs	Stream logs from all services
tilt get	Get resource status
tilt trigger <name>	Manually trigger a resource update
tilt disable <name>	Disable a resource
tilt enable <name>	Enable a resource
tilt doctor	Diagnose common issues

Tiltfile Configuration

Basic Tiltfile

# Tiltfile

# Build a Docker image
docker_build('my-app', '.',
  dockerfile='Dockerfile',
  build_args={'NODE_ENV': 'development'})

# Deploy Kubernetes manifests
k8s_yaml('k8s/deployment.yaml')

# Set up port forwarding
k8s_resource('my-app', port_forwards='8080:8080')

Live Update (Hot Reload)

# Tiltfile with live_update for fast iteration
docker_build('my-app', '.',
  live_update=[
    # Sync changed files to container
    sync('./src', '/app/src'),
    sync('./package.json', '/app/package.json'),

    # Run npm install when package.json changes
    run('npm install', trigger=['package.json']),

    # Restart process when config changes
    restart_container(),
  ])

k8s_yaml('k8s/deployment.yaml')
k8s_resource('my-app', port_forwards='3000:3000')

Multi-Service Setup

# Tiltfile for microservices

# Frontend
docker_build('frontend', './frontend',
  live_update=[
    sync('./frontend/src', '/app/src'),
  ])

# Backend API
docker_build('backend', './backend',
  live_update=[
    sync('./backend/src', '/app/src'),
    run('pip install -r requirements.txt', trigger=['requirements.txt']),
  ])

# Worker service
docker_build('worker', './worker')

# Deploy all manifests
k8s_yaml([
  'k8s/frontend.yaml',
  'k8s/backend.yaml',
  'k8s/worker.yaml',
  'k8s/database.yaml',
])

# Port forwarding
k8s_resource('frontend', port_forwards='3000:3000')
k8s_resource('backend', port_forwards='8000:8000')
k8s_resource('postgres', port_forwards='5432:5432')

Configuration

Helm Integration

# Deploy with Helm
k8s_yaml(helm(
  'charts/my-app',
  name='my-release',
  namespace='dev',
  values=['charts/my-app/values-dev.yaml'],
  set=[
    'image.repository=my-app',
    'replicaCount=1',
  ]))

Kustomize Integration

# Deploy with Kustomize
k8s_yaml(kustomize('kustomize/overlays/dev'))

Resource Configuration

# Group and configure resources
k8s_resource('backend',
  port_forwards='8000:8000',
  labels=['api'],
  resource_deps=['postgres'],
  auto_init=True,
  trigger_mode=TRIGGER_MODE_AUTO)

k8s_resource('postgres',
  port_forwards='5432:5432',
  labels=['database'])

# Custom resource grouping
k8s_resource('frontend', labels=['web'])
k8s_resource('nginx', labels=['web'])

Local Resources

# Run local commands (not in Kubernetes)
local_resource('compile-proto',
  cmd='protoc --go_out=. proto/*.proto',
  deps=['proto/'],
  labels=['codegen'])

local_resource('npm-install',
  cmd='cd frontend && npm install',
  deps=['frontend/package.json'],
  labels=['setup'])

# Serve local process
local_resource('docs',
  serve_cmd='cd docs && mkdocs serve',
  links=['http://localhost:8000'],
  labels=['docs'])

Advanced Usage

Custom Build

# Custom build command (not Docker)
custom_build('my-app',
  command='bazel build //app:image && bazel run //app:image',
  deps=['app/'],
  tag='dev')

# Build with ko (Go)
custom_build('my-go-app',
  command='ko build ./cmd/server -B -t $EXPECTED_REF',
  deps=['cmd/', 'pkg/'])

Extensions

# Load extensions from tilt-extensions repo
load('ext://restart_process', 'docker_build_with_restart')
load('ext://namespace', 'namespace_create')
load('ext://helm_remote', 'helm_remote')
load('ext://secret', 'secret_from_dict')

# Create namespace
namespace_create('dev')

# Deploy remote Helm chart
helm_remote('redis',
  repo_name='bitnami',
  repo_url='https://charts.bitnami.com/bitnami',
  namespace='dev')

# Create Kubernetes secret
k8s_yaml(secret_from_dict('my-secret', inputs={
  'api-key': os.environ.get('API_KEY', 'dev-key'),
}))

Buttons and UI Links

# Add custom buttons to Tilt UI
load('ext://uibutton', 'cmd_button')

cmd_button('seed-db',
  argv=['python', 'scripts/seed.py'],
  resource='backend',
  text='Seed Database',
  icon_name='database')

# Add links to resources
k8s_resource('frontend',
  links=[
    link('http://localhost:3000', 'App'),
    link('http://localhost:3000/admin', 'Admin'),
  ])

CI Mode

# Tiltfile CI configuration
config.define_bool('ci')
cfg = config.parse()

if cfg.get('ci'):
  # CI-specific settings
  update_settings(max_parallel_updates=1)
  analytics_settings(enable=False)

# Run in CI mode (exits after resources are ready)
tilt ci

# CI with timeout
tilt ci --timeout 10m

Troubleshooting

Issue	Solution
Slow rebuilds	Use live_update to sync files instead of rebuilding
Port forward fails	Check port conflicts; verify service is running
Live update not triggering	Verify sync paths match your file structure
OOM on local cluster	Reduce replica counts; increase Docker memory
Extension not loading	Check load() path; run tilt doctor
Resource stuck pending	Check tilt logs <resource>; verify image pull

# Diagnose issues
tilt doctor

# View all resource status
tilt get

# Stream logs for specific resource
tilt logs backend

# Trigger manual rebuild
tilt trigger backend

# Clean everything
tilt down --delete-namespaces

# Verbose mode
tilt up --verbose