tilt

What this skill does

# 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     |

```python
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

```python
# 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()`