Hyperlinks in Terminal Emulators

Hyperlinks_in_Terminal_Emulators.md

Hyperlinks (a.k.a. HTML-like anchors) in terminal emulators

[ Update 2020-05-31: I won't be maintaining this page or responding to comments anymore (except for perhaps a few exceptional occasions). ]

---

Most of the terminal emulators auto-detect when a URL appears onscreen and allow to conveniently open them (e.g. via Ctrl+click or Cmd+click, or the right click menu).

It was, however, not possible until now for arbitrary text to point to URLs, just as on webpages.

In spring 2017, GNOME Terminal and iTerm2 have changed this.

GNOME Terminal is based on the VTE widget, and almost all of this work went to VTE. As such, we expect other VTE-based terminal emulators to catch up and add support really soon. Other terminal emulators are also welcome and encouraged to join!

Quick example

Here's a simple command to try out the feature. The result is equivalent to this HTML link: This is a link

printf '\e]8;;http://example.com\e\\This is a link\e]8;;\e\\\n'

Supporting apps

The list of supporting terminal emulators and terminal-based apps is no longer maintained here. It is kindly maintained by Alhadis in his OSC 8 adoption in terminal emulators page.

A few use cases

We have a couple of use cases in mind...

apt-changelog

apt-changelog could automatically format bug IDs as links to the bugtracker's corresponding page.

git log

git log, or other similar tools could make the commit IDs links to the corresponding page of a web frontend to the repo.

viewers, editors

File viewers and editors could auto-detect URIs in the document, and convert them to hyperlinks even if they are only partially visible on the screen. Example screenshot from an imaginary text editor with two files opened:

╔═ file1 ════╗
║          ╔═ file2 ═══╗
║http://exa║Lorem ipsum║
║le.com    ║ dolor sit ║
║          ║amet, conse║
╚══════════║ctetur adip║
           ╚═══════════╝

Ctrl+clicking anywhere on http://exa or le.com could open the webpage http://example.com.

core utilities

Core utilities, such as ls, find could optionally mark the printed files with their file://... URI, making it just one click to open in a graphical application.

less -R

We're hoping to get less -R recognize and handle this escape sequence just as it does colors, so viewing the output of utilities piped to less -R would keep their hyperlinks working.

The escape sequence

A hyperlink is opened upon encountering an OSC 8 escape sequence with the target URI. The syntax is

OSC 8 ; params ; URI ST

Following this, all subsequent cells that are painted are hyperlinks to this target. A hyperlink is closed with the same escape sequence, omitting the parameters and the URI but keeping the separators:

OSC 8 ; ; ST

OSC (operating system command) is typically ESC ].

params is an optional list of key=value assignments, separated by the : character. Example: id=xyz123:foo=bar:baz=quux. Currently only the id key is defined, see below. These parameters allow future extendability of this feature. In the typical case no parameters are defined, in that case obviously the two semicolons have to be present next to each other.

URI is the target of the hyperlink in URI-encoded form. Web addresses need to begin with http:// or https://. Use ftp:// for FTP, file:// for local files (see below for the hostname), mailto: scheme for e-mail addresses, etc. It's up to the terminal emulator to decide what schemes it supports and which applications it launches for them.

The sequence is terminated with ST (string terminator) which is typically ESC \. (Although ST is the standard sequence according to ECMA-48 §8.3.89, often the BEL (\a) character is used instead. This nonstandard choice originates from XTerm, and was later adopted by probably all terminal emulators to terminate OSC sequences. Nevertheless, we encourage the use of the standard ST.)

(For OSC and ST, their C0 variant was shown above. They have another, C1 form which might be supported in some contexts. In 8-bit Latin-X character sets they are the single bytes 0x9d and 0x9c, respectively. In UTF-8 mode some terminal emulators deliberately do not implement C1 support because these bytes would conflict with the UTF-8 encoding, while some other terminal emulators recognize the UTF-8 representation of U+009d (i.e. 0xc2 0x9d) and U+009c (i.e. 0xc2 0x9c), respectively. Since C1 is not universally supported in today's default UTF-8 encoding, its use is discouraged.)

A note on opening/closing hyperlinks

The feature was modeled after anchors on webpages. There are some differences though, due to the nature of terminal emulation.

An HTML page is supposed contain balanced and unnested pairs of <a ...> and </a> tags. This is important in order to build up a DOM tree. Terminal emulators don't have this concept. They are a state machine, interpreting the data as it arrives in a stream.

As such, in terminal emulators an OSC 8 escape sequence just changes the hyperlink (or lack thereof) to the new value. It is perfectly legal to switch from one hyperlink to another without explicitly closing the first one. It is also perfectly legal to close a hyperlink when it's not actually open (e.g. to make sure to clean up after a potentially unclean exit of an application).

You can practically think of the hyperlink as yet another attribute that character cells have, similarly to the foreground and background color, bold, italic, strikethrough etc. bits. It is absolutely valid to switch from one color to another without resetting to the default in between, or to reset to the default multiple times. The same goes for hyperlinks.

file:// URIs and the hostname

Web browsers, desktop environments etc. tend to ignore the hostname component of a file://hostname/path/to/file.txt URI. In terminal emulators, such ignorance would lead to faulty targets if you ssh to a remote computer. As such, we don't allow this sloppiness. Utilities that print hyperlinks are requested to fill out the hostname, and terminal emulators are requested to match it against the local hostname and refuse to open the file if the hostname doesn't match (or offer other possibilities, e.g. to download with scp as iTerm2 does).

RFC 8089 says the hostname component should contain the fully qualified hostname, whereas Freedesktop's File URI Specification says it should contain the value returned by gethostname() which is often not fully qualified. It's unreasonable for simple utilities to go into the business of hostname resolution. As such, we urge utilities to place the value from gethostname() there (shell scripts might go for $HOSTNAME).

Terminal emulators should match the given value against the local hostname. They might accept multiple values, e.g. both short and fully qualified names, but they are free to go with just the value from gethostname(). They also must accept the string localhost or the empty string as local ones. If a different hostname is present, they must not open the local counterpart with the same filename.

Hover underlining and the id parameter

Many terminal emulators automatically recognize web addresses that appear on their screen and underline them on mouse hover. In order to provide a similar user experience and discoverability of this new feature, we figured out we should do the same here as well.

There's a nontrivial question though: Which cells to underline on hover? As opposed to webpages, we lack the semantics, the information about the cells that belong together and form a single web anchor.

Remember the http://exa and le.com use case example above? To make the hyperlink feature complete, our imaginary text editor should be able to specify that these two pieces of text actually belong to the same anchor, and when mousing over any of these two, both should be underlined.

In order to be able to do this, the lowercase id parameter was introduced which connects the cells together.

Character cells that have the same target URI and the same nonempty id are always underlined together on mouseover.

The same id is only used for connecting character cells whose URIs is also the same. Character cells pointing to different URIs should never be underlined together when hovering over.

For hyperlink cells that do not have an id (or have an empty id, these two are interchangeable), the terminal emulator does some heuristics in figuring out which cells belong together. Here VTE and iTerm2 differ, but from a practical point of view, this difference should not matter. (VTE automatically assigns a new unique id whenever it encounters an OSC 8 with a URI but without id. That is, it automatically connects cells that were printed in a single OSC 8 run, in case there was no explicit id. iTerm2 looks at the onscreen contents and connects those cells that are next to each other, lack the id, but point to the same URI.)

Terminal emulators that implement hyperlinks but don't want to underline on mouseover can simply ignore the id parameter.

So, what should applications do? Here's a rough guideline, obviously applications are allowed to diverge if that's what gives the right result.

Simple utilities that "just" print stuff on their standard output should not assign an id. Things will just work then as expected.

Complex apps that manage the full screen and wish to explicitly linkify URIs, such as viewers or editors, should assign explicit ids that identify that particular link, so that it keeps being underlined together even across a linebreak, across another pane or window of the app's UI, and even across crazily optimized screen updates (e.g. when it repaints only a part of an anchor text). Such an id might perhaps be the file offset, or the (row, column) tuple where the hyperlink starts. Apps that support multiple windows, such as the imaginary text editor with that screenshot above, should add the ID of the window to the link's id too so that it does not conflict with the same target URI appearing in another window.

Complex apps that display data that might itself contain OSC 8 hyperlinks (such as terminal multiplexers, less -R) should do the following: If the encountered OSC 8 hyperlink already has an id, they should prefix it with some static string, or if multiple windows/panes are supported by the app, a prefix that's unique to that window/pane to prevent conflict with other windows/panes. If the encountered OSC 8 hyperlink does not have an id, they should automatically create one so that they can still have multiple windows/panes and can still crazily partially update the screen and keep it as a semantically single hyperlink towards the host emulator (remember the difference in VTE and iTerm2 when no id is set which becomes relevant here, so it should be avoided). This id should be taken from a namespace that cannot conflict with a mangled explicit id. It's probably much easier to implement VTE's approach here: assign a new id (maybe a sequential integer) whenever an OSC 8 with an URI but no id is encountered. This way there's absolutely no need to maintain any internal pool of the active hyperlink ids or anything like that, it's just a trivial mapping each time an OSC 8 is encountered in the data that needs to be displayed.

Fullscreen apps that do not switch to the "alternate screen" of the terminal emulator, that is, leave their contents onscreen when quitting, should probably add some other identifier, such as the process ID or some random number to the id, so that as the user scrolls back in the history with the scrollbar, remains of two previous sessions do not collide.

Detecting availability of the feature

Currently there's no way of detecting whether the terminal emulator supports hyperlinks. We're hoping to address this at some point in the future.

The hyperlink feature should be used for providing convenient quick access to a target URI, but (at least by default) should not be the only means of figuring out the target.

Backward compatibility

Any terminal that correctly implements OSC parsing according to ECMA-48 is guaranteed not to suffer from compatibility issues. That is, even if explicit hyperlinks aren't supported, the target URI is silently ignored and the supposed-to-be-visible text is displayed, without artifacts.

If a terminal emits garbage upon an OSC 8 explicit hyperlink sequence, that terminal is buggy according to ECMA-48. It is, and will always be, outside of the scope of this specification to deal with buggy terminals.

At this moment, terminals known to be buggy (OSC 8 resulting in display corruption) are VTE versions up to 0.46.2 and 0.48.1, Windows Terminal up to 0.9, Emacs's built-in terminal, and screen with 700+ character long URLs.

Length limits

Terminal emulators traditionally use maybe a dozen or so bytes per cell. Adding hyperlinks potentially increases it by magnitudes. As such, it's tricky to implement this feature in terminal emulators (without consuming way too much memory), and they probably want to expose some safety limits.

Both VTE and iTerm2 limit the URI to 2083 bytes. There's no de jure limit, the de facto is 2000-ish. Internet Explorer supports 2083.

VTE currently limits the id to 250 bytes. It's subject to change without notice, and you should most definitely not rely on this particular number. Utilities are kindly requested to stay way below this limit, so that a few layers of intermediate software that need to mangle the id (e.g. add a prefix denoting their window/pane ID) still stay safe. Of course such intermediate layers are also kindly requested to keep their added prefix at a reasonable size. There's no limit for the id's length in iTerm2.

Terminal emulators might also impose a maximum length on the overall length of the OSC 8 escape sequence, including all its parameters.

VTE is planned to intentionally slow down a tiny little bit if too many long links are written to its scrollback buffer. This is so that a malicious app cannot quickly eat up the space where it stores the scrollback contents. This should not have an effect on normal usage. FIXME this is planned but not yet implemented.

Encodings

For portability, the parameters and the URI must not contain any bytes outside of the 32–126 range. If they do, the behavior is undefined. Bytes outside of this range in the URI must be URI-encoded.

Due to the syntax, additional parameter values cannot contain the : and ; characters either. If required at a future extension, some escaping (such as URI-encoding or base64) should be chosen. (Should there ever be an extension to specify hover colors or attributes, I recommend considering going for the ANSI color and attribute notation with the upper dots removed, e.g. bold italic light gray 1;3;38:5:255 would become 1,3,38.5.255.)

Security

This feature doesn't introduce anything that's not already present while browsing the web. Therefore we believe this feature doesn't have security aspects to worry about.

In particular, if a webpage is exploitable by making someone visit a URL, passing along their cookies (e.g. doesn't have proper CSRF protection), it's already exploitable from a malicious website.

Moreover, there's no "Referer" leakage to worry about.

That being said, a few points have been raised that are worth noting here.

Some locally installed applications might register a handle for some custom URI scheme (e.g. foobar://), and the handler application might be vulnerable in case the rest of the URI is maliciously crafted. Terminal emulators might decide to whitelist only some well known schemes and ask for the user's confirmation on less known ones.

Some are worried that this feature is unexpected from users, and that introducing this somewhat automated link between the terminal and the browser works against the concept of "defense in depth". That is, it's possible that a multi-step attack, exploiting a vulnerability of a website, takes place by using social engineering to get someone follow such a link that they somehow receive in the terminal emulator. It's out of the scope of this specification to deal with such scenarios, this specification can only be responsible for direct security vulnerabilities that it might open. However, terminal emulators might consider adding the following lines of defense. They shouldn't open the link on a simple mouse click (that's for copy-pasting or reporting mouse events typically, anyway), only on some more complex user action such as Ctrl+click or via the right-click menu. They should let the user know the URI upfront. They could decide to present a confirmation dialog before opening it. They could even offer to disable this feature (or even have it disabled by default). People working in critical environments (or their sysadmins) could decide to disable this feature entirely.

Links

• GNOME Terminal discussion
• iTerm2 discussion
• Test file

Hey @jamie-pate.

That should be considered a bug on the part of the program (I believe ansible-lint in your case) emitting the sequence, you should report the issue over there.

As Egmont explained, it's the duty of the program emitting the sequence to detect if its output stream is connected to a terminal device before emitting such sequences... The same applies to almost any other terminal control sequence, not just this.

Next time, kindly ask nicely about things you may not be well-informed about. 😃

EDIT: For the record, I saw your previous comment.

Oh, and just for the fun of it (in response to a freshly deleted comment that's archived on web.archive.org)

feels like this whole thing put the horse before the cart

The last time I checked, that's where the horse belongs 😂

https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda#backward-compatibility mentions that any terminal emulator that doesn't parse it correctly should consider this a bug since it doesn't properly follow ECMA-48

I was trying to be constructive, but to clarify, I mean that the terminal emulator is faulty if it parses colors and other ECMA-48 codes, but fails to properly deal with ]8

Trying to help people identify where to report the issues with various pieces of infrastructure that this is exposing.. e.g. concourse/concourse#4318

I mean that the terminal emulator is faulty if it parses colors and other ECMA-48 codes, but fails to properly deal with ]8

Isn't that just what the quoted section is saying?

I mean that the terminal emulator is faulty if it parses colors and other ECMA-48 codes, but fails to properly deal with ]8

Isn't that just what the quoted section is saying?

I was responding to this comment, which seems to be laying the blame on the emitter (Originating devices as per ECMA-48), not the consumer (Receiving devices as per ECMA-48):

Hey @jamie-pate.

That should be considered a bug on the part of the program (I believe ansible-lint in your case) emitting the sequence, you should report the issue over there.

My conclusion is that according to #backward-compatibility the Receiving device is 100% responsible for implementing the rest of ECMA-48 even if they just wanted fancy color support and implemented it by scanning through the wikipedia article on the subject. Therefore, if you have issues, you should report issues with the Receiving device implementer.

@jamie-pate Just to be clear, where exactly did you copy the following from?

]8;id=274247;https://ansible-lint.readthedocs.io/rules/syntax-check/\syntax-check[specific]]8;;\: Invalid options for ansible.builtin.include_role: vars

The program generating the output is ansible-lint which creates output using the rich python library

The issue shows up when running inside concourse ci

Whether or not concourse-ci renders OSC 8 links as links is optional: nice but not required.
However, it should parse OSC escape sequences and ignore ones it doesn't handle. That is a pretty basic requirement for any kind of modern terminal emulator (or wrapper like screen/tmux) that claims to be more-or-less-xterm-compatible (which almost all do). If concourse-ci only claims to implement a minimal ansi/vt-NNN-style terminal, then ansible-lint/rich should not be emitting any OSC sequences.

The program generating the output is ansible-lint which creates output using the rich python library

The issue shows up when running inside concourse ci

I see.

Firstly, I believe @PerBothner has given a good reply (possibly with the exception of the last sentence).

In addition... as far as I know, rich does the necessary detection. So, the issue seems to lie on the end of concourse-ci. If concourse-ci "tells" the programs it executes that their output is a terminal device, then it should gracefully behave as one.

Concourse doesn't advertise any virtual terminal support, but does support 'ANSI' color sequences ^[.... but not ^]8...

Many concourse examples add TERM=xterm-color to the environment, which advertises full support of the spec..

By removing the falsely advertised terminal advertisement from my config prevents the links, but I also lose all color.

If rich sees TERM=xterm-color I think it is reasonable for it to assume it is safe to emit OSC escape sequences, especially the more common ones.

So either fix/enhance concourse to ignore OSC escape sequences (probably not that difficult if it already handles ANSI color sequences). Or change TERM to something closer to what concourse supports, such as TERM=ansi. (I don't know if TERM=ansi will allow colors, but you should be able to find something that works.) And Concourse examples should be fixed to not use TERM=xterm-color as that is too much of a lie.

I don't know if TERM=ansi will allow colors

Unfortunately, this doesn't seem to be possible.

The issue is that 'supports colors' has been the dominating aspect of terminfo for so long that every library that sniffs for terminal capabilities will only check if it 'supports colors' and then give up if it doesn't. Other Control Function escape sequences have not been on the radar for quite a while for this class of non-interactive program. (edit: see this relevant code from the rich library as an example.) (ncurses-alike libraries will need more capabilities)

I agree the best way forward is that concourse's elm-ansi should be updated. This leaves me currently with the task of stripping unsupported sequences using sed and that is fine.

(edit: Actually, concourse+rich still guesses 'standardcolor' without TERM)

Probably worth opening a ticket on concourse ci for osc8 support since it's open source.

Thanks for this! I was able to use this to make hyperlinks in my p10k prompt segments!

  # Shows the PR number as hyperlink
  prompt_pr_number() {
    if [[ ! -d .git ]]; then return; fi

    local pr_number=$(git config --get branch."$(git branch --show-current)".github-pr-owner-number | awk -F "#" '{print $3}')

    if [ -z "$pr_number" ]; then return; fi

    local pr_link=$(echo "\e]8;;https://github.com/payloadcms/payload/pull/$pr_number\e\\#$pr_number\e]8;;\e\\")
    _p9k_prompt_segment "$0$state" 208 016 '' 0 '' "$pr_link"
  }

thanks for maintaining this compilation of useful resources.

Some locally installed applications might register a handle for some custom URI scheme (e.g. foobar://), and the handler application might be vulnerable in case the rest of the URI is maliciously crafted. Terminal emulators might decide to whitelist only some well known schemes and ask for the user's confirmation on less known ones.

I assessed this for iTerm2 and Hyper and just published: https://vin01.github.io/piptagole/escape-sequences/iterm2/hyper/url-handlers/code-execution/2024/05/21/arbitrary-url-schemes-terminal-emulators.html (Abusing url handling in iTerm2 and Hyper for code execution)

If terminal emulators themselves act as applications handling arbitrary URL schemes, attack surface can be quite broad.

If you want to skip the convoluted docs and just want to cut to the chase, here is a

Python example

def terminal_link(url, text):
	return '\033]8;;' + url + '\033\\' + text + '\033]8;;\033\\'

print('-->', terminal_link('https://google.com', 'Click here to open Google'), '<--')
print('-->', terminal_link('file:///etc/passwd', 'Click here to open /etc/passwd'), '<--')

@hybridgorilla897, that's such a naive and mediocre mindset that has lead to a lot of poor and low-quality projects/products all over the place. You can do better.

Sidenote

You seem to have joined GitHub just about an hour before posting this comment, that's crazy though 🤔. Not that it means anything, just interesting. Never had the priviledge of seeing such a fresh user on here.

@AnonymouX47 I use throwaway accounts all the time. My main account is from 2010.

This problem is realistically not something anyone should spend more than 30 seconds on.

This problem is realistically not something anyone should spend more than 30 seconds on.

Well... until someone runs into some issue and blames some innocent TE devs for their own negligence and incompetence or begin to ask unnecessary questions e.g see:

• Hover underlining and the id parameter
• Length limits
• Encodings

JavaScript implementation:

const OSC = "\u001B]";
const SEP = ";";
const BEL = "\u0007";
const link = (text, url) =>
  [OSC, "8", SEP, SEP, url, BEL, text, OSC, "8", SEP, SEP, BEL].join("");

On emitting file: URIs: why should every application be required to query and reproduce the FQDN for local links? What if the application doesn't/can't know the FQDN?

This problem doesn't arise in web browsers: I can write <a href="/foo.html">bar</a> rather than <a href="https://example.com/foo.html">bar</a>, and it works because the webbrowser is aware of the current domain. That could be replicated in a terminal by making ssh emit a control sequence indicating "now connected to machine example.com", with a corresponding operation to pop the current machine when the connection is closed. The terminal emulator can check the connection stack to see if/how to open a file: URI.

I think the document is clear on this: there's no FQDN involved.

The hostname, as a host calls itself, is involved. It's typically not fully qualified (although on some systems it is). It's as easy to get it as a gethostname() or uname() system call, or accessing the HOSTNAME environment variable, or executing the hostname utility. Surely something similarly simple is available on Windows, too.

What do you mean an application doesn't/can't know this, how could that happen??? If an application is written in a language that doesn't give you access to any of these then get in touch with that language's developers. If it's running in a sandbox and access to these is deliberately denied then presumably so is access to the host's files, therefore local links emitted wouldn't make sense either.

FQDN, on the other hand, goes hand in hand with DNS resolution, and is for addressing some other host on the network. Possibly multiple hosts via the same FQDN, due to load balancing. And a host can have a plethora of FQDNs that resolve to that particular host (or multiple hosts including that one). The question "what is the FQDN of this host" doesn't really make sense. And, luckily, it's fully omitted from this OSC 8 game.

---

Rather than the stateless design we went with, the stateful design that you propose would have the following properties:

Would need buy-in from OpenSSH developers. Or rather: would have needed buy-in from its developers when this OSC 8 feature was in design phase only, not knowing if it would become successful. Would have they agreed to go with it? Maybe, maybe not. We can't tell.

As far as I know, OpenSSH has absolutely nothing to do with terminal emulation, it doesn't know about any escape sequence. [It can allocate a tty line, and it can filter out unprintable characters from some messages (which it did not do yet when OSC 8 was designed, this security hole had not been discovered yet back then), but that's pretty much all about it.] So if I'm not mistaken, this would have been the first escape sequence it knows about and emits. Maybe just a few lines of code, but a significant change in its project scope. Then would it go into the business of terminal capabilities identification (terminfo and friends) to know if the terminal is supposed to support the said escape sequences? (Mind you, identifying this feature isn't addressed yet, in the current specs – long story for another day.) What if it gets it wrong one way? You get faulty links, pointing to a file of the same name on a different machine. What if it gets it wrong the other way, or if it leaves out this component and unconditionally emits the escape sequences? Chances of seeing garbage in non-supporting terminals. Now, surely, there's a chance currently that OSC 8 links result in garbage (there's a section dedicated to this in the doc), but with your proposed design this could also happen if somebody doesn't wish to use any OSC 8 at all.

Handle if the connection ends abruptly. I guess emitting the escape sequence could go to the ssh client and then it could protect against that. Handle local job control (^Z, fg, bg).

What to do if for whatever reason the stack gets corrupted? E.g. cat'ing a binary file accidentally prints one escape sequence that pushes to or pops from this stack? You'd get stuck with that broken behavior probably til the end of that terminal session.

What to do on reset? On one hand its job is, well, to reset things. On the other hand, if executed within an ssh session, you don't want to break the rest of OSC 8's within that session.

Let's suppose we would've gotten buy-in from OpenSSH. What about all the other ssh implementations out there? What about other commands and protocols that let you connect to a remote host? rsh, telnet, lxc exec, and a whole bunch of others, including commercial software too? Do you see a reasonable chance of convincing all of them to support OSC 8 hostname pushing/popping? Because wherever it's missing, you get faulty links.

Alternatively, you might say that it should be the remote shell's job to push/pop. But it's again highly problematic. How long until all systems set up the shell to emit this sequence by default? Decades at least. What if the user executes a specific command rather than the shell? It's skipped then, printing faulty links. What if the connection breaks? Popping is skipped, corrupting the rest of the terminal session.

---

The stateful design that you propose would be extremely unreliable in many situations where the current stateless design is robust, reliable.

Accessing the hostname, which you have a problem with in the current design, is not a problem at all.

---

And finally, a friendly reminder, to everyone having similar thoughts as you that the design should have been different:

The protocol was designed 7.5 years ago. It was discussed in public bugtrackers; anyone truly interested in all the innovations and ongoing work in popular terminal emulators did have a chance to notice it and join the conversation. That ship has sailed. Sailed a long-long time ago. Even if your proposal would be better (which I firmly believe it isn't), we couldn't just redesign the protocol in a backward incompatible way and convince everyone who already adopted OSC 8 to rework it.

Additionally, if you don't care about link robustness over ssh (or other ways to save output to file and replay it out of context / on other machines), AND have trouble obtaining the hostname, note the spec permits simply putting localhost there. Suboptimal but works fine for single-machine use cases.

Web browsers are not a fair comparison — they know exactly where a file starts/ends, so "base url", whether default or overridden are precisely scoped. Terminals have much fuzzier, flat, best-effort, idea of scopes (and can always be mucked up by cat untrusted_file.txt); any "action-at-a-distance" escape sequence interactions are fragile.

Thanks for the explanations.

Another Q: how can a Windows machine declare a link to a UNC share, like //server/share/file.txt? Would the URI be file://server/share/file.txt or something else?

I cannot answer this question because I'm really not familiar with Windows systems, sorry. Basically OSC 8 was designed to require a URI. So however that UNC share translates to a URI in other contexts as well (e.g. what do you type into a browser's address bar, a HTML page's A HREF tag?), or if they don't then it's up to Windows-savvy developers to extend the protocol to allow UNC names too (assuming that those two namespaces don't conflict). Or maybe it needs its own scheme, like unc://..., is that a thing? I don't know.

(cben thanks a lot for you amending my answer, you're absolutely right on both points, and I completely forgot about the possibility of using localhost or leaving the host empty :))

rfc8089 covers some of the possibilities in its appendices:

1. file://server/share/file.txt <-- the most common syntax; server is used as authority
2. file:////server/share/file.txt <-- older syntax, empty authority
3. file://///server/share/file.txt <-- variation with an additional / in the path, to match URIs like file:///c:/foo

None of them encode the hostname of the machine that generated the link, and this is one of the reasons why it's uncommon to see hostnames in file: URIs outside of UNC paths. To include the local hostname I guess we'd need something like file://myhost//server/share/file.txt, or perhaps with a triple-slash after myhost. I'll have a look to see if any existing implementations support this syntax.

Hello, I would like to seek some clarification on the responsibility of handling the hostname in file URIs.

---

I am using Alacritty on ArchLinux KDE, with the hyperlink handler set to xdg-open. Currently file URIs that correctly include my local hostname are erroring when clicked. For example:

The file or folder //MY-HOSTNAME/home does not exist.

So I ran Alacritty with increased logging verbosity, and see that it's passing the URI directly to xdg-open:

[9.002343748s] [DEBUG] [alacritty] Launched xdg-open with args ["file://MY-HOSTNAME/home"]

---

So my question is, should it be:

• Alacritty's responsibility to verify the hostname, remove the hostname, then pass the modified URI to xdg-open?
• Or xdg-open's responsibility to be able to handle file URIs that include a hostname?

Thanks in advance.

Great question.

I'd say it's undefined.

OSC 8 (this spec) specifies a protocol between two components: an application sending data towards a terminal emulator in the hope of presenting openable links, and that terminal emulator implementing a certain behavior including opening them.

This question here involves solely the latter side of the story. It's not the role of this spec to tell the terminal emulator how to implement the said behavior. I mean: not all want to get xdg-open involved, not all even have xdg-open in their host operating system. For example, I don't think that GNOME Terminal (one of the two designers and first two implementors of this spec) uses xdg-open indirectly under the hood, although I'm not sure; it uses gtk_show_uri() and I'm not entirely sure whether in turn it maybe uses xdg-open.

I'd say this is a problem to be sorted out between Alacritty and xdg-open, or whichever other components involved, and does not belong to this OSC 8 spec. This spec shouldn't know anything about xdg-open or any other particular helper implementation of opening a URI.

That being said... it's not so clear.

It is mentioned in this spec that the terminal should check the hostname part and reject URIs with remote hostnames. Mind you, it's not a wording that was intentional with this question in mind, and it's up for debate whether it needs to be the terminal emulator itself, or whether it can delegate this task to other apps it launches. E.g. if each and every URI opener app would properly check this, the terminal itself wouldn't have to.

In practice, GNOME Terminal chose to be on the safe side: we do verify the hostname, and once we're there, since we've found an important app suite that at that time had a problem with any hostname being there, we decided to strip it.

To summarize:

From a theoretical prospective, my answer is that this spec has nothing to do with this, it's up for Alacritty and xdg-open to figure it out; it's an interface between those two components which interface, as far as we are concerned here, doesn't even have to exist, so we have absolutely no influence on. From a practical prospective, I'd suggest to ask xdg-open folks first to see if they're open to changing their behavior, and if not then try to convince Alacritty (and other terminals).

Edit: Clarification: This spec tells what the entire Alacitty + xdg-open (or any analogous) combo should implement. xdg-open provides a certain interface, certain behavior. Of course there's a chance you could get to change xdg-open, but if that doesn't happen, it's Alacritty's task to use its building blocks (including xdg-open if it wishes to) and glue them together in a way that overall implements what OSC 8 requires.