cleveragents/cleveragents-core

Fork 3

feat(cli): final CLI polish and UX consistency pass #861

New issue

Closed

opened 2026-03-13 22:01:57 +00:00 by freemo · 1 comment

freemo commented

2026-03-13 22:01:57 +00:00

Owner

Metadata

Commit Message: feat(cli): final CLI polish and UX consistency pass
Branch: feature/m8-cli-polish

Background

M8 (v3.7.0) acceptance criterion: the CLI must receive a final polish and UX consistency pass. All CLI commands should have consistent help text, error messages, output formatting, and behavior patterns. This is the last opportunity to fix UX inconsistencies before the server milestone.

Expected Behavior

All CLI commands have consistent --help output format
Error messages follow a consistent pattern with actionable guidance
Output formatting is consistent (tables, JSON, text modes)
Exit codes are standardized
Shell completion works for all commands

Acceptance Criteria

All CLI commands have consistent help text
Error messages follow consistent pattern
Output formatting consistent across all commands
Exit codes standardized
Shell completion functional
Unit tests cover: help output, error formatting, exit codes

Subtasks

Audit all CLI commands for consistency
Standardize help text format
Standardize error message format
Standardize output formatting
Standardize exit codes
Implement shell completion
Tests (Behave): Add consistency verification scenarios
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata - **Commit Message**: `feat(cli): final CLI polish and UX consistency pass` - **Branch**: `feature/m8-cli-polish` ## Background M8 (v3.7.0) acceptance criterion: the CLI must receive a final polish and UX consistency pass. All CLI commands should have consistent help text, error messages, output formatting, and behavior patterns. This is the last opportunity to fix UX inconsistencies before the server milestone. ## Expected Behavior 1. All CLI commands have consistent `--help` output format 2. Error messages follow a consistent pattern with actionable guidance 3. Output formatting is consistent (tables, JSON, text modes) 4. Exit codes are standardized 5. Shell completion works for all commands ## Acceptance Criteria - [ ] All CLI commands have consistent help text - [ ] Error messages follow consistent pattern - [ ] Output formatting consistent across all commands - [ ] Exit codes standardized - [ ] Shell completion functional - [ ] Unit tests cover: help output, error formatting, exit codes ## Subtasks - [ ] Audit all CLI commands for consistency - [ ] Standardize help text format - [ ] Standardize error message format - [ ] Standardize output formatting - [ ] Standardize exit codes - [ ] Implement shell completion - [ ] Tests (Behave): Add consistency verification scenarios - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

freemo added the

labels

2026-03-13 22:02:08 +00:00

freemo added this to the v3.7.0 milestone

2026-03-13 22:02:12 +00:00

brent.edwards was assigned by freemo

2026-03-14 04:27:37 +00:00

brent.edwards added

and removed

labels

2026-03-17 01:13:17 +00:00

brent.edwards referenced this issue from a commit

2026-03-17 02:49:28 +00:00

feat(cli): final CLI polish and UX consistency pass

brent.edwards referenced this issue from a pull request that will close it,

2026-03-17 02:50:02 +00:00

feat(cli): final CLI polish and UX consistency pass #1018

brent.edwards referenced this issue from a commit

2026-03-17 02:51:37 +00:00

feat(cli): final CLI polish and UX consistency pass

brent.edwards added

and removed

labels

2026-03-17 02:51:56 +00:00

brent.edwards commented

2026-03-17 02:52:18 +00:00

Member

Implementation Notes

New Modules

cli/constants.py (70 lines): Standardized exit codes (EXIT_SUCCESS=0 through EXIT_CONFLICT=4) and format constants (FORMAT_TEXT, FORMAT_JSON, FORMAT_TABLE, VALID_FORMATS).

cli/errors.py (105 lines): Three utilities:

cli_error(message, hint=, exit_code=) — Rich-formatted error with optional actionable hint, raises SystemExit
cli_warning(message) — Non-fatal warning to stderr
cli_not_found(resource_type, name) — Resource-not-found with auto-generated hint ("Run 'agents {type} list'...")

Shell Completion

Added agents completion {bash|zsh|fish|powershell} command generating shell completion scripts via Typer's built-in mechanism.

Quality Gates

Session	Result
lint	PASS
typecheck	PASS (0 errors)
unit_tests	PASS (10,912 scenarios, 17 new)
integration_tests	PASS (15 new)
coverage	97%

Commit

1ccea894 on branch feature/m8-cli-polish

PR

PR #1018

## Implementation Notes ### New Modules **`cli/constants.py`** (70 lines): Standardized exit codes (EXIT_SUCCESS=0 through EXIT_CONFLICT=4) and format constants (FORMAT_TEXT, FORMAT_JSON, FORMAT_TABLE, VALID_FORMATS). **`cli/errors.py`** (105 lines): Three utilities: - `cli_error(message, hint=, exit_code=)` — Rich-formatted error with optional actionable hint, raises SystemExit - `cli_warning(message)` — Non-fatal warning to stderr - `cli_not_found(resource_type, name)` — Resource-not-found with auto-generated hint ("Run 'agents {type} list'...") ### Shell Completion Added `agents completion {bash|zsh|fish|powershell}` command generating shell completion scripts via Typer's built-in mechanism. ### Quality Gates | Session | Result | |---|---| | lint | PASS | | typecheck | PASS (0 errors) | | unit_tests | PASS (10,912 scenarios, 17 new) | | integration_tests | PASS (15 new) | | coverage | 97% | ### Commit `1ccea894` on branch `feature/m8-cli-polish` ### PR [PR #1018](https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/1018)

brent.edwards referenced this issue from a commit

2026-03-18 03:31:15 +00:00

feat(cli): final CLI polish and UX consistency pass

brent.edwards referenced this issue from a commit

2026-03-18 18:57:06 +00:00

feat(cli): final CLI polish and UX consistency pass

brent.edwards referenced this issue from a commit

2026-03-18 19:07:52 +00:00

feat(cli): final CLI polish and UX consistency pass

brent.edwards referenced this issue from a commit

2026-03-18 22:14:19 +00:00

feat(cli): final CLI polish and UX consistency pass