Add colour to the CLI on a terminal, and nothing at all when piped

Human-mode output gains a Claude-Code-style colour hierarchy: dim labels,
accented names and paths, semantic status colour (goal_met and admitted
green, rejected and REFUSED red), and aligned key/value blocks.

The whole design rests on one constraint: styling is decided at print time
from the stream's own isatty(), so piped, redirected and captured output is
byte-identical to before. That is what lets this land without touching a
single expected block — tests/test_readme.py and tests/test_cookbook_models.py
byte-compare CLI output against README.md and docs/cookbook/02-models.md, and
both harnesses present a non-tty stdout. Padding is emitted outside the
escape sequences, so a column is the same character count either way.

Verified: 50/36/32/18 escapes on a pty for plan/models/models --check/demo,
zero escapes on every piped stream, and ANSI-stripped tty output identical to
piped output. NO_COLOR, TERM=dumb, --no-color and --json each yield zero
escapes. The contracts that matter are unchanged — --json is one parseable
document on stdout with zero-byte stderr, a text-mode failure leaves stdout
empty with "error: ..." on stderr, viz stays raw pasteable Mermaid, and
replay/diff still emit only the engine formatter's text.

New grapharc/cli/style.py is stdlib only. No dependency was added: rich is
not in the lock, and the README markets a four-package runtime dep list.

Deliberately no glyphs, boxes or rules, even on a terminal. README and two
cookbook pages print these blocks verbatim, so tty-only decoration would
make what a user sees diverge from what the docs show — drift in the one
direction the byte-comparison tests cannot catch.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Shashankss1205

grapharc/cli/agent.py

@@ -20,7 +20,7 @@
 from pathlib import Path
 from typing import Any
 
-from grapharc.cli import optional
+from grapharc.cli import optional, style
 from grapharc.cli.output import EXIT_FAILED, EXIT_OK, emit, fail
 
 # Entry points accepted from `grapharc.tools`, in preference order: a registrar
@@ -241,24 +241,62 @@ def run_agent(
         "refused": len(result.refused),
     }
 
+    width = style.LABEL_WIDTH
+    note = f"  {style.dim(f'({result.note})')}" if result.note else ""
+
+    def count(number: int) -> str:
+        """A count, red once it is not zero.
+
+        Zero refusals is not news; one is the reason to read the tool-call rows
+        underneath it. The digits are the same either way when colour is off.
+        """
+        return style.err(str(number)) if number else str(number)
+
     lines = [
-        f"task      : {task}",
-        f"model     : {model_spec}",
-        f"workspace : {workspace}",
-        f"tools     : {', '.join(visible) or '(none visible under this policy)'}",
-        f"policy    : allow={allow} ask={ask} deny={deny}",
+        style.kv("task", task, width=width),
+        style.kv("model", model_spec, width=width, tint=style.accent),
+        style.kv("workspace", str(workspace), width=width, tint=style.accent),
+        style.kv(
+            "tools",
+            ", ".join(visible) or "(none visible under this policy)",
+            width=width,
+        ),
+        style.kv(
+            "policy",
+            f"{style.dim('allow=')}{allow} {style.dim('ask=')}{ask} {style.dim('deny=')}{deny}",
+            width=width,
+        ),
         "",
-        f"stopped   : {reason}{f'  ({result.note})' if result.note else ''}",
-        f"turns     : {result.iterations}   tool calls: {len(result.tool_calls)}   "
-        f"denied: {len(result.denied)}   refused: {len(result.refused)}",
-        f"tokens    : {meter.tokens:,}",
+        style.kv(
+            "stopped",
+            f"{(style.ok if met else style.warn)(reason)}{note}",
+            width=width,
+        ),
+        style.kv(
+            "turns",
+            f"{result.iterations}   {style.dim('tool calls:')} {len(result.tool_calls)}   "
+            f"{style.dim('denied:')} {count(len(result.denied))}   "
+            f"{style.dim('refused:')} {count(len(result.refused))}",
+            width=width,
+        ),
+        style.kv("tokens", f"{meter.tokens:,}", width=width),
     ]
     for call in result.tool_calls:
-        suffix = f" [{call.refused_by}]" if call.refused_by else ""
-        lines.append(f"   {call.status.value:<8} {call.tool}{suffix}")
+        suffix = f" {style.dim(f'[{call.refused_by}]')}" if call.refused_by else ""
+        # `ToolCallStatus` is ok / denied / error; anything a later version adds
+        # lands on amber rather than being quietly called a success.
+        verdict = {"ok": True, "denied": False, "error": False}.get(call.status.value)
+        lines.append(
+            f"   {style.cell(call.status.value, 8, tint=style.tint_for(verdict))} "
+            f"{style.accent(call.tool)}{suffix}"
+        )
     lines.append("")
-    lines.append(f"answer    : {result.output}" if met else f"partial   : {result.partial_output}")
-    lines.append(f"trace     : {trace_path}")
+    lines.append(
+        style.kv("answer", str(result.output), width=width)
+        if met
+        else style.kv("partial", str(result.partial_output), width=width, tint=style.dim)
+    )
+    lines.append(style.kv("trace", str(trace_path), width=width, tint=style.accent))
 
     emit(payload, lines, as_json=as_json)
     return EXIT_OK if met else EXIT_FAILED

grapharc/cli/graphrun.py

@@ -38,6 +38,7 @@
 from pathlib import Path
 from typing import Any
 
+from grapharc.cli import style
 from grapharc.cli.config import ConfigError
 from grapharc.cli.config import load as load_settings
 from grapharc.cli.generate import resolve_or_generate_policy
@@ -183,15 +184,32 @@ def run_graph(
         **settings.provenance(policy_source=policy_source),
     }
 
+    # `REFUSED` and `ADMITTED` are the whole answer, so on a terminal they carry
+    # the only two colours that matter here. The words, the widths and the order
+    # are untouched: `--check-only` is what CI runs, and CI reads text.
+    width = style.LABEL_WIDTH
+    header = [
+        style.kv("graph", graph_path, width=width, tint=style.accent),
+        style.kv("policy", policy_description, width=width),
+    ]
+    trace_line = style.kv("trace", str(trace_path), width=width, tint=style.accent)
+
     if not verdict.admitted:
         lines = [
-            f"graph     : {graph_path}",
-            f"policy    : {policy_description}",
+            *header,
             "",
-            f"REFUSED   : {len(verdict.rejections)} objection(s)",
+            style.kv(
+                "REFUSED",
+                f"{len(verdict.rejections)} objection(s)",
+                width=width,
+                key_tint=style.err,
+                tint=style.err,
+            ),
+        ]
+        lines += [
+            f"   {style.cell(r.code, 18, tint=style.err)} {r.detail}" for r in verdict.rejections
         ]
-        lines += [f"   {r.code:<18} {r.detail}" for r in verdict.rejections]
-        lines += ["", f"trace     : {trace_path}"]
+        lines += ["", trace_line]
         emit({"ok": False, **common}, lines, as_json=as_json)
         return EXIT_FAILED
 
@@ -210,13 +228,12 @@ def run_graph(
         compiled = materializer.materialize(verdict, proposal)
     except MaterializationError as exc:
         lines = [
-            f"graph     : {graph_path}",
-            f"policy    : {policy_description}",
+            *header,
             "",
-            "ADMITTED, BUT CANNOT BE BUILT",
+            style.err("ADMITTED, BUT CANNOT BE BUILT"),
             f"   {exc}",
             "",
-            f"trace     : {trace_path}",
+            trace_line,
         ]
         emit(
             {"ok": False, "buildable": False, "error": str(exc), **common},
@@ -227,12 +244,13 @@ def run_graph(
 
     if check_only:
         lines = [
-            f"graph     : {graph_path}",
-            f"policy    : {policy_description}",
-            f"nodes     : {proposal.node_count()}",
+            *header,
+            style.kv("nodes", str(proposal.node_count()), width=width),
             "",
-            "ADMITTED and buildable. Nothing was run.",
-            f"fingerprint: {verdict.fingerprint}",
+            style.ok("ADMITTED") + style.dim(" and buildable. Nothing was run."),
+            # Wider than the label column on purpose, and always has been: the
+            # fingerprint is what a later run is compared against.
+            style.kv("fingerprint", verdict.fingerprint, width=width, tint=style.accent),
         ]
         emit(
             {"ok": True, "checked_only": True, "buildable": True, **common},
@@ -245,13 +263,12 @@ def run_graph(
 
     payload = {"ok": True, "checked_only": False, **common, "state": state}
     lines = [
-        f"graph     : {graph_path}",
-        f"policy    : {policy_description}",
-        f"nodes     : {proposal.node_count()}",
+        *header,
+        style.kv("nodes", str(proposal.node_count()), width=width),
         "",
-        "ADMITTED and executed.",
-        f"state     : {state}",
-        f"trace     : {trace_path}",
+        style.ok("ADMITTED") + style.dim(" and executed."),
+        style.kv("state", str(state), width=width),
+        trace_line,
     ]
     emit(payload, lines, as_json=as_json)
     return EXIT_OK

grapharc/cli/live.py

@@ -15,6 +15,7 @@
 
 from pathlib import Path
 
+from grapharc.cli import style
 from grapharc.cli.output import EXIT_FAILED, EXIT_OK, emit
 from grapharc.gateway import different_providers, get_model
 from grapharc.observe.metrics import summarize
@@ -23,6 +24,10 @@
 
 DEFAULT_REVIEWER = "openrouter/openai/gpt-4o-mini"
 
+#: The header labels line up at nine characters, which is what `model`,
+#: `reviewer` and `budget` have always printed at.
+LABEL_WIDTH = 9
+
 # Real models are open-ended, so a live run always carries a ceiling.
 LIVE_BUDGET = Budget(max_iterations=40, max_tokens=200_000, max_seconds=600)
 
@@ -55,22 +60,32 @@ def say(line: str) -> None:
         if not as_json:
             print(line)
 
-    say(f"model    : {model_spec}")
+    say(style.kv("model", model_spec, width=LABEL_WIDTH, tint=style.accent))
     model = get_model(model_spec, temperature=0)
 
     reviewer = None
     correlated = None
     if _needs_reviewer(example):
         reviewer_spec = reviewer_spec or DEFAULT_REVIEWER
-        say(f"reviewer : {reviewer_spec}")
+        say(style.kv("reviewer", reviewer_spec, width=LABEL_WIDTH, tint=style.accent))
         correlated = not different_providers(model_spec, reviewer_spec)
         if correlated:
+            # Amber, not red: the run is still valid, the evidence is just weaker.
             say(
-                "  warning: author and reviewer share a provider — correlated "
-                "agreement makes this weaker evidence than a cross-vendor pair"
+                style.warn(
+                    "  warning: author and reviewer share a provider — correlated "
+                    "agreement makes this weaker evidence than a cross-vendor pair"
+                )
             )
         reviewer = get_model(reviewer_spec, temperature=0)
-    say(f"budget   : {LIVE_BUDGET.max_tokens:,} tokens / {LIVE_BUDGET.max_seconds:.0f}s")
+    say(
+        style.kv(
+            "budget",
+            f"{LIVE_BUDGET.max_tokens:,}{style.dim(' tokens / ')}"
+            f"{LIVE_BUDGET.max_seconds:.0f}{style.dim('s')}",
+            width=LABEL_WIDTH,
+        )
+    )
     say("")
 
     header = {
@@ -90,7 +105,7 @@ def say(line: str) -> None:
     if result is None:
         emit(
             {"ok": False, **header, "error": f"'{example}' has no live wiring yet"},
-            [f"'{example}' has no live wiring yet"],
+            [style.err(f"'{example}' has no live wiring yet")],
             as_json=as_json,
         )
         return EXIT_FAILED
@@ -99,14 +114,18 @@ def say(line: str) -> None:
     lines = []
     for key, value in result.items():
         rendered = str(value)
-        lines.append(f"{key}: {rendered[:400]}{'…' if len(rendered) > 400 else ''}")
+        clipped = f"{rendered[:400]}{'…' if len(rendered) > 400 else ''}"
+        lines.append(style.kv(str(key), clipped))
     if metrics:
         lines.append("")
         lines.append(
-            f"spent: {metrics.tokens:,} tokens across {metrics.nodes_executed} nodes "
-            f"in {metrics.duration_ms / 1000:.1f}s"
+            style.kv(
+                "spent",
+                f"{metrics.tokens:,}{style.dim(' tokens across ')}{metrics.nodes_executed}"
+                f"{style.dim(' nodes in ')}{metrics.duration_ms / 1000:.1f}{style.dim('s')}",
+            )
         )
-    lines.append(f"trace: {trace_path}")
+    lines.append(style.kv("trace", str(trace_path), tint=style.accent))
 
     emit(
         {"ok": True, **header, "result": result, "metrics": metrics},