Skip to content

[FEATURE]Adopt a unified dtaas-services <noun> <verb> command grammar for services CLI #1715

Description

@prasadtalasila

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:

  • Version incremented to 1.0.0
  • All commands follow dtaas-services <noun> <verb>; no top-level bare verbs or hyphenated verb-nouns remain
  • Commands regrouped under project, host, service, user; install moved into service_ops.py
  • --force added to project generate; --json added to service status
  • --volumes documented as primary on service remove, -v retained as alias
  • --services/-s selector behaves identically across every service verb
  • Deprecated aliases forward correctly and emit a deprecation notice
  • Printed "next steps" hints (after host setup, and the GitLab-not-ready path) use the new spellings
  • dtaas-services --help groups commands by the project → host → service → user workflow
  • README.md, DEVELOPER.md, and GITLAB_INTEGRATION.md updated to the new command surface
  • Test coverage is improved
  • No qlty issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions