# CLI Surface and Mutating Operations Agenda

## Status

Open

## Purpose

Define the stable CLI contract for packer commands, especially commands that mutate registry state or user files.

## Context

The draft already lists a substantial command surface:

- `init`
- `add`
- `adopt`
- `forget`
- `rm`
- `list`
- `show`
- `doctor`
- `build`
- `watch`
- `gc`
- `quarantine`

This is enough surface area that command semantics need architectural review before turning into normative CLI specs.

## Source Sections

- `13. CLI Commands (Comprehensive)`

## Key Questions

1. Which commands are core v1 and which are aspirational?
2. Which identifiers must every command accept: name, id, uuid, path?
3. Which commands mutate registry only versus mutate workspace files?
4. What requires confirmation, force flags, or dry-run support?
5. How explicit should `--fix` and auto-materialization behavior be?
6. Should CLI output contracts be stable for automation, or only JSON/structured output modes?

## Options

### Option A

Define a minimal stable v1 CLI and mark the rest as future or optional.

### Option B

Freeze the larger command catalog immediately.

## Tradeoffs

- Option A lowers the early compatibility burden.
- Option A gives room to validate mutating operations safely before promising too much.
- Option B gives a bigger product surface up front, but it increases long-term compatibility cost.

## Recommendation

Adopt Option A and distinguish:

- required core commands,
- optional commands,
- future commands not yet in the normative CLI contract.

## Expected Decisions to Produce

1. Core v1 command set.
2. Mutation safety model.
3. Identifier resolution rules.
4. Structured output and automation expectations.

## Expected Spec Follow-up

- CLI command contract spec.
- Mutation and confirmation policy spec.
- Command output contract spec.

## Non-Goals

- Asset payload binary layout.
- Format-specific `asset.json` rules.
- Detailed cache internals.