feat: add clickable hyperlinks for URLs in terminal output

Use OSC 8 escape sequences to make tweet and list URLs clickable
in supported terminals (iTerm2, Ghostty, Kitty, WezTerm, VS Code, etc.).

- Add hyperlink() helper function in output.ts
- Apply hyperlinks in printTweets() for tweet URLs
- Apply hyperlinks in printLists() for list URLs
- Add hyperlinks flag to OutputConfig (auto-disabled for non-TTY)
- Automatically falls back to plain text in --plain mode or when piped

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

src/cli/shared.ts

@@ -7,6 +7,7 @@ import kleur from 'kleur';
 import { type CookieSource, resolveCredentials } from '../lib/cookies.js';
 import { extractTweetId } from '../lib/extract-tweet-id.js';
 import {
+  hyperlink,
   labelPrefix,
   type OutputConfig,
   resolveOutputConfigFromArgv,
@@ -323,7 +324,8 @@ export function createCliContext(normalizedArgs: string[], env: NodeJS.ProcessEn
       if (tweet.createdAt) {
         console.log(`${l('date')}${tweet.createdAt}`);
       }
-      console.log(`${l('url')}https://x.com/${tweet.author.username}/status/${tweet.id}`);
+      const tweetUrl = `https://x.com/${tweet.author.username}/status/${tweet.id}`;
+      console.log(`${l('url')}${hyperlink(tweetUrl, tweetUrl, output)}`);
       if (opts.showSeparator ?? true) {
         console.log('─'.repeat(50));
       }

src/commands/lists.ts

@@ -4,6 +4,7 @@
 import type { Command } from 'commander';
 import type { CliContext } from '../cli/shared.js';
 import { extractListId } from '../lib/extract-list-id.js';
+import { hyperlink } from '../lib/output.js';
 import type { TwitterList } from '../lib/twitter-client.js';
 import { TwitterClient } from '../lib/twitter-client.js';
 
@@ -23,7 +24,8 @@ function printLists(lists: TwitterList[], ctx: CliContext): void {
     if (list.owner) {
       console.log(`  ${ctx.colors.muted(`Owner: @${list.owner.username}`)}`);
     }
-    console.log(`  ${ctx.colors.accent(`https://x.com/i/lists/${list.id}`)}`);
+    const listUrl = `https://x.com/i/lists/${list.id}`;
+    console.log(`  ${ctx.colors.accent(hyperlink(listUrl, listUrl, ctx.getOutput()))}`);
     console.log('──────────────────────────────────────────────────');
   }
 }

src/lib/output.ts

@@ -2,6 +2,7 @@ export type OutputConfig = {
   plain: boolean;
   emoji: boolean;
   color: boolean;
+  hyperlinks: boolean;
 };
 
 export type StatusKind = 'ok' | 'warn' | 'err' | 'info' | 'hint';
@@ -33,8 +34,9 @@ export function resolveOutputConfigFromArgv(argv: string[], env: NodeJS.ProcessE
   const plain = argv.includes('--plain');
   const emoji = !plain && !argv.includes('--no-emoji');
   const color = !plain && !argv.includes('--no-color') && defaultColor;
+  const hyperlinks = !plain && isTty;
 
-  return { plain, emoji, color };
+  return { plain, emoji, color, hyperlinks };
 }
 
 export function resolveOutputConfigFromCommander(
@@ -48,8 +50,9 @@ export function resolveOutputConfigFromCommander(
   const plain = Boolean(opts.plain);
   const emoji = !plain && (opts.emoji ?? true);
   const color = !plain && (opts.color ?? true) && defaultColor;
+  const hyperlinks = !plain && isTty;
 
-  return { plain, emoji, color };
+  return { plain, emoji, color, hyperlinks };
 }
 
 export function statusPrefix(kind: StatusKind, cfg: OutputConfig): string {
@@ -93,6 +96,21 @@ export function formatTweetUrl(tweetId: string): string {
   return `https://x.com/i/status/${tweetId}`;
 }
 
+/**
+ * Wraps a URL in OSC 8 escape sequences to make it clickable in supported terminals.
+ * Falls back to plain text when not in a TTY or when hyperlinks are disabled.
+ */
+export function hyperlink(url: string, text?: string, cfg?: OutputConfig): string {
+  const displayText = text ?? url;
+  // Only use hyperlinks when explicitly enabled (requires TTY and not plain mode)
+  if (!cfg?.hyperlinks) {
+    return displayText;
+  }
+  // OSC 8 hyperlink: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+  return `\x1b]8;;${url}\x07${displayText}\x1b]8;;\x07`;
+}
+
 export function formatTweetUrlLine(tweetId: string, cfg: OutputConfig): string {
-  return `${labelPrefix('url', cfg)}${formatTweetUrl(tweetId)}`;
+  const url = formatTweetUrl(tweetId);
+  return `${labelPrefix('url', cfg)}${hyperlink(url, url, cfg)}`;
 }

tests/output.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   formatStatsLine,
   formatTweetUrlLine,
+  hyperlink,
   labelPrefix,
   resolveOutputConfigFromArgv,
   resolveOutputConfigFromCommander,
@@ -9,14 +10,19 @@ import {
 } from '../src/lib/output.js';
 
 describe('output', () => {
-  it('defaults to emoji + color on TTY', () => {
+  it('defaults to emoji + color + hyperlinks on TTY', () => {
     const cfg = resolveOutputConfigFromArgv([], {}, true);
-    expect(cfg).toEqual({ plain: false, emoji: true, color: true });
+    expect(cfg).toEqual({ plain: false, emoji: true, color: true, hyperlinks: true });
   });
 
-  it('plain disables emoji + color', () => {
+  it('disables hyperlinks on non-TTY', () => {
+    const cfg = resolveOutputConfigFromArgv([], {}, false);
+    expect(cfg.hyperlinks).toBe(false);
+  });
+
+  it('plain disables emoji + color + hyperlinks', () => {
     const cfg = resolveOutputConfigFromArgv(['--plain'], {}, true);
-    expect(cfg).toEqual({ plain: true, emoji: false, color: false });
+    expect(cfg).toEqual({ plain: true, emoji: false, color: false, hyperlinks: false });
     expect(statusPrefix('ok', cfg)).toBe('[ok] ');
     expect(labelPrefix('url', cfg)).toBe('url: ');
   });
@@ -33,7 +39,7 @@ describe('output', () => {
 
   it('--no-color disables colors', () => {
     const cfg = resolveOutputConfigFromArgv(['--no-color'], {}, true);
-    expect(cfg).toEqual({ plain: false, emoji: true, color: false });
+    expect(cfg).toEqual({ plain: false, emoji: true, color: false, hyperlinks: true });
   });
 
   it('--no-emoji switches to text prefixes', () => {
@@ -44,32 +50,65 @@ describe('output', () => {
 
   it('commander opts override defaults', () => {
     const cfg = resolveOutputConfigFromCommander({ emoji: false, color: false }, {}, true);
-    expect(cfg).toEqual({ plain: false, emoji: false, color: false });
+    expect(cfg).toEqual({ plain: false, emoji: false, color: false, hyperlinks: true });
     expect(statusPrefix('info', cfg)).toBe('Info: ');
     expect(labelPrefix('date', cfg)).toBe('Date: ');
   });
 
   it('commander plain wins over emoji/color', () => {
     const cfg = resolveOutputConfigFromCommander({ plain: true, emoji: true, color: true }, {}, true);
-    expect(cfg).toEqual({ plain: true, emoji: false, color: false });
+    expect(cfg).toEqual({ plain: true, emoji: false, color: false, hyperlinks: false });
+  });
+
+  it('commander disables hyperlinks on non-TTY', () => {
+    const cfg = resolveOutputConfigFromCommander({}, {}, false);
+    expect(cfg.hyperlinks).toBe(false);
   });
 
   it('formats stats line for all modes', () => {
     const stats = { likeCount: null, retweetCount: undefined, replyCount: 2 };
 
-    expect(formatStatsLine(stats, { plain: true, emoji: false, color: false })).toBe(
+    expect(formatStatsLine(stats, { plain: true, emoji: false, color: false, hyperlinks: false })).toBe(
       'likes: 0  retweets: 0  replies: 2',
     );
-    expect(formatStatsLine(stats, { plain: false, emoji: false, color: false })).toBe('Likes 0  Retweets 0  Replies 2');
+    expect(formatStatsLine(stats, { plain: false, emoji: false, color: false, hyperlinks: false })).toBe(
-    expect(formatStatsLine(stats, { plain: false, emoji: true, color: false })).toBe('❤️ 0  🔁 0  💬 2');
+      'Likes 0  Retweets 0  Replies 2',
+    );
+    expect(formatStatsLine(stats, { plain: false, emoji: true, color: false, hyperlinks: false })).toBe(
+      '❤️ 0  🔁 0  💬 2',
+    );
   });
 
   it('always includes tweet URL in all modes', () => {
     const id = '1234567890';
     const url = `https://x.com/i/status/${id}`;
 
-    expect(formatTweetUrlLine(id, { plain: true, emoji: false, color: false })).toContain(url);
+    expect(formatTweetUrlLine(id, { plain: true, emoji: false, color: false, hyperlinks: false })).toContain(url);
-    expect(formatTweetUrlLine(id, { plain: false, emoji: false, color: false })).toContain(url);
+    expect(formatTweetUrlLine(id, { plain: false, emoji: false, color: false, hyperlinks: false })).toContain(url);
-    expect(formatTweetUrlLine(id, { plain: false, emoji: true, color: false })).toContain(url);
+    expect(formatTweetUrlLine(id, { plain: false, emoji: true, color: false, hyperlinks: true })).toContain(url);
+  });
+
+  it('hyperlink returns plain text when hyperlinks disabled', () => {
+    const cfg = { plain: true, emoji: false, color: false, hyperlinks: false };
+    expect(hyperlink('https://x.com/test', undefined, cfg)).toBe('https://x.com/test');
+  });
+
+  it('hyperlink returns plain text on non-TTY (hyperlinks: false)', () => {
+    const cfg = { plain: false, emoji: true, color: false, hyperlinks: false };
+    expect(hyperlink('https://x.com/test', undefined, cfg)).toBe('https://x.com/test');
+  });
+
+  it('hyperlink wraps URL with OSC 8 escapes when hyperlinks enabled', () => {
+    const cfg = { plain: false, emoji: true, color: true, hyperlinks: true };
+    const result = hyperlink('https://x.com/test', undefined, cfg);
+    expect(result).toContain('\x1b]8;;');
+    expect(result).toContain('\x07');
+  });
+
+  it('hyperlink uses custom display text', () => {
+    const cfg = { plain: false, emoji: true, color: true, hyperlinks: true };
+    const result = hyperlink('https://x.com/test', 'Click here', cfg);
+    expect(result).toContain('Click here');
+    expect(result).toContain('\x1b]8;;https://x.com/test\x07');
   });
 });