KiloLock Docs

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

Use the Terraform-compatible lane, not the native lane, when the target state is meant to remain strict Terraform-compatible.

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.

If KL_PROTOCOL=state-engine is enabled, this may use the native slice-aware lane. That native lane is intentionally blocked for states that are already configured for strict Terraform compatibility, and also for brand new states in environments whose default mode is vanilla.

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.

As with file-scoped native execution, strict Terraform-compatible states and strict-by-default environments reject the native lane early.

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.

When newer versions landed after the plan was created, the preflight now also surfaces:

  • changed since plan
  • allowed because
  • recent relevant versions

That is the main operator-facing answer to "what changed while I was planning?" and "why is this run still allowed to proceed?"

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.

Strict Terraform-compatible states

When kl apply discovers that the target state is running in strict Terraform-compatible mode, it prints an explicit note.

What happens next depends on the execution lane:

  • full/spec/backend-lane applies may still run, because they behave as the

    Terraform-compatible wrapper flow

  • native KL apply lanes are rejected early
  • vanilla Terraform whole-state locks remain authoritative

That means "strict Terraform-compatible" really means:

  • no native state-engine slice apply
  • no native/orchestrated KL commit path
  • whole-state locking and strict coexistence remain the contract

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