`kl plan`

kl plan turns a Terraform configuration into a KiloLock plan spec.

That spec is the contract that kl apply uses later. It captures:

predicted writes
predicted reads
reservation needs
dependency context
discovered state identity
effective input variables used during planning

When to use it

Use kl plan when you want:

a reviewable artifact before apply
scoped planning from one or more files
targeted planning for experiments or careful operator work
quota-aware preflight before mutating state

Core forms

Full configuration plan

kl plan

This runs in the current Terraform directory and writes kl-plan.json.

File-scoped plan

kl plan -f slow_a.tf -o slow-a.plan.json

Use this when you want KiloLock to treat one file as the intended mutation surface.

Targeted plan

kl plan --target time_sleep.slow_a -o slow-a.plan.json

Use this only when you deliberately want Terraform target semantics.

Important flags

--out, -o: write the plan spec somewhere explicit.
--file, -f: scope intent to resources declared in selected file(s).
--target: use Terraform target semantics. Useful, but easier to misuse.
--no-refresh: skip provider reads for faster planning when you trust current state.
--var NAME=VALUE: pin explicit input variables into the spec.
--no-pin-vars: avoid storing effective plan-time variables from TF_VAR_* and .tfvars.
--terraform-bin: use a non-default Terraform binary.
--timeout: cap the combined terraform plan and terraform show -json wall time.

Meaningful examples

Generate a reviewable spec for PR discussion

kl plan -o artifacts/kl-plan.json

This is the simplest “show me what KiloLock thinks this change touches” workflow.

Scope a plan to one file in a large state

kl plan -f slow_a.tf -o slow-a.plan.json

This is the right starting point for a large shared state where only one part should be owned by the change.

Try a fast iterative plan

kl plan -f slow_a.tf --no-refresh

Useful in local loops and demos. Do not rely on it when you need fresh drift detection.

Plan with explicit input values

kl plan --var slow_a_version=v2 --var slow_b_version=v1

This makes the plan spec replayable and removes ambiguity from later apply.

`--target` guidance

--target is a power tool, not the default path.

Use it when:

you are isolating a specific Terraform address on purpose
you understand that target-scoped plans can omit needed graph branches
you are willing to review preflight warnings carefully

Prefer --file when:

the intended scope maps naturally to a file
you want a more understandable developer workflow
you want fewer “why did Terraform touch that?” surprises

Output artifact

By default:

kl-plan.json

Typical follow-up:

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

Apply
Quota
[Environment variables and .kl.toml](./environment.md)

kl plan