test of output

[protpaw]

Canonical CLI automated review report

This report is AI-generated. Please report issues with the cli-skill so we can improve this report.

Scope: CLI standard compliance review of cmd/cli/**

Workflow: CLI skill version v.X

Reference: Canonical CLI standards

Limitations: Detection of clear CLI spec violations. Does not guarantee full compliance with CLI spec

---

Findings

Severity	Rule summary	Evidence	How to fix
HIGH-1	Commands are verbs — every command acting on a primary object must be a verb.	webui command (cmd/cli/commands/webui.go) uses a noun (webui) as the command name.	Should be a verb like launch-webui or open-webui.
HIGH-2	Do not offer both short and long flags for the same action.	main.go:68 — rootCmd.PersistentFlags().BoolVarP(&ctx.Verbose, "verbose", "v", false, "Enable verbose logging") exposes both --verbose and -v.	Remove the short flag -v; keep --verbose only.
MEDIUM-1	Use plural noun shorthand (foobars) for listing secondary objects instead of list-foobar.	list-engines and list-models use the list-foobar pattern for secondary objects (engines/models).	Rename to engines and models.
MEDIUM-2	Column headers should use upper case and bold font.	list-engines.go:105 — header row uses lowercase: {"engine", "vendor", "summary", "compat"}.	Use uppercase bold: {"ENGINE", "VENDOR", "SUMMARY", "COMPAT"}.
LOW-1	Error messages use lowercase error: prefix.	main.go:49 — "Error retrieving snap services: %v"; main.go:78,84 — "Error: %v". Standard uses lowercase error:.	Use error: consistently.
LOW-2	Show column headers by default but allow them to be hidden with --no-headers.	list-engines table output has no --no-headers flag.	Add a --no-headers boolean flag to suppress the header row.
LOW-3	Flag descriptions should be accurate.	unset.go:37 — --no-restart description reads "do not restart the snap after setting the configuration" but the command unsets, not sets.	Change to "...after unsetting the configuration".

---

Detailed analysis

[HIGH-1] webui is a noun, not a verb

CLI Standard citation: Grammar + Vocabulary — "Commands are verbs. Every command that acts on a primary object of a command must be a verb."

Evidence:

// cmd/cli/commands/webui.go
cobraCmd := &cobra.Command{
    Use:   "webui",
    Short: "Launch web UI",
    ...
}

The command name webui is an abbreviation (noun). It acts on a primary object (the snap's web interface) and should be a verb.

Remediation: Rename to launch-webui or open-webui.

---

[HIGH-2] --verbose / -v dual flag pattern

CLI Standard citation: Flags — "As a policy, do not offer both short and long flags for the same action."

Evidence:

// cmd/cli/main.go:68
rootCmd.PersistentFlags().BoolVarP(&ctx.Verbose, "verbose", "v", false, "Enable verbose logging")

Both --verbose and -v are registered for the same persistent flag. The standard requires choosing one format and sticking with it.

Remediation: Remove the -v short form. Keep --verbose only, as it is more descriptive and the standard generally prefers long flags for infrequent actions.

---

[MEDIUM-1] list-engines / list-models should use shorthand noun form

CLI Standard citation: Grammar + Vocabulary — "Use foobars as a shorthand for listing information about all instances of a specific type of secondary object instead of list-foobar (e.g. snap services over snap list-services)."

Evidence:

// cmd/cli/commands/list-engines.go
cobraCmd := &cobra.Command{
    Use:   "list-engines",
    ...
}
// cmd/cli/commands/list-models.go
cobraCmd := &cobra.Command{
    Use:   "list-models",
    ...
}

Engines and models are secondary objects of the CLI tool. The list-foobar form is explicitly discouraged in favor of the bare plural noun.

Remediation: Rename list-engines → engines and list-models → models.

---

[MEDIUM-2] Table column headers are lowercase instead of uppercase bold

CLI Standard citation: Tabular Data — "Column headers should use upper case (e.g. NAME, STATUS, etc) and bold font."

Evidence:

// cmd/cli/commands/list-engines.go:105
var headerRow = []string{"engine", "vendor", "summary", "compat"}

The header row uses all-lowercase strings. The renderer does apply bold via color.Bold, but the text case is incorrect.

Remediation: Change to {"ENGINE", "VENDOR", "SUMMARY", "COMPAT"}.

---

[LOW-1] Error messages use uppercase Error instead of lowercase error

CLI Standard citation: Errors, warnings and success messages — the standard consistently uses lowercase error: prefix in examples (e.g. error: cannot establish the connection, error: no matching snaps installed).

Evidence:

// cmd/cli/main.go:49 — this PR made it worse by removing the colon
fmt.Printf("Error retrieving snap services: %v\n", err)
// cmd/cli/main.go:78, 84
fmt.Printf("Error: %v\n", err)

The standard uses lowercase error: throughout. The PR change to line 49 dropped the colon entirely, further degrading compliance.

Remediation: Use fmt.Printf("error: ...") consistently.

---

[LOW-2] Missing --no-headers flag for table output

CLI Standard citation: Tabular Data — "Show column headers by default but allow them to be hidden with --no-headers."

Evidence: The list-engines command produces a table but only supports a --format flag (table/json). There is no --no-headers boolean flag.

Remediation: Add a --no-headers boolean flag that suppresses the header row when set.

---

[LOW-3] Inaccurate --no-restart description on unset command

CLI Standard citation: CLI Copy and Tone of Voice — "Be concise, precise, and clear at all times."

Evidence:

// cmd/cli/commands/unset.go:37
cobraCmd.Flags().BoolVar(&cmd.noRestart, "no-restart", false,
    "do not restart the snap after setting the configuration")

The flag is on the unset command but describes "setting" — it should say "unsetting" or "changing".

Remediation: Change description to "do not restart the snap after unsetting the configuration".

---

CLI changes in this PR

The PR introduces minor text changes to cmd/cli/main.go:

• The comment // It gets populated with subcommands was lowered to // it gets populated with subcommands (cosmetic).
• The long description lost a comma: "Use this command to configure the active engine, or switch..." → "Use this command to configure the active engine or switch..." (minor wording tweak — no standard impact).
• The error message "Error: retrieving snap services: %v\n" was changed to "Error retrieving snap services: %v\n", which worsens compliance by dropping the colon-separator after the error prefix. The standard requires lowercase error: format.

---

Summary

Severity	Count	Guideline Categories
High	2	Grammar, Flags
Medium	2	Grammar, Tabular Data
Low	3	Errors, Tabular Data, Flags
Unrated	0	—
Total	7

Overall rating: 82

The scoring algorithm starts with 100%, number of commands N, weight W=100/N. For each High violation, reduce by 1×W; Medium violation by 0.5×W; Low violation by 0.2×W. Clamp to 0–100.

---

View action run | Model: openrouter/deepseek/deepseek-v4-pro (thinking: medium) | Time: 2m 19s | Tokens: 309.9K | Cost: $0.11 | Pi SDK v0.79.10 | Action v2.22.0 #