Repository: eza-community/eza (2025-11-06T14:58:15Z)

Issue:
feat:  make --hyperlink work like --color and --icons with always,auto,never for piping
I'd like to be able to pipe the output of eza with --hyperlink into a pipe and have the links suppressed like the colour and icons.
bug: `--hyperlink` adds links when output is piped, should have always/auto/never
`--hyperlink` should accept values of `always/auto[matic]/never`, just like `--classify`, `--color`, and `--icons`.

Currently, if you run `eza --hyperlink | pbcopy`, you get this:
```
]8;;file:///Users/jsu/test/foo\foo]8;;\

```

---

eza version: 0.22.1 [+git]
Shell: fish 4.0.2
Terminal: Ghostty
OS: macOS Sequoia 15.5


Discussion:
I believe there was a PR in for this at one point. I'll try to either dig it up or tbh our handling of hyperlinks is changing soon(hopefully) but either way I'll keep this in mind :+1: 
This may or may not be intended behavior if `--hyperlink` is currently interpreted as "always" but this was surprising to me:

```shell
$ touch foo bar
$ eza --hyperlink | xargs -n 1
ar
oo

```

I encountered this because I alias `ls` to include the `--hyperlink` option or it probably would have been more obvious.
#693 seems potentially related although I can't reproduce it.
See also https://github.com/eza-community/eza/issues/1156 on why the default may not be `auto` here
Looks like both https://github.com/eza-community/eza/pull/1059 and https://github.com/eza-community/eza/pull/1664 were opened to implement `--hyperlink=auto/always/never`, and https://github.com/eza-community/eza/pull/746 is a superseded PR.





Patch:
diff --git a/README.md b/README.md
index 2184bdf4d..fea6e62bf 100644
--- a/README.md
+++ b/README.md
@@ -110,7 +110,7 @@ eza’s options are almost, but not quite, entirely unlike `ls`’s. Quick overv
 - **--colo[u]r-scale=(field)**: highlight levels of `field` distinctly(all, age, size)
 - **--color-scale-mode=(mode)**: use gradient or fixed colors in --color-scale. valid options are `fixed` or `gradient`
 - **--icons=(when)**: when to display icons (always, auto, never)
-- **--hyperlink**: display entries as hyperlinks
+- **--hyperlink=(when)**: when to display entries as hyperlinks (always, auto, never)
 - **--absolute=(mode)**: display entries with their absolute path (on, follow, off)
 - **-w**, **--width=(columns)**: set screen width in columns
 
diff --git a/completions/bash/eza b/completions/bash/eza
index dbecd8a91..f1033d10e 100644
--- a/completions/bash/eza
+++ b/completions/bash/eza
@@ -18,6 +18,11 @@ _eza() {
             return
             ;;
 
+        --hyperlink)
+            mapfile -t COMPREPLY < <(compgen -W 'always automatic auto never' -- "$cur")
+            return
+            ;;
+
         -L|--level)
             mapfile -t COMPREPLY < <(compgen -W '{0..9}' -- "$cur")
             return
diff --git a/completions/fish/eza.fish b/completions/fish/eza.fish
index e3488239f..98e538b13 100644
--- a/completions/fish/eza.fish
+++ b/completions/fish/eza.fish
@@ -37,7 +37,12 @@ complete -c eza -l icons -d "When to display icons" -x -a "
   never\t'Never display icons'
 "
 complete -c eza -l no-quotes -d "Don't quote file names with spaces"
-complete -c eza -l hyperlink -d "Display entries as hyperlinks"
+complete -c eza -l hyperlink -d "When to display entries as hyperlinks" -x -a "
+  always\t'Always display entries as hyperlinks'
+  auto\t'Display hyperlinks if standard output is a terminal'
+  automatic\t'Display hyperlinks if standard output is a terminal'
+  never\t'Never display entries as hyperlinks'
+"
 complete -c eza -l follow-symlinks -d "Drill down into symbolic links that point to directories"
 complete -c eza -l absolute -d "Display entries with their absolute path" -x -a "
   on\t'Show absolute path for listed entries'
diff --git a/completions/nush/eza.nu b/completions/nush/eza.nu
index 3830fd9f1..6558c9189 100644
--- a/completions/nush/eza.nu
+++ b/completions/nush/eza.nu
@@ -17,7 +17,7 @@ export extern "eza" [
     --colour-scale-mode        # Use gradient or fixed colors in --colour-scale
     --icons                    # When to display icons
     --no-quotes                # Don't quote file names with spaces
-    --hyperlink                # Display entries as hyperlinks
+    --hyperlink                # When to display entries as hyperlinks
     --absolute                 # Display entries with their absolute path
     --follow-symlinks          # Drill down into symbolic links that point to directories
     --group-directories-first  # Sort directories before other files
diff --git a/completions/pwsh/_eza.ps1 b/completions/pwsh/_eza.ps1
index 51f647296..b7d3fd703 100644
--- a/completions/pwsh/_eza.ps1
+++ b/completions/pwsh/_eza.ps1
@@ -77,6 +77,11 @@ Register-ArgumentCompleter -Native -CommandName 'eza' -ScriptBlock {
             ForEach-Object {[System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)}
             break
         }
+        '*;--hyperlink' {
+            $ArrayWhen | 
+            ForEach-Object {[System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)}
+            break
+        }
         '*;--all' {
             [CompletionResult]::new('--show-symlinks'            ,'listfilessyl'        , [CompletionResultType]::ParameterName, 'explicitly show symbolic links (for use with --only-dirs | --only-files)')
             [CompletionResult]::new('--no-symlinks'              ,'listfilessyl'        , [CompletionResultType]::ParameterName, 'do not show symbolic links')
@@ -158,7 +163,7 @@ Register-ArgumentCompleter -Native -CommandName 'eza' -ScriptBlock {
         #   [CompletionResult]::new('--colour-scale-mode'        ,'colorscalemode'      , [CompletionResultType]::ParameterName, 'use gradient or fixed colors in --color-scale (fixed, gradient)')
             [CompletionResult]::new('--icons'                    ,'icons'               , [CompletionResultType]::ParameterName, 'when to display icons (always, auto, never)')
             [CompletionResult]::new('--no-quotes'                ,'noquotes'            , [CompletionResultType]::ParameterName, 'don''t quote file names with spaces')
-            [CompletionResult]::new('--hyperlink'                ,'hyperlink'           , [CompletionResultType]::ParameterName, 'display entries as hyperlinks')
+            [CompletionResult]::new('--hyperlink'                ,'hyperlink'           , [CompletionResultType]::ParameterName, 'when to display entries as hyperlinks (always, auto, never)')
             [CompletionResult]::new('--absolute'                 ,'absolute'            , [CompletionResultType]::ParameterName, 'display entries with their absolute path (on, follow, off)')
             [CompletionResult]::new('--follow-symlinks'          ,'followsymlinks'      , [CompletionResultType]::ParameterName, 'drill down into symbolic links that point to directories')
         #   [CompletionResult]::new('-w'                         ,'widths'              , [CompletionResultType]::ParameterName, 'set screen width in columns')
diff --git a/completions/zsh/_eza b/completions/zsh/_eza
index 9636fe254..c5b95aaa3 100644
--- a/completions/zsh/_eza
+++ b/completions/zsh/_eza
@@ -25,7 +25,7 @@ __eza() {
         --colo{,u}r-scale-mode"[Use gradient or fixed colors in --color-scale]:(mode):(fixed gradient)" \
         --icons="[When to display icons]:(when):(always auto automatic never)" \
         --no-quotes"[Don't quote filenames with spaces]" \
-        --hyperlink"[Display entries as hyperlinks]" \
+        --hyperlink="[When to display entries as hyperlinks]:(when):(always auto automatic never)" \
         --absolute"[Display entries with their absolute path]:(mode):(on follow off)" \
         --follow-symlinks"[Drill down into symbolic links that point to directories]" \
         --group-directories-first"[Sort directories before other files]" \
diff --git a/man/eza.1.md b/man/eza.1.md
index 4daeac48b..dc14382fb 100644
--- a/man/eza.1.md
+++ b/man/eza.1.md
@@ -123,9 +123,14 @@ When used without a value, defaults to ‘`automatic`’.
 `--no-quotes`
 : Don't quote file names with spaces.
 
-`--hyperlink`
+`--hyperlink=WHEN`
 : Display entries as hyperlinks
 
+Valid settings are ‘`always`’, ‘`automatic`’ (‘`auto`’ for short), and ‘`never`’.
+When used without a value, defaults to ‘`automatic`’.
+
+`automatic` or `auto` will display hyperlinks only when the standard output is connected to a real terminal. If `eza` is ran while in a `tty`, or the output of `eza` is either redirected to a file or piped into another program, hyperlinks will not be used. Setting this option to ‘`always`’ causes `eza` to always display hyperlinks, while ‘`never`’ disables the use of hyperlinks.
+
 `-w`, `--width=COLS`
 : Set screen width in columns.
 
diff --git a/src/options/file_name.rs b/src/options/file_name.rs
index 700b90804..f591df6c1 100644
--- a/src/options/file_name.rs
+++ b/src/options/file_name.rs
@@ -95,10 +95,10 @@ impl QuoteStyle {
 
 impl EmbedHyperlinks {
     fn deduce(matches: &ArgMatches) -> Self {
-        if matches.get_flag("hyperlink") {
-            Self::On
-        } else {
-            Self::Off
+        match matches.get_one("hyperlink") {
+            Some(ShowWhen::Never) | None => Self::Never,
+            Some(ShowWhen::Always) => Self::Always,
+            Some(ShowWhen::Auto) => Self::Automatic,
         }
     }
 }
@@ -149,18 +149,34 @@ mod tests {
     }
 
     #[test]
-    fn deduce_embed_hyperlinks_on() {
+    fn deduce_embed_hyperlinks_auto() {
         assert_eq!(
             EmbedHyperlinks::deduce(&mock_cli(vec!["--hyperlink"])),
-            EmbedHyperlinks::On
+            EmbedHyperlinks::Automatic
+        );
+        assert_eq!(
+            EmbedHyperlinks::deduce(&mock_cli(vec!["--hyperlink", "auto"])),
+            EmbedHyperlinks::Automatic
+        );
+    }
+
+    #[test]
+    fn deduce_embed_hyperlinks_always() {
+        assert_eq!(
+            EmbedHyperlinks::deduce(&mock_cli(vec!["--hyperlink", "always"])),
+            EmbedHyperlinks::Always
         );
     }
 
     #[test]
-    fn deduce_embed_hyperlinks_off() {
+    fn deduce_embed_hyperlinks_never() {
+        assert_eq!(
+            EmbedHyperlinks::deduce(&mock_cli(vec!["--hyperlink", "never"])),
+            EmbedHyperlinks::Never
+        );
         assert_eq!(
             EmbedHyperlinks::deduce(&mock_cli(vec![""])),
-            EmbedHyperlinks::Off
+            EmbedHyperlinks::Never
         );
     }
 
@@ -254,7 +270,7 @@ mod tests {
                 classify: Classify::JustFilenames,
                 show_icons: ShowIcons::Never,
                 quote_style: QuoteStyle::QuoteSpaces,
-                embed_hyperlinks: EmbedHyperlinks::Off,
+                embed_hyperlinks: EmbedHyperlinks::Never,
                 absolute: Absolute::Off,
                 is_a_tty: true,
             })
diff --git a/src/options/parser.rs b/src/options/parser.rs
index 526188a9f..231c27968 100644
--- a/src/options/parser.rs
+++ b/src/options/parser.rs
@@ -85,7 +85,10 @@ pub fn get_command() -> clap::Command {
             .num_args(0..=1)
             .value_parser(value_parser!(ShowWhen))
             .default_missing_value("auto"))
-        .arg(arg!(--hyperlink "display entries as hyperlinks"))
+        .arg(arg!(--hyperlink <WHEN> "when to display entries as hyperlinks")
+            .num_args(0..=1)
+            .value_parser(value_parser!(ShowWhen))
+            .default_missing_value("auto"))
         .arg(arg!(--"no-quotes" "don't quote file names with spaces"))
 
         .next_help_heading("FILTERING OPTIONS")
diff --git a/src/output/file_name.rs b/src/output/file_name.rs
index 6e14e2067..bbb8a7c98 100644
--- a/src/output/file_name.rs
+++ b/src/output/file_name.rs
@@ -121,8 +121,14 @@ pub enum ShowIcons {
 /// Whether to embed hyperlinks.
 #[derive(PartialEq, Eq, Debug, Copy, Clone)]
 pub enum EmbedHyperlinks {
-    Off,
-    On,
+    /// Never embed hyperlinks, even when output is going to a terminal.
+    Never,
+
+    /// Embed hyperlinks automatically, based on the output destination.
+    Automatic,
+
+    /// Always embed hyperlinks, even when the output isn't going to a terminal.
+    Always,
 }
 
 /// Whether to show absolute paths
@@ -275,7 +281,7 @@ impl<C: Colours> FileName<'_, '_, C> {
                             classify: Classify::JustFilenames,
                             quote_style: QuoteStyle::QuoteSpaces,
                             show_icons: ShowIcons::Never,
-                            embed_hyperlinks: EmbedHyperlinks::Off,
+                            embed_hyperlinks: EmbedHyperlinks::Never,
                             is_a_tty: self.options.is_a_tty,
                             absolute: Absolute::Off,
                         };
@@ -413,7 +419,12 @@ impl<C: Colours> FileName<'_, '_, C> {
         let mut bits = Vec::new();
 
         let mut display_hyperlink = false;
-        if self.options.embed_hyperlinks == EmbedHyperlinks::On
+        let should_embed_hyperlinks = match self.options.embed_hyperlinks {
+            EmbedHyperlinks::Never => false,
+            EmbedHyperlinks::Automatic => self.options.is_a_tty,
+            EmbedHyperlinks::Always => true,
+        };
+        if should_embed_hyperlinks
             && let Some(abs_path) = self
                 .file
                 .absolute_path()


Test patch:
diff --git a/powertest.yaml b/powertest.yaml
index ce637a30a..b9401c655 100644
--- a/powertest.yaml
+++ b/powertest.yaml
@@ -69,6 +69,12 @@ commands:
   ? - null
     - --hyperlink
   :
+  ? - null
+    - --hyperlink
+  : values:
+      - auto
+      - always
+      - never
   ? - null
     - --absolute
   : values:
diff --git a/tests/ptests/ptest_2439b7d68089135b.stdout b/tests/ptests/ptest_2439b7d68089135b.stdout
index b3996abef..5bd9aa127 100644
--- a/tests/ptests/ptest_2439b7d68089135b.stdout
+++ b/tests/ptests/ptest_2439b7d68089135b.stdout
@@ -26,7 +26,7 @@ DISPLAY OPTIONS:
       --color-scale [<FIELDS>...]  highlight value of FIELDS distinctly [possible values: all, age, size]
       --color-scale-mode <MODE>    mode for --color-scale [default: gradient] [possible values: fixed, gradient]
       --icons [<WHEN>]             when to display icons [possible values: always, auto, never]
-      --hyperlink                  display entries as hyperlinks
+      --hyperlink [<WHEN>]         when to display entries as hyperlinks [possible values: always, auto, never]
       --no-quotes                  don't quote file names with spaces
 
 FILTERING OPTIONS:
diff --git a/tests/ptests/ptest_295b1dd87a9bb792.toml b/tests/ptests/ptest_295b1dd87a9bb792.toml
new file mode 100644
index 000000000..8cdceb2f3
--- /dev/null
+++ b/tests/ptests/ptest_295b1dd87a9bb792.toml
@@ -0,0 +1,2 @@
+bin.name = "eza"
+args = "tests/test_dir --hyperlink never"
\ No newline at end of file
diff --git a/tests/ptests/ptest_a689ab7558716dda.stderr b/tests/ptests/ptest_a689ab7558716dda.stderr
deleted file mode 100644
index e69de29bb..000000000
diff --git a/tests/ptests/ptest_a689ab7558716dda.stdout b/tests/ptests/ptest_a689ab7558716dda.stdout
deleted file mode 100644
index 9272823fb..000000000
--- a/tests/ptests/ptest_a689ab7558716dda.stdout
+++ /dev/null
@@ -1,9 +0,0 @@
-]8;;file://[CWD]/tests/test_dir/git/git]8;;/
-]8;;file://[CWD]/tests/test_dir/grid/grid]8;;/
-]8;;file://[CWD]/tests/test_dir/group/group]8;;/
-]8;;file://[CWD]/tests/test_dir/icons/icons]8;;/
-]8;;file://[CWD]/tests/test_dir/perms/perms]8;;/
-]8;;file://[CWD]/tests/test_dir/size/size]8;;/
-]8;;file://[CWD]/tests/test_dir/specials/specials]8;;/
-]8;;file://[CWD]/tests/test_dir/symlinks/symlinks]8;;/
-]8;;file://[CWD]/tests/test_dir/time/time]8;;/
diff --git a/tests/ptests/ptest_a689ab7558716dda.toml b/tests/ptests/ptest_a689ab7558716dda.toml
deleted file mode 100644
index c870e345c..000000000
--- a/tests/ptests/ptest_a689ab7558716dda.toml
+++ /dev/null
@@ -1,2 +0,0 @@
-bin.name = "eza"
-args = "tests/test_dir --hyperlink "
\ No newline at end of file
diff --git a/tests/ptests/ptest_bba388583551f506.toml b/tests/ptests/ptest_bba388583551f506.toml
new file mode 100644
index 000000000..f277bfa81
--- /dev/null
+++ b/tests/ptests/ptest_bba388583551f506.toml
@@ -0,0 +1,2 @@
+bin.name = "eza"
+args = "tests/test_dir --hyperlink always"
\ No newline at end of file
diff --git a/tests/ptests/ptest_e8471ce10a208fd.toml b/tests/ptests/ptest_e8471ce10a208fd.toml
new file mode 100644
index 000000000..937707e81
--- /dev/null
+++ b/tests/ptests/ptest_e8471ce10a208fd.toml
@@ -0,0 +1,2 @@
+bin.name = "eza"
+args = "tests/test_dir --hyperlink auto"
\ No newline at end of file