> ## Documentation Index
> Fetch the complete documentation index at: https://sponson.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR 0002: Three commands

> Architecture decision record 0002. Status: Accepted

Date: 2026-10-10

## Status

Accepted

## Context

Infrastructure tools tend to grow a command per situation: import, refresh, taint, state surgery, garbage collection.
Each command is another thing to document, test and decide between, and agents in particular pick the wrong one.
Sponson's operations reduce to two directions between the plan and reality, plus a read-only comparison.

The obvious fourth command was `import`, to bring existing resources under management. Its job overlaps with
generating the first plan: both read live state and write plan lines.

## Decision

The CLI has three commands, plus `mcp` to serve them to agents:

| Command | Direction | Writes |
| - | - | - |
| `sponson init` | make the plan catch up with reality: write a starter plan, or append lines adopting unmanaged resources (`--adopt <key>` for one) | the plan file only |
| `sponson plan` (alias `status`) | compare: read live state, print the diff and drift | nothing |
| `sponson apply` | make reality catch up with the plan; `--destroy` removes what the scope created | providers and the receipt store |

Variations are flags on these commands (`--env`, `--approved-by`, `--reconcile`, `--wait`, `--destroy`, `--json`),
never new commands. Every command takes `--json`.

## Consequences

* `init` is idempotent: first run writes a plan, later runs only append lines for unmanaged resources and never
  reformat what is there.
* `apply` is idempotent and resumable, so the same `sponson apply` serves every CI trigger (pull request opened or
  updated, deployment finished) and a retry is always safe.
* Some operations are deliberately missing. Garbage collection of scopes whose pull request closed without the
  workflow running would need a fourth command and is not implemented.
* CONTRIBUTING.md requires a design note in the pull request for any fourth command, explaining why a flag on an
  existing one is worse.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.