Color Support

ebcprep outputs color-coded status messages, section headers, and sync summaries to your terminal using the Rich library. This page explains how ebcprep detects whether your terminal supports color, what controls that detection, and how to force color on or off when the defaults do not match your environment — for example when running inside a CI pipeline, a log file redirect, or a terminal emulator that reports color support incorrectly.

Before working through this page, you should have:

• ebcprep installed (uv tool install --from ~/path/to/ebcprep-orchestrator ebcprep)
• A terminal emulator (macOS Terminal, iTerm2, VS Code integrated terminal, or similar)
• Basic familiarity with environment variables

No additional packages are required — Rich is already a dependency of ebcprep.

1. Confirm ebcprep is installed:

ebcprep --version

2. Confirm Rich is available in the same environment:

uv run python -c "import rich; print(rich.__version__)"

If this raises ModuleNotFoundError, reinstall ebcprep:

uv tool install --from ~/path/to/ebcprep-orchestrator ebcprep --force --reinstall

3. Run a quick smoke test to see color output in your current terminal:

ebcprep doctor

You should see colored check marks (✓ in green, ✗ in red) next to each health-check item. If the output appears as plain text without color, continue to the Configuration section below.

ebcprep inherits Rich's standard color-detection behavior. Rich inspects the terminal environment automatically on startup and enables or disables color accordingly. You can override that detection with the following standard environment variables — set them in your shell, in a CI environment, or in your .env file.

Why these matter for ebcprep specifically:

• When you redirect output to a log file (e.g. nohup ebcprep --verbose sync > data/sync.log 2>&1 &), Rich detects that stdout is not a TTY and automatically disables color — so data/sync.log will contain clean plain text suitable for grep and tail.
• If you run ebcprep sync inside a CI pipeline that supports ANSI color (GitHub Actions, GitLab CI), set FORCE_COLOR=1 so the colored summary is visible in the pipeline log.
• If your terminal renders raw escape codes as literal characters (e.g. \x1b[32m✓), set NO_COLOR=1 to disable them.

In normal interactive use you do not need to configure anything — ebcprep detects your terminal automatically and renders color where it is supported.

Suppress color for a single command:

NO_COLOR=1 ebcprep sync --dry-run

Force color on when piping or logging:

FORCE_COLOR=1 ebcprep sync 2>&1 | tee data/sync.log

Redirect to a log file (color disabled automatically):

nohup ebcprep --verbose sync > data/sync.log 2>&1 &

Because stdout is not a TTY in this case, Rich suppresses color automatically. The log file will contain plain readable text. Monitor it with:

tail -f data/sync.log

Check whether color is active before a run:

ebcprep doctor

If the ✓ and ✗ symbols appear in green and red, color is active. If they appear in monochrome or as raw escape sequences, adjust NO_COLOR or FORCE_COLOR as described in the Configuration section.

Example 1 — Default interactive run (color enabled automatically)

ebcprep doctor

Expected output (colors rendered in terminal):

✓  nlm profile authenticated   (profile: ebcprep)
✓  Sheet readable               (42 rows)
✓  Service account JSON found
✓  defaults.toml loaded         (1 collaborator, 1 default source)

Example 2 — Suppress color with NO_COLOR

NO_COLOR=1 ebcprep doctor

Expected output (no ANSI codes, plain text):

✓  nlm profile authenticated   (profile: ebcprep)
✓  Sheet readable               (42 rows)
✓  Service account JSON found
✓  defaults.toml loaded         (1 collaborator, 1 default source)

The content is identical; only the color styling is absent.

Example 3 — Force color on in a CI pipeline

FORCE_COLOR=1 ebcprep sync --dry-run

Expected output: colored section headers and a colored summary table are preserved in the CI log, making it easier to scan for failures.

Example 4 — Background sync with plain-text log

nohup ebcprep --verbose sync > data/sync.log 2>&1 &
tail -f data/sync.log

Because stdout is redirected to a file (not a TTY), Rich disables color automatically. The log file contains clean plain text with no escape sequences.

Symptom: Output contains raw escape codes like \x1b[32m✓\x1b[0m

• Cause: Your terminal emulator does not interpret ANSI escape codes, but Rich believes it does (possibly because COLORTERM or TERM is set to a value that implies color support).
• Fix: Set NO_COLOR=1 before running ebcprep:
  Copy

  NO_COLOR=1 ebcprep sync --dry-run
  

  To make this permanent, add NO_COLOR=1 to your shell profile (~/.zshrc or ~/.bash_profile) or to your .env file.

Symptom: Log file at data/sync.log contains ANSI color codes

• Cause: FORCE_COLOR=1 is set in the environment, overriding Rich's TTY detection.
• Fix: Unset FORCE_COLOR before redirecting output, or explicitly set NO_COLOR=1 for the background command:
  Copy

  NO_COLOR=1 nohup ebcprep --verbose sync > data/sync.log 2>&1 &
  

Symptom: CI pipeline log shows no color even though the CI runner supports ANSI

• Cause: The runner's stdout is not a PTY, so Rich correctly detects "no TTY" and disables color.
• Fix: Set FORCE_COLOR=1 in your CI environment variables or prefix the command:
  Copy

  FORCE_COLOR=1 ebcprep sync
  

Symptom: Colors appear but look wrong (e.g. green renders as a different color)

• Cause: Your terminal is set to a custom color scheme that remaps standard ANSI color indices.
• Fix: This is a terminal theme issue, not an ebcprep issue. Adjust your terminal's color palette, or set NO_COLOR=1 to use unstyled output that is unaffected by theme remapping.

Symptom: Color output disappeared after upgrading ebcprep

• Cause: uv tool install makes a frozen snapshot; a stale install may be missing updated Rich configuration.
• Fix: Reinstall ebcprep to refresh the snapshot:
  Copy

  uv tool install --from ~/path/to/ebcprep-orchestrator ebcprep --force --reinstall