`kl apply`

kl apply is the command that takes predicted scope and turns it into a new committed state version.

It can:

apply an existing plan spec
build a full plan implicitly
build a file-scoped plan implicitly
build a targeted plan implicitly

When to use it

Use kl apply when you want:

a normal KiloLock apply from kl plan
scoped apply on a large shared state
target-based operator work with explicit acknowledgement
preflight-only review with --dry-run

Core forms

Apply an existing spec

kl apply --plan-spec kl-plan.json

This is the cleanest CI-friendly flow.

Build and apply a full plan implicitly

kl apply

This is convenient when you are already in the Terraform directory and want the shortest path.

Build and apply from selected files

kl apply -f slow_a.tf --confirm-scope

This is the practical shared-state workflow for many KiloLock users.

Build and apply from selected targets

kl apply --target time_sleep.slow_a --allow-unsafe-target --confirm-scope

Use this only when you intentionally accept target-specific risk.

Important flags

--plan-spec: apply a spec generated earlier by kl plan.
--file, -f: derive a scoped apply from selected file(s).
--target: derive a targeted apply from selected addresses.
--dry-run: print preflight and exit without running Terraform apply.
--confirm-scope: required for mutating scoped applies.
--allow-unsafe-target: required for mutating --target applies.
--allow-destructive-scoped: required when a file-scoped apply contains destructive actions.
--strict-target-preflight: fail when target preflight emits risk warnings.
--strict-file-preflight: fail when file-scoped preflight emits risk warnings.
--strict-coexistence: fail instead of only warning when vanilla Terraform whole-state locks are active.
--state: override the trunk state name.
--work-dir: point at the Terraform config directory explicitly.
--terraform-bin: override the Terraform binary path.
--no-refresh: with --file, skip refresh during scoped plan creation.
--orchestrated: use the DB-backed reservation and row-level commit path.
--wait-timeout: wait for conflicting reservations instead of failing immediately.
--keep-tmp-dir: preserve temp workspace for debugging.

Meaningful examples

Safest review-first workflow

kl plan -f slow_a.tf -o slow-a.plan.json
kl apply --plan-spec slow-a.plan.json --dry-run
kl apply --plan-spec slow-a.plan.json --confirm-scope

This gives you a spec artifact, a preflight review, and then an explicit apply.

Fail fast in CI

kl apply --plan-spec kl-plan.json --wait-timeout 0

This is the “do not hang the pipeline behind someone else’s reservation” mode.

Run a file-scoped apply with strict safety

kl apply -f slow_a.tf --confirm-scope --strict-file-preflight

Good when you want scoped productivity without silently ignoring risk warnings.

Run a targeted apply with explicit acknowledgement

kl apply \
  --target time_sleep.slow_a \
  --allow-unsafe-target \
  --confirm-scope \
  --strict-target-preflight

This is the right shape when you must use target semantics and want the CLI to push back hard on risky fanout.

Scoped apply model

The important mental model is:

--file says “this file is the intended ownership surface”
--target says “this exact address selection is the intended surface”
--confirm-scope is the operator acknowledgement that the derived scope looks right

That is why the command asks for explicit confirmation on mutating scoped flows.

When to prefer implicit apply vs explicit spec

Prefer explicit spec files when:

you want reviewable artifacts
you want repeatable CI/CD
you want the plan and apply steps clearly separated

Prefer implicit kl apply -f ... when:

you are operating locally
the scope is obvious
you want less ceremony for one-off changes

kl apply