ADR 0003: CLI Hierarchy Hard Cutover
Status: Accepted
Date: 2026-03-24
Context
Section titled “Context”The edgeplane command surface grew organically and mixed concerns at the top level: tools, sync, explorer, maintenance, update, compat, drift, remote, evolve, login, logout, whoami all lived at the root. This made command discovery and onboarding harder and increased ambiguity around where functionality belongs.
Because EdgePlane is in a pilot stage, a hard cutover without backward-compatibility aliases is acceptable.
Decision
Section titled “Decision”Adopt the following top-level command hierarchy:
Keep at top level: launch, serve, daemon, ops, workspace, approvals, profile, init, run, tui
Group into domains:
| Domain | Commands |
|---|---|
auth | login, logout, whoami |
admin | policy ..., governance ... |
data | tools ..., sync ..., explorer ... |
system | doctor, maintenance ..., update ..., compat ..., drift ... |
agent | signal, list, describe, attach, cancel, cron ..., supervise ..., evolve ... |
No legacy aliases are retained.
Consequences
Section titled “Consequences”Positive:
- Clear information architecture by user intent
- Less cognitive load for new operators and agent authors
- Better foundation for docs, catalogs, and scripted playbooks
Negative:
- Breaking command changes require immediate doc and script updates
- Existing shell history and muscle memory are invalidated at the transition point
Follow-up
Section titled “Follow-up”- Update docs and catalog entries to the new hierarchy
- Ensure in-product hints and repair messages reference new command paths
- Maintain
docs/reference/COMMAND-MAP.mdas the canonical command index
See Reference: Command Map for the current full hierarchy.