> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```lua Task Numbers theme={null}
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:

```lua GitHub Repos theme={null}
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

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

### Pull Request Numbers

```lua PR Numbers theme={null}
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

<Note>
  The first matched regex group is captured in `$1`, the second in `$2`, and so on.
</Note>

### Example: Multiple Capture Groups

```lua Docker Image Tags theme={null}
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](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) specification, which allows programs to emit hyperlinks without showing the URL.

### Using Explicit Hyperlinks

From the command line:

```bash Output Hyperlink theme={null}
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 Bash Function theme={null}
#!/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

<CodeGroup>
  ```lua Development Workflow theme={null}
  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
  ```

  ```lua Marketing Team theme={null}
  local wezterm = require 'wezterm'
  local config = {}

  config.hyperlink_rules = wezterm.default_hyperlink_rules()

  -- Google Analytics campaign IDs
  table.insert(config.hyperlink_rules, {
    regex = [=[\bGA-([A-Z0-9-]+)\b]=],
    format = 'https://analytics.google.com/analytics/web/#/report/campaigns/$1',
  })

  -- Bitly short links
  table.insert(config.hyperlink_rules, {
    regex = [=[\bbit\.ly/([\w-]+)\b]=],
    format = 'https://bit.ly/$1',
  })

  return config
  ```
</CodeGroup>

## Hyperlink Actions

### Opening Hyperlinks

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

```lua Custom Link Handler theme={null}
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](/features/quick-select) mode (`Ctrl+Shift+Space`) to quickly select and open visible hyperlinks without using the mouse.

## Best Practices

<Steps>
  <Step title="Start with defaults">
    Always begin with `wezterm.default_hyperlink_rules()` to preserve standard URL matching.
  </Step>

  <Step title="Test your patterns">
    Use a regex testing tool to verify your patterns match correctly before adding them.
  </Step>

  <Step title="Order matters">
    Rules are evaluated in order. Place more specific rules before general ones.
  </Step>

  <Step title="Avoid conflicts">
    Ensure your custom patterns don't conflict with default URL patterns.
  </Step>
</Steps>

## 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