📝 Write an ADR for noun-first CLI restructure
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 51m
- Merged PRs (30d)
- 104
Description
Note — do not pre-claim an ADR number. This issue deliberately does not name one.
Pick the number when the file is actually written, by checking the highest number both
onmainand in open PRs (PR #393 currently holds 126-132 for the multi-region set;
mainis at 134 as of this note). This issue previously said ADR-122, then ADR-133 — both
were taken out from under it, because numbers get claimed in titles and branches long
before the file exists whilemainonly knows the numbers already merged.
Description
Write an ADR documenting the decision to restructure the CLI from its current organic layout to a noun-first command hierarchy.
Current State
The CLI has grown organically with a mix of patterns:
| Command | Pattern | Issue |
|---|---|---|
deploy, delete, status |
Verb at top level | Stack operations not grouped |
cfn-template, lambda-export |
Compound at top level | Export operations scattered |
entity set-limits |
Noun + compound verb | Inconsistent with resource set-defaults |
entity list-resources |
Cross-noun query on entity | Belongs under resource |
version, upgrade, check |
Verb at top level | Stack lifecycle not grouped |
Proposed Structure (ADR Content)
The ADR must document the following decisions:
1. Top-level nouns: stack, system, resource, entity, audit, usage, local, load
2. Consistent verb set: get, list, set, delete, create, deploy (max 2 levels of nesting: noun verb)
3. Global options: --name, --region, --endpoint-url are defined on the root group and inherited by all subcommands
4. Mapping table (current -> new):
| Current | New | Notes |
|---|---|---|
deploy |
stack deploy |
|
delete |
stack delete |
|
status |
stack status / stack get |
|
list |
stack list |
|
version |
stack version |
|
upgrade |
stack upgrade |
|
check |
stack check |
|
cfn-template |
stack export-template |
|
lambda-export |
stack export-lambda |
|
system set-defaults |
system set |
|
system get-defaults |
system get |
|
system delete-defaults |
system delete |
|
resource set-defaults |
resource set |
|
resource get-defaults |
resource get |
|
resource delete-defaults |
resource delete |
|
resource list |
resource list |
No change |
entity set-limits |
entity set |
|
entity get-limits |
entity get |
|
entity delete-limits |
entity delete (config) |
|
entity create |
entity create |
No change |
entity show |
entity show |
No change |
entity list |
entity list |
No change |
entity list-resources |
resource list --with-entity-configs |
Cross-noun query moves to resource |
audit list |
audit list |
No change |
usage list |
usage list |
No change |
usage summary |
usage summary |
No change |
local up/down/... |
local up/down/... |
No change |
load deploy/connect/... |
load deploy/connect/... |
No change |
5. Entity config sub-operations decision: Whether entity set covers both entity creation and limit configuration, or limits need a sub-noun (entity config set vs entity set --resource). The ADR must decide between:
entity set --resource gpt-4 -l rpm:1000(flat with--resourceflag)entity config set --resource gpt-4 -l rpm:1000(3-level nesting, violates max-2 rule)- Keep
entity set-limitsas a hyphenated verb (exception to the verb set)
6. Legacy alias strategy:
- Old commands remain as hidden aliases for 2 minor versions
- Aliases emit deprecation warnings to stderr
- Removed in the next major version (v2.0.0)
7. Cross-noun query resolution:
entity list-resourcesbecomesresource list --with-entity-configs- Queries belong under the noun that represents the result type
Acceptance Criteria
-
docs/adr/<N>-noun-first-cli.mdexists with Status: Proposed, where<N>is chosen at write time per the note above (highest number onmainand in open PRs, +1) - ADR follows the format from ADR-000 (max 100 lines, required sections: Context, Decision, Consequences, Alternatives Considered)
- Decision section contains: (a) the noun list, (b) the verb set, (c) global options list, (d) the entity config sub-operation decision, (e) legacy alias deprecation timeline, (f) cross-noun query rule
- Alternatives Considered section addresses at least: verb-first hierarchy, flat (no grouping), and 3-level nesting
- No code examples or implementation checklists in the ADR (per ADR-000)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading docs/adr/ADR-000 and checking the highest ADR number on main and in open PR #393 before choosing the filename. Write a Proposed ADR under docs/adr/ with the required sections, noun-first decisions, alternatives, alias timeline, and cross-noun query rule, staying under 100 lines and omitting code examples and implementation checklists.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100