CLI UX Design

Purpose

Agent-first CLI design skill for commands that serve both machine consumers (JSON envelopes via

--json

) and human operators (Rich terminal output). Covers the dual-output routing pattern, structured JSON envelopes with HATEOAS next actions, Rich progress indicators, data model conventions, and terminal visual language used across the

ai-eng

CLI.

Trigger

• Command: agent invokes cli-ux skill or user requests CLI command design/review.
• Context: new CLI command, CLI output review, adding

  --json

  support, improving terminal UX, adding progress indicators.

When NOT to Use

• API endpoint design — use

  dev:api-design

  for REST/GraphQL contract-first design.
• CI/CD pipeline configuration — use

  dev:cicd-generate

  for pipeline setup.
• General code review — use

  dev:code-review

  for implementation review.
• Test strategy for CLI commands — use

  dev:test-strategy

  for test design.

Procedure

1. Understand output context — determine if the command needs JSON mode, human mode, or both.

   • All user-facing commands MUST support both modes (dual-output).
   • Internal/plumbing commands may be JSON-only.
   • Read

     src/ai_engineering/cli_output.py

     for the routing pattern.

2. Design data model — every result gets both

   to_dict()

   and

   to_markdown()

   .

   • to_dict()

     : returns a JSON-serializable dict for the envelope.

   • to_markdown()

     : returns a human-readable markdown string.
   • Serialization rules:

     Path

     →

     .as_posix()

     , dates →

     .isoformat()

     , enums →

     .value

     .
   • Use Pydantic models or

     @dataclass

     — never raw dicts as primary data structures.

3. Implement dual-output routing — branch on

   is_json_mode()

   .
   • JSON path:

     emit_success(command_name, data_dict, [NextAction(...)])

     → stdout.
   • JSON errors:

     emit_error(command_name, message, error_code, fix, [NextAction(...)])

     → stdout.
   • Human path:

     result_header()

     ,

     kv()

     ,

     status_line()

     ,

     suggest_next()

     → stderr.
   • Rule: JSON goes to stdout, human messaging goes to stderr (CLIG guideline).
   • Use

     output()

     router from

     cli_output.py

     for clean branching.

4. Design JSON envelope — follow the

   SuccessEnvelope

   /

   ErrorEnvelope

   contract.
   • Success:

     { ok: true, command: str, result: dict, next_actions: [...] }

     .
   • Error:

     { ok: false, command: str, error: { message, code }, fix: str, next_actions: [...] }

     .
   • HATEOAS

     NextAction

     :

     { command: str, description: str, params?: dict }

     — suggest follow-up commands.
   • Use

     truncate_list(items, max_items=20)

     for large collections to protect agent context windows.

5. Add progress indicators — wrap long operations in

   spinner()

   or

   step_progress()

   .

   • spinner(description)

     : single-step context manager for indeterminate waits.

   • step_progress(total, description)

     : multi-step tracker with

     tracker.step(msg)

     .
   • Auto-suppressed in JSON mode (

     is_json_mode()

     ) and non-TTY (CI, piped output).
   • Transient by default — spinners disappear when done, leaving clean output.
   • Gate hooks (pre-commit, commit-msg, pre-push): NEVER add progress indicators.

6. Apply visual language — consistent Rich markup and color semantics.

   • Success:

     [success]

     (green). Error:

     [error]

     (red). Warning:

     [warning]

     (yellow). Info:

     [info]

     (blue).
   • Brand accent:

     [brand]

     (teal

     #00D4AA

     ). Muted:

     [muted]

     (dim). Paths:

     [path]

     (teal underline).
   • Key-value pairs:

     kv(key, value)

     . File counts:

     file_count(label, count)

     .
   • Section dividers:

     header(title)

     . Result summary:

     result_header(label, status, detail)

     .
   • Next steps:

     suggest_next([(command, description), ...])

     .
   • Respect

     NO_COLOR

     ,

     TERM=dumb

     , and non-TTY detection (handled by

     get_console()

     ).

7. Validate output contract — verify both output modes work correctly.

   • JSON: output is valid JSON, parseable by

     json.loads()

     .
   • JSON: envelope matches

     SuccessEnvelope

     /

     ErrorEnvelope

     schema.
   • Human: output is readable, no raw dicts or repr strings.
   • Test:

     --json

     flag produces stdout-only JSON; human mode produces stderr-only Rich output.

Output Contract

• CLI command with dual-output support (JSON + human).
• Data model with

  to_dict()

  and

  to_markdown()

  methods.
• JSON envelope conforming to

  SuccessEnvelope

  /

  ErrorEnvelope

  .
• Progress indicators that auto-suppress in JSON/non-TTY contexts.

Governance Notes

• CLI output modules are framework-managed — changes require governance review.
• JSON envelope schema (

  SuccessEnvelope

  /

  ErrorEnvelope

  ) is a contract — do not modify fields without versioning.
• Human output primitives (

  cli_ui.py

  ) are shared — additions are welcome, removals require deprecation.
• All new commands must pass

  --json

  output validation in tests.

Iteration Limits

• Max 3 attempts to resolve the same CLI output issue. After 3 failures, escalate to user with evidence.

Post-Action Validation

• After implementing dual-output, verify JSON is parseable with

  json.loads()

  .
• Run the command with and without

  --json

  to confirm both paths work.
• If validation fails, fix issues and re-validate (max 3 attempts).

References

• standards/framework/stacks/python.md

  — Python stack patterns.

Implementation Files (repo root-relative)

Read these on-demand when implementing or reviewing CLI commands:

1. src/ai_engineering/cli_envelope.py

   — JSON envelope (

   SuccessEnvelope

   ,

   ErrorEnvelope

   ,

   NextAction

   ).

2. src/ai_engineering/cli_ui.py

   — Rich human output primitives (

   kv

   ,

   status_line

   ,

   result_header

   ,

   suggest_next

   ).

3. src/ai_engineering/cli_output.py

   — dual-mode router (

   is_json_mode

   ,

   output

   ).

4. src/ai_engineering/cli_progress.py

   — spinner and step_progress context managers.

5. src/ai_engineering/cli_commands/core.py

   — reference implementation (install, doctor commands).