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

[!NOTE]
Requires Node 22.1 or newer, which is where pathToFileURL gained the windows option used to convert Windows-shaped paths on any platform.

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.

[!TIP]
Pad and align inside the formatter, not on the result. The returned string contains invisible escapes, so link(path).padEnd(20) pads to the wrong width, while formatter: absolute => basename(absolute).padEnd(20) lines up as expected.

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

Option	Default
formatter	cwd-relative path plus :<line>:<column>	builds the label, given the absolute path, line and column
cwd	process.cwd(), read at call time	base for relative paths
stream	process.stdout	stream whose TTY state gates output
line / column		shown as :<line>:<column> and linked as #L<line>,<column>
id		OSC 8 id param, so a label wrapped across lines hovers as one link
enabled	detection result	force on/off

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

[!NOTE]
No escapes are emitted when the target stream isn’t a TTY, or when CI is set, as they would otherwise end up in log files. Netlify is the exception, since it renders build logs as HTML and never allocates a TTY.

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

[!WARNING]
FORCE_HYPERLINK=1 bypasses every check, including the CI and non-TTY ones. Escape sequences will end up in whatever you are redirecting to.

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	Detection
Windows Terminal >= 1.4	WT_SESSION (any other terminal on win32 is treated as unsupported)
VS Code >= 1.72	TERM_PROGRAM=vscode + version
Cursor	TERM_PROGRAM=vscode + CURSOR_TRACE_ID (own 0.x version line)
iTerm2 >= 3.1	TERM_PROGRAM=iTerm.app + version
WezTerm >= 20200620	TERM_PROGRAM=WezTerm, including Nix’s 0-unstable-YYYY-MM-DD scheme
ghostty	TERM_PROGRAM=ghostty or TERM=xterm-ghostty
kitty	TERM=xterm-kitty
Alacritty >= 0.11	TERM=alacritty
zed, rio, Tabby, Warp, Orca	TERM_PROGRAM
GNOME Terminal / VTE >= 0.50.1	VTE_VERSION (0.50.0 is excluded: it segfaults on hyperlinks)
tmux >= 3.4	TERM_PROGRAM=tmux + version

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.

[!IMPORTANT]
The comma in #L12,3 is deliberate. VS Code parses the fragment with /^L?(\d+)(?:,(\d+))?/, so #L12:3 matches the line and silently drops the column.

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.