Specification

1. Terminology

The key words MUST, SHOULD, and MAY in this document are to be interpreted as requirement language for this convention. They are used in the ordinary RFC-style sense for clarity, but this document is not an IETF standard.

An emitter is any application, library, or other component that writes OSC 8 hyperlinks to a terminal stream. Terminal emulators, multiplexers, and pagers are considered terminal-side software.

2. Environment Variables

NO_HYPERLINKS

If NO_HYPERLINKS is present in the environment and its value is not the empty string, emitters MUST NOT emit OSC 8 hyperlink sequences unless explicitly overridden by a higher-precedence local control.

FORCE_HYPERLINKS

If FORCE_HYPERLINKS is present in the environment and its value is not the empty string, and NO_HYPERLINKS does not apply, emitters SHOULD emit OSC 8 hyperlink sequences even when automatic detection would otherwise disable them.

3. Precedence

Implementations SHOULD apply controls in the following order:

1. Explicit command-line flags or application config.
2. NO_HYPERLINKS.
3. FORCE_HYPERLINKS.
4. Automatic support and TTY detection.

If both environment variables are set to non-empty values, NO_HYPERLINKS MUST take precedence.

4. Local Overrides

Emitters SHOULD expose a local control such as --hyperlinks=auto|always|never or an equivalent config setting.

If an implementation offers local overrides, those controls MUST be documented as higher precedence than the environment variables defined here. This keeps behavior explicit and debuggable.

5. Fallback Rendering

When hyperlinks are disabled, emitters SHOULD render the destination URL in plain text when the destination is relevant to the user. Hyperlink-only labels that hide a meaningful destination should be avoided in disabled mode.

6. Terminal-Side Software

Terminal emulators, multiplexers, and pagers are not the primary normative target of this convention, but they play a practical interoperability role.

Terminal-side software SHOULD do one of the following predictably:

• Preserve OSC 8 sequences when configured to pass through styled output.
• Ignore or strip OSC 8 sequences safely without corrupting visible text.
• Document relevant behavior and any user-facing controls that affect hyperlinks.

7. Governance

This convention begins as v1. Feedback should be gathered through public issue tracking and cross-project adoption discussion. Future revisions SHOULD be additive where possible and MUST clearly describe any breaking semantic changes.