easy-plan

easy-plan is a terminal-only, local-first CLI. It reads Markdown and writes Markdown; it has no browser, TUI, watch, inspect, or legacy graph surface. Source files are never overwritten.

The canonical binary is easy-plan. epv and easy-plan-viewer remain compatibility aliases, and the npm package is still named easy-plan-viewer to support migration from 0.2.x.

Install and run

pnpm add --global easy-plan-viewer
easy-plan brief path/to/plan.md

The package can also be invoked with pnpm dlx or npx; use the package name for those runners. The command accepts one readable Markdown file for content operations.

Commands

easy-plan brief <file.md> [--to <locale>]
easy-plan eli5 <file.md> [--to <locale>]
easy-plan business <file.md> [--to <locale>]
easy-plan translate <file.md> --to <locale>
easy-plan visualize <file.md> [--to <locale>]
easy-plan visualise <file.md> [--to <locale>]
easy-plan config show
easy-plan config provider set <provider> --model <model> --protocol <protocol>
easy-plan config models <provider>
easy-plan config consent grant|revoke
easy-plan help
easy-plan version

visualize is canonical; visualise is an alias. The 0.2.x migration is graph → visualize and simplify → brief. The old commands are removed.

Every successful content command publishes exactly one user-facing Markdown artifact below .easy-plan/artifacts/, with a hidden compact metadata sidecar. It prints exactly one safe reader command and does not execute it. Reader selection prefers bat, batcat, glow, mdcat, less, then cat.

Visualization

visualize produces source-grounded architecture documentation: evidence and plain Markdown tables cover database, request, component, and migration sections. Mermaid is generated locally from validated facts and restricted to the supported safe subset. It does not invent cardinality, ordering, or edges. ER cardinality and identifying relationships are emitted only when explicit ER notation is present in the source evidence; otherwise the fact remains in the table. Mermaid remains readable source in cat/bat and renders in tools that support Mermaid.

Credentials, consent, and safety

Configure a provider, model, and protocol with config, grant consent, and set the provider's documented API-key environment variable in the current shell. Environment variables are recommended. Keys are not command arguments or examples in this documentation. Consent covers the captured Markdown and canonical metadata; source identity, freshness checks, and atomic publication prevent stale or partial artifacts. Legacy inline/keychain reads may remain available only for migration compatibility; new setups should use environment variables. Never commit or share credentials.

Requirements and development

Node.js 22.x is required. See the terminal workflow for input, configuration, output, and migration details, and release readiness for the 0.3.0 verification gate.