UAT: CLEVERAGENTS_FORMAT environment variable is registered in config but never read by the CLI (spec violation) #4080

New issue

Open

opened 2026-04-06 10:07:30 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:07:30 +00:00

Owner

Metadata

Branch: fix/cli-cleveragents-format-env-var
Commit Message: fix(cli): read CLEVERAGENTS_FORMAT env var for default output format
Milestone: (none — backlog)
Parent Epic: #399 (Epic: Post-MVP Server & Clients — nearest applicable CLI epic)

Bug Report

What was tested: Whether the CLEVERAGENTS_FORMAT environment variable is respected by the CLI as the spec requires.

Expected behavior (from spec, ADR-021, and docs/specification.md line 26694):

The spec defines a format resolution precedence chain:

--format CLI flag > CLEVERAGENTS_FORMAT env var > core.format config key > default (rich)

ADR-021 explicitly states:

"The format is resolved per-invocation: --format CLI flag > CLEVERAGENTS_FORMAT env var > core.format config key > default (rich)."

Setting CLEVERAGENTS_FORMAT=plain should cause all CLI commands to output in plain format without requiring --format plain on every invocation. This is critical for accessibility: users who need screen-reader-compatible output (e.g., CLEVERAGENTS_FORMAT=plain or CLEVERAGENTS_FORMAT=json) should be able to set it once in their environment.

Actual behavior (from code analysis):

The CLEVERAGENTS_FORMAT env var is registered in ConfigService (src/cleveragents/application/services/config_service.py, line 154) but is never read by the CLI format resolution logic.

Evidence:

src/cleveragents/cli/output/__init__.py documents this as SD-15: "The spec defines CLEVERAGENTS_FORMAT for overriding the default format. This implementation only accepts --format CLI flag."
src/cleveragents/cli/output/selection.py — select_materializer() does not check CLEVERAGENTS_FORMAT.
All CLI command --format options hardcode = "rich" as the default (e.g., action.py:217, db.py:53, invariant.py:123, etc.) without consulting the config service or env var.
src/cleveragents/cli/main.py — main_callback() does not read CLEVERAGENTS_FORMAT.

Steps to reproduce:

export CLEVERAGENTS_FORMAT=plain
agents actor list
# Expected: plain text output
# Actual: rich formatted output (env var ignored)

Code locations:

src/cleveragents/cli/output/__init__.py — SD-15 documents the deviation
src/cleveragents/cli/output/selection.py — select_materializer() missing env var check
src/cleveragents/cli/main.py — main_callback() missing env var read
All --format option defaults in src/cleveragents/cli/commands/*.py

Accessibility impact: High. Users who rely on screen readers or pipe output to tools need a persistent way to set plain/JSON output without adding --format to every command. The env var is the standard mechanism for this.

Subtasks

Read CLEVERAGENTS_FORMAT env var in select_materializer() or in a shared format-resolution helper
Update all --format option defaults to use the resolved default (from env var / config) instead of hardcoded "rich"
Add tests verifying CLEVERAGENTS_FORMAT is respected
Remove SD-15 from src/cleveragents/cli/output/__init__.py once implemented

Definition of Done

CLEVERAGENTS_FORMAT=plain agents actor list outputs plain text
CLEVERAGENTS_FORMAT=json agents plan list outputs JSON
--format flag still overrides the env var
All existing tests pass
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/cli-cleveragents-format-env-var` - **Commit Message**: `fix(cli): read CLEVERAGENTS_FORMAT env var for default output format` - **Milestone**: (none — backlog) - **Parent Epic**: #399 (Epic: Post-MVP Server & Clients — nearest applicable CLI epic) ## Bug Report **What was tested:** Whether the `CLEVERAGENTS_FORMAT` environment variable is respected by the CLI as the spec requires. **Expected behavior (from spec, ADR-021, and `docs/specification.md` line 26694):** The spec defines a format resolution precedence chain: ``` --format CLI flag > CLEVERAGENTS_FORMAT env var > core.format config key > default (rich) ``` ADR-021 explicitly states: > "The format is resolved per-invocation: `--format` CLI flag > `CLEVERAGENTS_FORMAT` env var > `core.format` config key > default (`rich`)." Setting `CLEVERAGENTS_FORMAT=plain` should cause all CLI commands to output in plain format without requiring `--format plain` on every invocation. This is critical for accessibility: users who need screen-reader-compatible output (e.g., `CLEVERAGENTS_FORMAT=plain` or `CLEVERAGENTS_FORMAT=json`) should be able to set it once in their environment. **Actual behavior (from code analysis):** The `CLEVERAGENTS_FORMAT` env var is registered in `ConfigService` (`src/cleveragents/application/services/config_service.py`, line 154) but is **never read by the CLI format resolution logic**. Evidence: 1. `src/cleveragents/cli/output/__init__.py` documents this as **SD-15**: "The spec defines `CLEVERAGENTS_FORMAT` for overriding the default format. This implementation only accepts `--format` CLI flag." 2. `src/cleveragents/cli/output/selection.py` — `select_materializer()` does not check `CLEVERAGENTS_FORMAT`. 3. All CLI command `--format` options hardcode `= "rich"` as the default (e.g., `action.py:217`, `db.py:53`, `invariant.py:123`, etc.) without consulting the config service or env var. 4. `src/cleveragents/cli/main.py` — `main_callback()` does not read `CLEVERAGENTS_FORMAT`. **Steps to reproduce:** ```bash export CLEVERAGENTS_FORMAT=plain agents actor list # Expected: plain text output # Actual: rich formatted output (env var ignored) ``` **Code locations:** - `src/cleveragents/cli/output/__init__.py` — SD-15 documents the deviation - `src/cleveragents/cli/output/selection.py` — `select_materializer()` missing env var check - `src/cleveragents/cli/main.py` — `main_callback()` missing env var read - All `--format` option defaults in `src/cleveragents/cli/commands/*.py` **Accessibility impact:** High. Users who rely on screen readers or pipe output to tools need a persistent way to set plain/JSON output without adding `--format` to every command. The env var is the standard mechanism for this. ## Subtasks - [ ] Read `CLEVERAGENTS_FORMAT` env var in `select_materializer()` or in a shared format-resolution helper - [ ] Update all `--format` option defaults to use the resolved default (from env var / config) instead of hardcoded `"rich"` - [ ] Add tests verifying `CLEVERAGENTS_FORMAT` is respected - [ ] Remove SD-15 from `src/cleveragents/cli/output/__init__.py` once implemented ## Definition of Done - [ ] `CLEVERAGENTS_FORMAT=plain agents actor list` outputs plain text - [ ] `CLEVERAGENTS_FORMAT=json agents plan list` outputs JSON - [ ] `--format` flag still overrides the env var - [ ] All existing tests pass - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:07:57 +00:00

#399 Epic: Post-MVP Server & Clients

freemo referenced this issue

2026-04-06 10:09:24 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 10:10:08 +00:00

freemo referenced this issue

2026-04-06 10:15:49 +00:00