Core Concepts

Understand the operational mental model, idempotency guarantees, and safety protections of the Testform CLI.

The Plan and Apply Mental Model

The Testform CLI strictly decouples speculative analysis from physical mutation:

1. Read & Diff (plan): The CLI never modifies remote resources in plan mode. You can execute testform plan safely at any time to review pending operations.
2. Approved Mutation (apply): Requires explicit confirmation (or -auto-approve in unattended CI runners) and acquires a distributed mutex prior to dispatching mutations.

The State Ledger as the Known Truth

Unlike tools that rely solely on external API queries, Testform maintains a cryptographic state ledger (testform.state):

• Performance: Computes local diffs instantaneously without exhausting remote API rate limits.
• Drift Detection: Preserves SHA-256 hashes for each resource to detect out-of-band modifications.
• Lineage and Serial: Guards against concurrent race conditions from divergent branches.

Idempotency Guarantees

An idempotent command produces identical end states regardless of how many times it is triggered:

# First execution: Creates 3 remote resources
testform apply -auto-approve
# Output: Plan: 3 to add, 0 to change, 0 to destroy.

# Immediate second execution: Zero operations performed
testform apply -auto-approve
# Output: No changes. Your infrastructure matches the configuration.