Describe the Feature
As an administrator installing DTaaS platform services, I want every dtaas-services command to follow a single <noun> <verb> pattern so that I can tell from the command itself whether it touches the host, a service container, or a user account.
Problem Statement
The dtaas-services CLI mixes three command styles:
| Style |
Example |
| Top-level hyphenated verb-noun |
dtaas-services generate-project |
| Flat top-level verbs |
dtaas-services setup, install, start, stop, restart, status, remove, clean |
| Noun-grouped verbs |
dtaas-services user add, dtaas-services user reset-password |
Consequences:
- Three different scopes read as peers.
setup prepares the host (copies TLS certs, sets permissions, requires root); install initialises a service's
database schema; start/stop act on containers. Flattened together, nothing signals these very different blast radii.
- Ambiguous setup verbs.
generate-project, setup, and install are three setup-flavoured top-level verbs whose differences only emerge from reading each help text.
- Not guessable. Learning
user add suggests service start, but the real command is the top-level start.
- Non-standard flag.
remove -v means "also remove volumes", but -v is conventionally verbose/version.
Proposed Solution
Adopt the same rule used by the dtaas CLI: dtaas-services <noun> <verb> [flags], with four nouns — project, host, service, user.
| Before |
After |
dtaas-services generate-project |
dtaas-services project generate [--force] |
dtaas-services setup |
dtaas-services host setup |
dtaas-services install -s <svc> |
dtaas-services service install -s <svc> |
dtaas-services start|stop|restart|clean [-s ...] |
dtaas-services service start|stop|restart|clean [-s ...] |
dtaas-services status [-s ...] |
dtaas-services service status [-s ...] [--json] |
dtaas-services remove [-s ...] [-v] |
dtaas-services service remove [-s ...] [--volumes] |
dtaas-services user add|reset-password |
unchanged (already noun verb) |
Key points:
host is the missing noun that makes setup legible — it prepares the machine, not a service, and grouping it under host states that scope up
front.
service gathers the six operational verbs plus install, sitting next to the already-universal --services/-s selector.
--json added to service status for scripted health checks.
--volumes promoted over -v, keeping -v as a compatibility alias.
- The resulting workflow reads as the documented install order:
project generate → host setup → service clean → service start → service install → user add.
Full rationale, noun-choice justification, command tables, and a clig.dev audit are in
deploy/services/cli/DTaaS-Services-CLI-Design.md.
Alternatives Considered
- Leave the operational verbs flat and only group new commands.
Rejected: keeps the host/service/schema scope collision that causes the most confusion.
- Fold
setup into service as service setup. Rejected: it acts on the host (certs, permissions, root), not on any service container; naming it a
service verb would misstate its scope.
system or machine instead of host. Both workable; host was chosen to match the platform's existing "DTaaS host" vocabulary.
- Merge
dtaas-services into the dtaas binary. Out of scope here — the two remain separate tools; this request only aligns their grammar.
- Flag-day rename with no aliases. Rejected: breaks the documented Quick Start and existing scripts without warning.
Additional Context
The design follows clig.dev subcommand guidance and the git/docker precedent, and deliberately mirrors the companion dtaas CLI redesign so the two tools are learned once and used everywhere.
The change is almost entirely command-layer wiring: pkg/ logic does not move. cmd.py gains project, host, and service groups alongside the existing user group, and install moves from setup_ops.py into service_ops.py.
This is a breaking change. A one-release deprecation window is proposed: old spellings remain as explicit hidden aliases that forward and print a deprecation notice to stderr, housed in a single aliases.py.
Follow-up noted in the design document: service remove --volumes is data-destroying and should gain a confirmation prompt (with --yes bypass), as clean already has.
Success Criterion
Checklist:
Describe the Feature
As an administrator installing DTaaS platform services, I want every
dtaas-servicescommand to follow a single<noun> <verb>pattern so that I can tell from the command itself whether it touches the host, a service container, or a user account.Problem Statement
The
dtaas-servicesCLI mixes three command styles:dtaas-services generate-projectdtaas-services setup,install,start,stop,restart,status,remove,cleandtaas-services user add,dtaas-services user reset-passwordConsequences:
setupprepares the host (copies TLS certs, sets permissions, requires root);installinitialises a service'sdatabase schema;
start/stopact on containers. Flattened together, nothing signals these very different blast radii.generate-project,setup, andinstallare three setup-flavoured top-level verbs whose differences only emerge from reading each help text.user addsuggestsservice start, but the real command is the top-levelstart.remove -vmeans "also remove volumes", but-vis conventionally verbose/version.Proposed Solution
Adopt the same rule used by the
dtaasCLI:dtaas-services <noun> <verb> [flags], with four nouns —project,host,service,user.dtaas-services generate-projectdtaas-services project generate [--force]dtaas-services setupdtaas-services host setupdtaas-services install -s <svc>dtaas-services service install -s <svc>dtaas-services start|stop|restart|clean [-s ...]dtaas-services service start|stop|restart|clean [-s ...]dtaas-services status [-s ...]dtaas-services service status [-s ...] [--json]dtaas-services remove [-s ...] [-v]dtaas-services service remove [-s ...] [--volumes]dtaas-services user add|reset-passwordnoun verb)Key points:
hostis the missing noun that makessetuplegible — it prepares the machine, not a service, and grouping it underhoststates that scope upfront.
servicegathers the six operational verbs plusinstall, sitting next to the already-universal--services/-sselector.--jsonadded toservice statusfor scripted health checks.--volumespromoted over-v, keeping-vas a compatibility alias.project generate → host setup → service clean → service start → service install → user add.Full rationale, noun-choice justification, command tables, and a clig.dev audit are in
deploy/services/cli/DTaaS-Services-CLI-Design.md.Alternatives Considered
Rejected: keeps the host/service/schema scope collision that causes the most confusion.
setupintoserviceasservice setup. Rejected: it acts on the host (certs, permissions, root), not on any service container; naming it aservice verb would misstate its scope.
systemormachineinstead ofhost. Both workable;hostwas chosen to match the platform's existing "DTaaS host" vocabulary.dtaas-servicesinto thedtaasbinary. Out of scope here — the two remain separate tools; this request only aligns their grammar.Additional Context
The design follows clig.dev subcommand guidance and the
git/dockerprecedent, and deliberately mirrors the companiondtaasCLI redesign so the two tools are learned once and used everywhere.The change is almost entirely command-layer wiring:
pkg/logic does not move.cmd.pygainsproject,host, andservicegroups alongside the existingusergroup, andinstallmoves fromsetup_ops.pyintoservice_ops.py.This is a breaking change. A one-release deprecation window is proposed: old spellings remain as explicit hidden aliases that forward and print a deprecation notice to
stderr, housed in a singlealiases.py.Follow-up noted in the design document:
service remove --volumesis data-destroying and should gain a confirmation prompt (with--yesbypass), ascleanalready has.Success Criterion
Checklist:
dtaas-services <noun> <verb>; no top-level bare verbs or hyphenated verb-nouns remainproject,host,service,user;installmoved intoservice_ops.py--forceadded toproject generate;--jsonadded toservice status--volumesdocumented as primary onservice remove,-vretained as alias--services/-sselector behaves identically across everyserviceverbhost setup, and the GitLab-not-ready path) use the new spellingsdtaas-services --helpgroups commands by theproject → host → service → userworkflowREADME.md,DEVELOPER.md, andGITLAB_INTEGRATION.mdupdated to the new command surface