clickable-path#

Make the file paths your CLI prints ctrl/cmd-clickable

CLIs print paths, but making them open can be tricky.

Thankfully, OSC 8 hyperlinks exist. They point at an invisible absolute file:// URL.

clickable-path is a zero-dependency package to print paths as OSC 8 hyperlinks if your terminal supports them, falling back to a plain label if not.

Usage#

npm install clickable-path

import { link } from 'clickable-path'

console.log(`Building ${link('/home/me/project/nuxt.config.ts')}`)
// -> label `nuxt.config.ts`, linking file:///home/me/project/nuxt.config.ts

console.log(link('src/index.ts', { line: 12 }))
// -> label `src/index.ts:12`, linking file:///home/me/project/src/index.ts#L12

API#

link(path, options?)#

Wraps path in an OSC 8 hyperlink pointing at it on disk, labelled with the cwd-relative form (plus :<line>:<column> if given) or with whatever options.formatter returns. Relative input is resolved against options.cwd.

createLinker(defaults?)#

Returns a { link } with defaults pre-applied, so you can configure a formatter and cwd once rather than at every call site:

const { link } = createLinker({
  formatter: absolute => absolute.replace(rootDir, '~'),
})

console.log(link('/project/app/tailwind.config.ts'))
// label `~/tailwind.config.ts`, linking file:///project/app/tailwind.config.ts

The formatter receives the resolved absolute path, plus line and column if they were passed, and its return value is used without modification. (The default formatter is path.relative with a :<line>:<column> suffix.) Showing the position is up to the formatter; a label that omits it still links to it, so the file opens at the right line either way. Every LinkOptions key can be defaulted this way and overridden per call.

supportsHyperlinks(stream?)#

Whether stream (default process.stdout) will render hyperlinks.

The environment is read on every call rather than snapshotted at module load, so a .env file or a --no-color flag applied after import is still respected. It costs around a microsecond; if you are linking in a hot loop, call this once and pass the result as enabled.

LinkOptions#

Paths are converted with pathToFileURL, so spaces, #, ? and non-ASCII characters are percent-encoded. Windows-shaped inputs (C:\..., \\server\share\...) are converted on any platform.

Non-TTY and CI#

Overrides, in order of precedence: FORCE_HYPERLINK (set to 0 to disable), --no-hyperlink / --hyperlink flags, then NO_COLOR / NO_HYPERLINK / NO_HYPERLINKS.

NO_COLOR disables hyperlinks here. Colour support and hyperlink support are not the same capability, so there is no general colour-support check, but someone who has asked for no escape sequences at all should get none.

Terminal support#

Terminal.app is explicitly unsupported: it ignores OSC 8, though it degrades gracefully to the plain label. TeamCity is excluded. Anything unrecognised gets no escapes, since a wrong positive prints visible junk.

Passing line (and optionally column) appends :12:3 to the default label and #L12,3 to the URL. Most terminals ignore the fragment and simply open the file, so treat jump-to-line as a hint. You can decide whether to show a position in a custom formatter if you want.

Differences from terminal-link and supports-hyperlinks#

• When hyperlinks are unsupported, only the label is printed. terminal-link falls back to appending the raw URL (nuxt.config.ts file:///home/me/nuxt.config.ts), which is noise in a log file and breaks any width maths. Here the output is exactly what you would have printed anyway.
• tmux is detected. tmux overwrites TERM_PROGRAM with tmux, hiding the outer terminal, so supports-hyperlinks reports no support inside every tmux session. tmux itself has handled OSC 8 since 3.4, so that version and up are supported directly.
• Detection reads the environment per call. supports-hyperlinks snapshots supportsHyperlinks.stdout at module load, so anything that mutates the environment after import is missed, such as loading a .env file, or normalising --no-color into NO_COLOR while parsing argv.
• No colour-support coupling. supports-hyperlinks returns false whenever supports-color does, but this isn't necessarily correct. (We still honour NO_COLOR if set.)
• The OSC 8 id param is exposed, which terminal-link does not surface.
• Labels are derived, not passed in. terminal-link(text, url) makes every call site build both halves; here the path is the argument and the label comes from a formatter you configure once.
• Zero dependencies, versus supports-color + has-flag + ansi-escapes.

Credits#

• supports-hyperlinks and terminal-link by Sindre Sorhus and James Talmage are excellent. Detection coverage in this package is informed by supports-hyperlinks, reimplemented so there are no dependencies and no module-load-time caching. If you want hyperlinks in general rather than paths specifically, terminal-link would be a good choice.
• Egmont Koblinger's hyperlinks in terminal emulators is the de facto OSC 8 spec.

💻 Development#

• Clone this repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License#

Made with ❤️

Published under MIT License.