Bun CLI – Screen Reader Output Compatibility

Answer to the Core Question

Yes – Bun can expose a --plain-output flag that strips all ANSI escape sequences and injects minimal semantic markers (e.g., === Help ===) for help and version commands. For interactive prompts, Bun can emit a simple prompt string (e.g., > ) followed by a newline, so screen readers announce the focus change without altering the terminal’s input flow.

Why This Works

• ANSI removal – --plain-output or --no-color turns off color entirely, leaving plain text that screen readers read correctly.
• Semantic markers – Plain‑text headings like === Help === give a clear structure that assistive technologies can navigate, similar to ARIA headings.
• Focus announcements – A predictable prompt string is read by the screen reader as soon as it appears, mimicking the behavior of tools like readline in many shells.

Implementation Steps (for the Bun maintainers)

1. Add flags
   • --plain-output – forces stripping of all \x1b[ sequences.
   • Keep --no-color for backward compatibility.
2. Detect terminal capabilities – If process.stdout.isTTY is false, default to plain output to avoid garbled escape codes in non‑interactive contexts.
3. Inject headings
   • For bun help and bun --version, prepend === Help === or === Version === when --plain-output is set.
   • Keep the original colored output when the flag is absent.
4. Prompt handling
   • When an interactive prompt is requested, output > followed by a newline before reading stdin.
   • Do not modify the prompt’s key‑binding logic; the string is purely for screen‑reader announcement.
5. Environment variable support
   • Introduce BUN_COLOR=never as an alternative to --no-color for scripts that set environment variables.
6. Testing & verification
   • Run bun --plain-output help > out.txt and grep for \x1b; the file should be clean.
   • Use a screen reader to confirm that === Help === is announced as a heading.
   • Interact with bun repl and ensure the prompt is read without extra keystrokes.
   • Run automated scripts that parse Bun output before and after the change to catch regressions.

Potential Pitfalls and Mitigations

• Scripts that rely on color codes for parsing may break – provide a clear deprecation notice and encourage use of the new flag.
• Adding headings increases output length; document that the headings are optional and can be disabled if needed.
• Prompt string output could interfere with programs that read raw stdin; the change is non‑intrusive because the string is identical to the existing prompt seen by users.

Diagnostic Question

Does your workflow rely on parsing Bun’s output (e.g., for CI scripts or log aggregation) where color codes or exact spacing matter? If so, we may need to provide a separate --plain-output-no-headers option to preserve the original formatting while still removing ANSI sequences.

Conclusion

By introducing a --plain-output flag, optional semantic headings, and a screen‑reader‑friendly prompt, Bun can become accessible to users who rely on assistive technology while remaining fully compatible with existing terminal workflows.