Symptom
CLI conventions have drifted across subcommands:
- Connection:
introspect/dump-cluster/dump-sql take -host/-port/-user/-password/-secure flags; diff accepts only a clickhouse:// URI.
- Output:
introspect/load use -out, dump-cluster uses -out-dir.
-left means "one of two diff operands" in diff but "the schema to edit" in sql2hcl.- Exit codes: usage errors are sometimes
os.Exit(1), sometimes os.Exit(2) for the same class (e.g. hclexp.go:218 vs :333).
- Per-subcommand
-h is bare Go flag output — no description or examples; only the top-level usage() has prose.
Impact
Users must relearn flag conventions per subcommand; scripts can't rely on exit codes.
Fix direction
Pick one connection convention (support both URI and flags everywhere via a shared flag group), unify -out, standardize exit codes (2 = usage, 1 = runtime), and give each FlagSet a Usage func with a one-line description + example.
Found in the 2026-07-02 deep-dive audit (docs/plans/2026-07-02-deep-dive-improvement-areas.md, C4).
Symptom
CLI conventions have drifted across subcommands:
introspect/dump-cluster/dump-sqltake-host/-port/-user/-password/-secureflags;diffaccepts only aclickhouse://URI.introspect/loaduse-out,dump-clusteruses-out-dir.-leftmeans "one of two diff operands" indiffbut "the schema to edit" insql2hcl.os.Exit(1), sometimesos.Exit(2)for the same class (e.g. hclexp.go:218 vs :333).-his bare Go flag output — no description or examples; only the top-levelusage()has prose.Impact
Users must relearn flag conventions per subcommand; scripts can't rely on exit codes.
Fix direction
Pick one connection convention (support both URI and flags everywhere via a shared flag group), unify
-out, standardize exit codes (2 = usage, 1 = runtime), and give each FlagSet aUsagefunc with a one-line description + example.Found in the 2026-07-02 deep-dive audit (docs/plans/2026-07-02-deep-dive-improvement-areas.md, C4).