Hyperlinks

Make URLs and custom patterns clickable in your terminal

WezTerm supports both implicit and explicit hyperlinks, allowing you to click URLs and create custom clickable patterns that integrate with your workflow.

Implicit Hyperlinks

Implicit hyperlinks are automatically generated by matching patterns in terminal output. WezTerm includes default rules for URLs and allows you to define custom patterns.

Default URL Matching

By default, WezTerm automatically detects and makes URLs clickable:

• http:// and https:// URLs
• file:// URLs
• mailto: links

Simply click any detected URL to open it in your default browser.

Custom Hyperlink Rules

Create clickable patterns for your specific workflow:

Task Numbers

local wezterm = require 'wezterm'
local config = {}

-- Start with the defaults
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- Make task numbers clickable
-- Matches T123 or t123 and links to task tracker
table.insert(config.hyperlink_rules, {
  regex = [=[\b[tt](\d+)\b]=],
  format = 'https://example.com/tasks/?t=$1',
})

return config

GitHub Repository Links

Automatically link GitHub repository references:

GitHub Repos

local wezterm = require 'wezterm'
local config = {}

config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- Make username/project paths clickable
-- Matches patterns like: wezterm/wezterm or "nvim-treesitter/nvim-treesitter"
table.insert(config.hyperlink_rules, {
  regex = [=[["']?([\w\d]{1}[-\w\d]+)(/){1}([-\w\d\.]+)["']?]=],
  format = 'https://www.github.com/$1/$3',
})

return config

JIRA Issues

JIRA Links

table.insert(config.hyperlink_rules, {
  regex = [=[\b([A-Z]+-\d+)\b]=],
  format = 'https://jira.company.com/browse/$1',
})

Pull Request Numbers

PR Numbers

table.insert(config.hyperlink_rules, {
  regex = [=[\bPR\s*#?(\d+)\b]=],
  format = 'https://github.com/yourorg/yourrepo/pull/$1',
})

Pattern Matching

Hyperlink rules use regular expressions with capture groups:

• regex - The pattern to match
• format - The URL template where $1, $2, etc. are replaced with captured groups

The first matched regex group is captured in $1, the second in $2, and so on.

Example: Multiple Capture Groups

Docker Image Tags

table.insert(config.hyperlink_rules, {
  regex = [=[\b([\w-]+)/([\w-]+):(\w+)\b]=],
  format = 'https://hub.docker.com/r/$1/$2/tags?name=$3',
})

This matches patterns like library/nginx:latest and creates a link to Docker Hub.

Explicit Hyperlinks

WezTerm supports the Hyperlinks in Terminal Emulators specification, which allows programs to emit hyperlinks without showing the URL.

Using Explicit Hyperlinks

From the command line:

Output Hyperlink

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

This displays “This is a link” as clickable text that opens http://example.com.

Format Specification

The escape sequence format is:

\e]8;;{URL}\e\\{display text}\e]8;;\e\\

• First part: \e]8;;{URL}\e\\ - Starts the hyperlink
• Middle: {display text} - The visible text
• Last part: \e]8;;\e\\ - Ends the hyperlink

Script Example

Bash Function

#!/bin/bash

# Function to create a hyperlink
hyperlink() {
  local url="$1"
  local text="$2"
  printf '\e]8;;%s\e\\%s\e]8;;\e\\' "$url" "$text"
}

# Usage
hyperlink "https://wezterm.org" "Visit WezTerm"
echo

Advanced Configuration

Combining Rules

Development Workflow

local wezterm = require 'wezterm'
local config = {}

-- Start with defaults
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- GitHub issues
table.insert(config.hyperlink_rules, {
  regex = [=[\b[Ii]ssue\s*#?(\d+)\b]=],
  format = 'https://github.com/myorg/myrepo/issues/$1',
})

-- JIRA tickets
table.insert(config.hyperlink_rules, {
  regex = [=[\b([A-Z]+-\d+)\b]=],
  format = 'https://jira.example.com/browse/$1',
})

-- File paths (local file:// URLs)
table.insert(config.hyperlink_rules, {
  regex = [=[\b(/[\w\-./]+)\b]=],
  format = 'file://$1',
})

return config

Hyperlink Actions

Opening Hyperlinks

By default, clicking a hyperlink opens it in your system’s default browser. You can customize this behavior:

Custom Link Handler

config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- The hyperlink will be opened with the default browser
-- You can override this in your shell config or window manager

Keyboard Navigation

Use Quick Select mode (Ctrl+Shift+Space) to quickly select and open visible hyperlinks without using the mouse.

Best Practices

1. Start with defaults

   Always begin with wezterm.default_hyperlink_rules() to preserve standard URL matching.

2. Test your patterns

   Use a regex testing tool to verify your patterns match correctly before adding them.

3. Order matters

   Rules are evaluated in order. Place more specific rules before general ones.

4. Avoid conflicts

   Ensure your custom patterns don’t conflict with default URL patterns.

Troubleshooting

Links Not Clickable

1. Check that your pattern is correctly escaped (Lua string escaping)
2. Verify the regex matches your expected text
3. Ensure the rule is added to config.hyperlink_rules

Wrong URL Generated

1. Verify capture groups are in the correct order
2. Check that $1, $2 etc. reference the right groups
3. Test the format string with sample matches

Performance Issues

• Complex regex patterns can slow down rendering
• Limit the number of rules for better performance
• Use specific patterns rather than overly broad matches