gh-news 0.11.0

# gh-news Configuration Example
#
# This is an example configuration file for gh-news. Copy this file to your
# configuration directory to get started:
#
#   cp config.example.toml ~/.config/gh-news/config.toml
#
# Configuration can be overridden by:
#   1. Command-line arguments (highest priority)
#   2. Environment variables
#   3. Config file values (this file)
#   4. Hardcoded defaults (lowest priority)
#
# For authentication, gh-news uses these environment variables in order:
#   - GH_TOKEN (highest priority)
#   - GITHUB_TOKEN
#   - ~/.config/gh/hosts.yml (gh CLI configuration)
#
# Some settings are also persisted in state file (~/.cache/gh-news/state.toml)
# and will override config file values when present:
#   - auto_mark_read (user's toggle)
#   - auto_archive (user's toggle)
#
# ==============================================================================
# NETWORK & API SETTINGS
# ==============================================================================

# How often to refresh notifications automatically (in seconds).
# Default: 120 (5 minutes)
# Environment variable: GH_NEWS_AUTO_REFRESH_INTERVAL
# CLI flag: (not available as flag, set via env or config)
auto_refresh_interval = 120

# HTTP request timeout (in seconds).
# Default: 30
# CLI flag: (not available as flag, set via env or config)
api_timeout = 30

# Maximum number of notifications to fetch from GitHub API.
# Leave commented out to fetch all notifications (default).
# Default: no limit
# CLI flag: --max-notifications <NUMBER> / -n <NUMBER>
# max_notifications = 100

# Number of notifications to fetch per API request (pagination size).
# Default: 50
# CLI flag: (not available as flag, set via env or config)
pagination_size = 50

# ==============================================================================
# DEFAULT FILTERS
# ==============================================================================

# Show read notifications by default (unless filtered out by other options).
# Default: false
# CLI flag: --all / -a
show_read = false

# Show only notifications where you are directly participating (commenting, etc).
# Default: false
# CLI flag: --participating / -p
participating_only = false

# Apply a regular expression filter to notification subjects by default.
# Useful for permanently filtering out certain notification types.
# Examples:
#   default_filter = "(?i)dependabot"  # Hide Dependabot notifications
#   default_filter = "release|tag"     # Show only releases and tags
# Default: (empty, no filter)
# CLI flag: --filter <REGEX> / -f <REGEX>
# default_filter = ""

# ==============================================================================
# DISPLAY SETTINGS
# ==============================================================================

# Default preview mode for notification details (applied on every startup).
# Options: "off", "horizontal", "vertical"
#   - off:        Don't show preview pane (more space for notification list)
#   - horizontal: Preview appears below the notification list
#   - vertical:   Preview appears to the right of the notification list
# Default: "vertical"
# Note: Can be toggled at runtime with Tab, but resets on restart.
# CLI flag: (not available as flag, set via env or config)
default_preview_mode = "vertical"

# Start with repository groups collapsed.
# Default: false
# CLI flag: (not available as flag, set via env or config)
repos_collapsed = false

# Group notifications by organisation above repository grouping.
# Options:
#   - "off":    only group by repository
#   - "auto":   group by organisation only when an organisation has >1 notifications
#   - "always": always group by organisation when applicable
# Default: "auto"
org_grouping = "auto"

# ==============================================================================
# BEHAVIOR
# ==============================================================================

# Automatically mark notifications as read when you navigate away from them.
# Default: true
# CLI flag: --no-auto-mark-read
# Note: Can be toggled at runtime with M key and saved to state file.
auto_mark_read = true

# Automatically archive (mark as done) notifications when navigating away.
# When enabled, auto_mark_read is also forced on.
# Default: false
# CLI flag: --no-auto-archive
# Note: Can be toggled at runtime with M key (cycles off/read/archive)
#       and saved to state file.
auto_archive = false

# ==============================================================================
# EXTERNAL COMMANDS & HOOKS
# ==============================================================================

# Custom command to open URLs in a browser.
# If not set, gh-news will use your system's default browser.
# Examples:
#   browser_command = "firefox"        # Use Firefox
#   browser_command = "open -a Safari" # Use Safari (macOS)
#   browser_command = "xdg-open"       # Use XDG default (Linux)
# Default: (use system default)
# CLI flag: (not available as flag, set via env or config)
# browser_command = ""

# ─── Notification Cache ──────────────────────────────────────────────────
# Cache notifications locally so subsequent launches display data instantly
# instead of waiting for the GitHub API. A background refresh always fetches
# fresh data after the cached view is shown. Use --no-cache to bypass.
#
# Custom path for the notification cache file.
# Default: ~/.cache/gh-news/notifications_cache.json
# cache_file = "/path/to/cache.json"

# ─── External Commands ──────────────────────────────────────────────────

# Command to execute when a new notification arrives.
# Useful for sending notifications to your desktop, playing a sound, etc.
#
# Available environment variables:
#   - GH_NEWS_ID          Repository notification ID
#   - GH_NEWS_TITLE       Notification subject
#   - GH_NEWS_REPO        Repository name (owner/repo)
#   - GH_NEWS_OWNER       Repository owner
#   - GH_NEWS_TYPE        Notification type (PullRequest, Issue, etc)
#   - GH_NEWS_REASON      Why you're notified (mention, review_requested, etc)
#   - GH_NEWS_URL         URL to the notification
#   - GH_NEWS_UNREAD      "true" or "false"
#   - GH_NEWS_UPDATED_AT  Last update timestamp (RFC3339 format)
#
# Examples:
#   # macOS desktop notification
#   on_new_notification_command = "osascript -e 'display notification \"$GH_NEWS_TITLE\" with title \"gh-news: $GH_NEWS_REPO\"'"
#
#   # Linux libnotify
#   on_new_notification_command = "notify-send 'gh-news' '$GH_NEWS_TITLE ($GH_NEWS_REPO)'"
#
#   # Play a sound (macOS)
#   on_new_notification_command = "afplay /System/Library/Sounds/Glass.aiff"
#
# Default: (no hook, notifications are silent)
# CLI flag: (not available as flag, set via env or config)
# on_new_notification_command = ""

# ==============================================================================
# GITHUB ENTERPRISE
# ==============================================================================

# GitHub API host for GitHub Enterprise Server installations.
# Use this to connect to your enterprise GitHub instance.
# Examples:
#   github_host = "github.example.com"     # Enterprise Server
#   github_host = "github.com"             # GitHub Cloud (default)
# Default: "github.com"
# CLI flag: (not available as flag, set via env or config)
github_host = "github.com"

# ==============================================================================
# CUSTOM ACTIONS
# ==============================================================================

# Define custom actions that can be executed on notifications via the action
# menu (press 'x'). Actions run shell commands with placeholder substitution.
#
# Available placeholders:
#   - {id}        Notification ID
#   - {title}     Notification title
#   - {url}       Web URL for the notification
#   - {repo}      Repository name (without owner)
#   - {owner}     Repository owner
#   - {full_name} Full repository name (owner/repo)
#   - {type}      Notification type (Issue, PullRequest, etc.)
#   - {reason}    Notification reason (mention, review_requested, etc.)
#   - {unread}    Read status (true/false)
#
# Options:
#   - name:        Display name in the action menu (required)
#   - command:     Command template with placeholders (required)
#   - interactive: Suspend TUI and run with full terminal access for interactive
#                  tools like vim, fzf, etc. (default: false)
#
# Examples:

# Copy notification URL to clipboard (Linux with xclip)
# [[actions]]
# name = "Copy URL"
# command = "echo {url} | xclip -selection clipboard"

# Copy notification URL to clipboard (macOS)
# [[actions]]
# name = "Copy URL"
# command = "echo {url} | pbcopy"

# Open in VS Code
# [[actions]]
# name = "Open in VS Code"
# command = "code --goto {url}"

# Add to TODO list
# [[actions]]
# name = "Add to TODO"
# command = "echo '* TODO {title}' >> ~/todo.org"

# Open in vim (interactive - suspends TUI)
# [[actions]]
# name = "Open in Vim"
# command = "gh pr view {url} | vim -"
# interactive = true

# ==============================================================================
# STATE FILE
# ==============================================================================

# Path to state file for persisting runtime settings.
# The state file stores auto_mark_read toggle and pinned notifications.
# If not set, defaults to ~/.cache/gh-news/state.toml (XDG-compliant).
# Default: (use XDG cache directory)
# CLI flag: --state-file <PATH>
# state_file = "/path/to/custom/state.toml"