📝 Write ADR-133 for noun-first CLI restructure

[sodre]

Note: Originally numbered ADR-122; renumbered to 133 because 122 was assigned to the 'Resolve Limits on Repository' ADR.

Description

Write ADR-133 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 --resource flag)
• entity config set --resource gpt-4 -l rpm:1000 (3-level nesting, violates max-2 rule)
• Keep entity set-limits as 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-resources becomes resource list --with-entity-configs
• Queries belong under the noun that represents the result type

Acceptance Criteria

• docs/adr/133-noun-first-cli.md exists with Status: Proposed
• 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)

[sodre]

Noun-First CLI Patterns: Lessons from Well-Known Tools

This research examines how 5 industry-leading CLIs structure their commands. The goal is to understand what makes noun-first CLIs feel cohesive, predictable, and scalable.

Executive Summary

Noun-first CLIs succeed through:

1. Verb consistency — A small, shared set of common verbs (list, create, delete, get) used across all resources
2. Logical hierarchy — Resources grouped in parent/noun/verb structure; nested resources inherit parent verbs
3. Graceful escape hatches — Domain-specific operations live in specialized subcommands rather than polluting CRUD operations
4. Discoverability through consistency — Once users learn one resource's verbs, they expect them everywhere
5. Backward compatibility paths — Legacy aliases allowed during transition (Docker's approach)

---

1. Docker

Standard Verbs Across All Resources

Docker uses a consistent verb set across all object types (container, image, volume, network, etc.):

Verb	Purpose	Example
ls / list	Display objects	docker container ls, docker image ls
inspect	Show detailed info	docker container inspect
rm / remove	Delete objects	docker container rm
create	Create new objects	docker container create
run	Create + start (containers only)	docker container run
start / stop	Control state	docker container start
ps	List running (legacy alias)	docker container ps

Organization Pattern

docker <noun> <verb> [OPTIONS]

Example hierarchy:

• docker container ls (list containers)
• docker image build (build image)
• docker volume ls (list volumes)
• docker network ls (list networks)
• docker service ls (list services)

Handling Non-CRUD Operations

Docker isolates complex/experimental operations in dedicated subcommands rather than mixing them into basic CRUD:

• docker compose — Full subcommand namespace for Compose operations (not docker container compose)
• docker buildx — Advanced build features separated from basic docker image build
• docker scan — Security scanning as dedicated subcommand
• docker plugin — Plugin management as distinct namespace

Key insight: Complex domains get their own docker <tool> entry point with their own verb hierarchy, rather than being nested under container/image/etc.

Backward Compatibility Strategy

Docker maintains legacy top-level commands alongside new management commands:

• Old: docker rm container_id → New: docker container rm container_id
• Old: docker pull ubuntu → New: docker image pull ubuntu

Environment variable DOCKER_HIDE_LEGACY_COMMANDS allows transitioning users gradually. This prevents breaking existing scripts while encouraging adoption of the new structure.

---

2. GitHub CLI (gh)

Common Verbs Across Resource Types

GitHub CLI uses a highly consistent core verb set that appears across nearly every resource type:

Verb	Resources	Count
list	issue, pr, repo, release, label, gist, ssh-key, gpg-key, secret, variable, config, alias, and more	19+
create	issue, pr, repo, release, label, gist, codespace, and more	10+
delete	issue, pr, repo, release, label, gist, ssh-key, gpg-key, secret, and more	19+
view	issue, pr, repo, release, label, gist, codespace, and more	11+
edit	issue, pr, repo, release, label, gist, config, and more	9+

Specialized Verbs (Domain-Specific)

Alongside the core verbs, gh adds resource-specific operations:

• PR-only: checkout, merge, revert, review, diff, comment
• Issue-only: lock, unlock, pin, unpin, close, reopen, comment
• Release-only: download, verify
• Run-only: watch, cancel, rerun
• Workflow-only: enable, disable

Organization Pattern

gh <noun> <verb> [ARGUMENTS]
gh <noun> <verb> <sub-noun> [ARGUMENTS]

Examples:

• gh issue create (simple verb)
• gh pr comment (adding a comment)
• gh repo deploy-key add (nested noun pattern)

Key Feature: Consistent Flags Across Resources

All resources support -R <repo> to target different repositories, making commands portable and predictable:

gh issue list -R owner/repo
gh pr list -R owner/repo
gh release list -R owner/repo

---

3. Kubernetes (kubectl)

Standard Verbs (RBAC-Inspired)

Kubernetes uses HTTP-inspired standard verbs that reflect database operations:

Verb	Purpose	Example
get	Retrieve/list resources	kubectl get pods
create	Create resources	kubectl create deployment nginx --image=nginx
apply	Create or update (idempotent)	kubectl apply -f config.yaml
delete	Remove resources	kubectl delete pod my-pod
patch	Partial update	kubectl patch pod my-pod -p '{"spec":{"key":"val"}}'
update	Replace entire resource	kubectl replace -f config.yaml

Resource Hierarchy

kubectl <verb> <resource-type> [NAME] [FLAGS]

Unique note: verb comes first, then noun (inverse of Docker/gh). This is intentional—it groups similar operations together rather than similar resources.

Handling Cluster-Wide Operations

Kubernetes reserves top-level commands for operations outside the resource model:

Command	Purpose
cluster-info	Cluster infrastructure details (no resource targeting)
version	Client/server version mismatch detection
config	Kubeconfig management (subcommand structure below)
explain	API documentation for resources
api-resources	List available resource types
api-versions	List available API versions

Subcommand structure for complex domains:

kubectl config current-context
kubectl config set-context
kubectl config view
kubectl config set-cluster

Key Insight: Verb-First vs Noun-First

Unlike Docker and gh (noun-first), kubectl is verb-first (get pods not pods get). This works because:

• All resources share the same verb set
• Users learn the verb set once, then apply to any resource
• Related operations cluster together in help output

---

4. AWS CLI

Service Organization (Service as Noun)

AWS CLI uses services as the primary noun, not resource types. Each service has its own verb set:

aws <service> <verb> [OPTIONS]

Verb Patterns by Service (NOT Standardized)

Unlike Docker/gh, AWS services have inconsistent verb patterns:

S3 (file-like):

• ls — List buckets/objects
• cp, mv, rm — File operations
• mb, rb — Make/remove bucket

EC2 (resource):

• describe-instances — List instances
• run-instances — Launch instances
• start-instances, stop-instances — State control
• terminate-instances — Delete instances

DynamoDB (data):

• list-tables — List tables
• describe-table — Get table info
• create-table — Create table
• put-item, get-item — Data operations
• scan, query — Data retrieval

STS (security):

• get-caller-identity — Get current principal
• assume-role — Assume IAM role

CloudFormation (infrastructure):

• describe-stacks — List stacks
• create-stack — Create stack
• update-stack — Modify stack

Why Inconsistency?

AWS services were built independently with their own verb conventions:

• S3 uses Unix file commands because it's file-like
• EC2 uses describe-* because it's resource-centric
• DynamoDB uses put-item/get-item because it's data-centric
• STS uses get-* because it's security-oriented

This makes AWS CLI harder to predict but necessary for domain accuracy.

Discoverability Strategy

AWS relies on:

• aws help (lists all services)
• aws <service> help (lists verbs for that service)
• Consistent naming within each service (reduces mental load for single-service users)

---

5. Pulumi

Command Organization by Domain

Pulumi uses top-level commands for different concerns:

Domain	Commands	Purpose
Deployment	up, preview, destroy	Infrastructure lifecycle
Stack Mgmt	pulumi stack	Multiple environment/stack management
Configuration	pulumi config	Configuration and secrets
State	pulumi state	Raw state editing (advanced)
Plugins	pulumi plugin	Plugin management
Policy	pulumi policy	Governance and compliance rules
Auth	login, logout, whoami	Session management
Project	pulumi new	Project scaffolding

Configuration Subcommands (Handling CRUD + Special Ops)

pulumi config get <key>              # Read
pulumi config set <key> <value>      # Create/Update
pulumi config rm <key>               # Delete
pulumi config rm-all                 # Delete multiple
pulumi config set-all                # Batch set

Special Operations in Separate Subcommands

Rather than mixing concerns, Pulumi isolates domain-specific operations:

• pulumi config env — ESC (Environments, Secrets, Config) integration
• pulumi config cp — Cross-stack configuration duplication
• pulumi config refresh — Sync local config from deployment

Key insight: Operations that would clutter basic CRUD get their own subcommand, keeping config operations clean.

Discoverability Model

Pulumi separates help into:

• Common commands (top 6-8 most-used)
• Management commands (stack, config, state, etc.)
• Other commands (less common utilities)

This provides progressive disclosure—new users see core commands first, power users can access full feature set.

---

Common Patterns Across All CLIs

1. Core Verb Consistency

All successful CLIs have a small, predictable verb set:

CLI	Core Verbs
Docker	ls, inspect, rm, create, run, start, stop
GitHub	list, create, delete, view, edit
Kubectl	get, create, apply, delete, patch
Pulumi	up, preview, destroy (top-level); get, set, rm (config)

Specialization happens within a verb (e.g., docker container run vs docker image build), not in the verb itself.

2. Hierarchical Organization

Most successful CLIs use some form of hierarchy:

# Docker: noun > verb
docker container ls

# GitHub: noun > verb [> sub-noun]
gh pr checkout
gh repo deploy-key add

# Kubectl: verb > noun (inverse, but still hierarchical)
kubectl get pods

# Pulumi: domain > verb
pulumi config get
pulumi stack list

3. Specialized Verbs Live in Subcommands

Instead of polluting the main verb set, domain-specific operations get their own namespace:

CLI	Example
Docker	docker compose (separate tool)
GitHub	gh pr review (specialized under pr)
Kubectl	kubectl config set-context (subcommand structure)
Pulumi	pulumi config env (subcommand for special ops)

4. Escape Hatch: Legacy/Backward Compatibility

Most CLIs need a transition path:

CLI	Strategy
Docker	DOCKER_HIDE_LEGACY_COMMANDS environment variable
GitHub	No legacy burden (started with new model)
Kubectl	No legacy burden (designed for verb-first)
Pulumi	No legacy burden (designed for domain separation)

5. Help/Discoverability Strategy

CLI	Strategy
Docker	Object-first organization; docker --help → object list
GitHub	Command categories; gh help commands → filtered by domain
Kubectl	Verb-first organization; commands grouped by operation type
Pulumi	Progressive disclosure: common → management → other

6. Flag Consistency

When a flag makes sense across resources, it's applied consistently:

CLI	Flag	Applies To
GitHub	-R <repo>	Across all resources (issue, pr, release, etc.)
Kubectl	-n <namespace>	Across most resources
Docker	-f (format)	Across list commands

---

Design Principles for Noun-First CLIs

Principle 1: Start with a Core Verb Set

Define the 5-7 most common operations early. Every resource should support them:

CORE_VERBS = [list, create, delete, view, edit]

Once established, new resources automatically inherit these verbs. This scales linearly: adding the 100th resource doesn't require new verb definitions.

Principle 2: Special Ops Get Subcommands, Not New Verbs

When an operation doesn't fit core verbs:

# WRONG: inventing new verbs
zae-limiter entity sync
zae-limiter entity export
zae-limiter entity reconcile

# RIGHT: subcommand for special ops
zae-limiter entity:config sync
zae-limiter entity:bulk export
zae-limiter system:repair reconcile

Or use separate top-level commands:

zae-limiter config-sync entity-123
zae-limiter export --type entity
zae-limiter repair --dry-run

Principle 3: Hierarchy > Invention

When unsure whether something is a verb or a subcommand, choose the hierarchical interpretation:

# Object hierarchy
zae-limiter <resource> <verb> [<sub-resource>] [<sub-verb>]

# Examples
zae-limiter entity list                    # list all entities
zae-limiter entity get entity-123         # view single entity
zae-limiter entity config get api-key     # get entity's API key config
zae-limiter resource limits set gpt-4     # set defaults for resource

Principle 4: Consistent Flags for Cross-Cutting Concerns

Flags that apply across multiple resources should work identically everywhere:

# If one resource supports --format json, all should
zae-limiter entity list --format json
zae-limiter resource list --format json
zae-limiter limit list --format json

# If --region is needed, it should work everywhere
zae-limiter deploy --name my-app --region us-east-1
zae-limiter status --name my-app --region us-east-1

Principle 5: Help Text is Part of CLI Design

Help discovery should reflect the noun-first organization:

zae-limiter --help                 # Top-level: "Commands: entity, resource, limit, deploy..."
zae-limiter entity --help          # Second-level: "Commands: list, create, delete, get, set-limits..."
zae-limiter entity list --help     # Operation-level: "List all entities with optional filters"

---

Anti-Patterns to Avoid

1. Verb Explosion

# DON'T: Too many verbs
zae-limiter entity list
zae-limiter entity view
zae-limiter entity show
zae-limiter entity describe
zae-limiter entity get-all

Pick ONE verb and use it consistently. If variations are needed, use flags:

# DO: One verb, behavior controlled by flags
zae-limiter entity list                # default: list all
zae-limiter entity list --id entity-1  # single entity
zae-limiter entity list --format json  # different format

2. Inconsistent Flags Across Resources

# DON'T: Different flags for same operation
zae-limiter entity list --all          # all entities
zae-limiter resource list -a           # all resources (different flag!)

# DO: Consistent flags
zae-limiter entity list --all
zae-limiter resource list --all

3. Mixing Domains into Single Noun

# DON'T: Everything under "admin"
zae-limiter admin entity-limits set
zae-limiter admin resource-defaults get
zae-limiter admin system-config list

# DO: Separate by domain
zae-limiter entity limits set entity-1
zae-limiter resource defaults get gpt-4
zae-limiter system config list

4. Buried Utilities

# DON'T: Utility hidden deep in hierarchy
zae-limiter entity advanced-config system-repair

# DO: Utilities at top level or in dedicated subcommand
zae-limiter repair
zae-limiter system repair

5. CRUD Verbs for Non-CRUD Operations

# DON'T: "create" for an action that isn't resource creation
zae-limiter entity create-usage-report entity-1     # Confusing!
zae-limiter resource create-forecast gpt-4          # "create" implies data creation

# DO: Dedicated verbs for special operations
zae-limiter report entity entity-1
zae-limiter forecast resource gpt-4
zae-limiter export --type usage-report

---

Summary Table: Patterns by CLI

Aspect	Docker	GitHub	Kubectl	AWS	Pulumi
Organization	Noun > Verb	Noun > Verb	Verb > Noun	Service > Verb	Domain > Verb
Core Verbs	7 (consistent)	5 (consistent)	6 (consistent)	Varies per service	Varies by domain
Nested Resources	Separate subcommands	Inline sub-noun	Not applicable	Not applicable	Subcommand structure
Special Ops	docker <tool>	Specialized verb	Top-level command	Domain-specific	Subcommand
Backward Compat	Legacy aliases + env var	N/A	N/A	N/A	N/A
Help Strategy	Object-first listing	Category grouping	Verb-first grouping	Service listing	Progressive disclosure
Verb Consistency	High (goal)	High (goal)	High (goal)	Low (accepted)	Medium (by domain)

---

Key Takeaway

The most cohesive CLIs achieve predictability through consistency, not through feature completeness.

Users should be able to guess a command before running it. The moment a user thinks "I should be able to do X," and the command exists where they expect it, the CLI feels professional and well-designed.

Consistency > Feature Richness. Predictability > Flexibility.