Foundry CLI UX Contract

Core position

Foundry commands should optimize for simplicity, determinism, and consistent human-readable output. New commands should follow the existing contract instead of inventing one-off styles.

Command shape

foundry <command> <subcommand> [options]

Examples include foundry version, foundry plugin list --enabled, foundry theme scaffold editorial, and foundry routes check.

Output modes

Tabular output

Commands that show multiple rows should prefer aligned tables. Existing examples include plugin lists, theme lists, routes lists, and content lists.

Marker output

Status-oriented commands should use explicit markers such as [OK] and [FAIL]. Existing examples include plugin validation, doctor, validate, and routes check.

Mutators

Commands that change project state should clearly say what changed and print Next steps: when the user still has follow-up work.

Preferred wording

• Prefer foundry ... over make ... in user-facing guidance.
• Keep success lines direct and terse.
• Keep failure messages direct and specific.
• Do not print Next steps: for read-only commands.

Config requirements

Commands should not require project config unless they actually need it. foundry version is the model for config-free commands; foundry build is the model for config-bound commands.

Validation scope

1. config validates config only.
2. plugin validate validates plugins.
3. routes check validates routes.
4. validate validates the overall project.
5. doctor checks project plus environment health.

Human-first output

Default CLI output should stay optimized for humans. Machine-readable formats such as --json can exist, but they are not the primary interface.

Source document

The canonical source is docs/cli-contract.md. Update that file when the contract changes.