KiloLock Docs

kl refresh

kl refresh talks to providers directly and writes a new KiloLock state version when refreshed data differs from the current trunk.

This is not a Terraform plan/apply command. It is a provider-driven refresh workflow.

When to use it

Use kl refresh when you want:

  • drift visibility without running a normal Terraform plan
  • a backend-recorded refresh run
  • provider-driven state updates with auditability

Core form

kl refresh big-state

You can also pass a full state URL instead of a plain state name.

Important flags

  • --dry-run: detect drift without writing a new state version.
  • --fail-fast: stop on the first resource error.
  • --concurrency: control parallel provider groups.
  • --actor: record a specific audit actor string.
  • --provider-search-path: tell KiloLock where provider binaries live.
  • --token: override KL_TOKEN.

Meaningful examples

Safe refresh preview

kl refresh big-state --dry-run

Use this before writing refreshed state in a sensitive environment.

Run a refresh with explicit provider paths

kl refresh big-state \
  --provider-search-path ./.terraform/providers \
  --provider-search-path ~/.terraform.d/plugin-cache

Useful when provider discovery is the main source of refresh failure.

Stop immediately on provider errors

kl refresh big-state --fail-fast

This is useful for debugging broken provider auth or schema issues.

Provider discovery

Search path precedence is:

  1. --provider-search-path
  2. KL_PROVIDER_PATH
  3. built-in defaults such as .terraform/providers, Terraform plugin cache locations, and TF_PLUGIN_CACHE_DIR when set