no-hyperlinks

v1 Draft Convention

Terminal hyperlinks should respect user intent.

NO_HYPERLINKS disables OSC 8 hyperlinks globally. FORCE_HYPERLINKS enables them when local heuristics would otherwise hold back. Together they provide a small, predictable control surface for CLI tools, shared output libraries, terminal emulators, multiplexers, and pagers.

Read the specification See adoption guidance

The convention

If NO_HYPERLINKS is present and non-empty, emitters do not write OSC 8 sequences. If FORCE_HYPERLINKS is present and non-empty, emitters should write OSC 8 sequences unless a stronger local override says otherwise.

The point

Users already have global knobs for color. Hyperlinks deserve the same clarity for accessibility, privacy, security review, and plain old preference.

Simple precedence

Explicit CLI or config settings win first. Then NO_HYPERLINKS. Then FORCE_HYPERLINKS. After that, tools may fall back to normal support detection.

Emitter-centered

The normative behavior targets applications and libraries that generate terminal output. Terminal-side software is encouraged to preserve and document compatible behavior.

Adoption-first

This is a de facto convention, not an ECMA, ISO, or IETF standard. It becomes real through consistent implementation and public documentation.

Normative summary

Recommended decision flow

  1. Respect explicit command-line or application config overrides first.
  2. If NO_HYPERLINKS is set and non-empty, disable OSC 8 emission.
  3. Else if FORCE_HYPERLINKS is set and non-empty, enable OSC 8 emission.
  4. Else apply normal TTY and capability detection.
  5. When disabled, render user-relevant destinations as readable plain text rather than hyperlink-only labels.

For tool authors

Expose a local override too

The recommended interface is --hyperlinks=auto|always|never or an equivalent config setting. This gives users a per-tool escape hatch without undermining the global convention.

For terminal-side software

Stay predictable

Emulators, multiplexers, and pagers should either preserve OSC 8 sequences, ignore them safely, or document the conditions under which they are stripped or transformed.