NAME
    stockstui - A terminal user interface for monitoring stock data.

SYNOPSIS
    stockstui [OPTIONS]
    stockstui [VIEW_OPTION] [TICKER(S)]
    stockstui -o, --output [LISTS] [--session-list ...]

DESCRIPTION
    stocksTUI is a modern, terminal-based application for watching stock prices,
    viewing historical data, and reading the latest financial news. It uses a
    configurable, tabbed interface to organize assets into watchlists and
    provides a suite of tools for analysis and debugging.

    The application can be run as a full Terminal User Interface (TUI) or in a
    direct output mode for scripting and quick lookups from the command line.

OPTIONS
    -h, --help
        Show a concise help message listing all command-line options and exit.

    --man
        Display this full user manual and exit.

    -v, -V, --version
        Show the application's version number and exit.

    TUI VIEW OPTIONS (Mutually Exclusive)

    --tab LIST_NAME
        Start the application on a specific watchlist tab. LIST_NAME should
        correspond to a list defined in your lists.json config file (e.g.,
        "stocks", "crypto").

    -H, --history [TICKER]
        Start on the History tab. If TICKER is provided, historical data for
        that symbol will be loaded. If omitted, the view will be empty.

    -N, --news [TICKER,TICKER2,...]
        Start on the News tab. If one or more comma-separated TICKER(S) are
        provided, a combined news feed for those symbols will be loaded.
        If omitted, the view will be empty.

    -O, --options [TICKER]
        Start on the Options tab. If TICKER is provided, options data for
        that symbol will be loaded. If omitted, the view will be empty.

    --fred [SERIES_ID]
        Start on the Economic Data (FRED) tab. If SERIES_ID is provided,
        data for that FRED series will be loaded. If omitted, the view
        will show configured series.

    --debug
        Start on the Debug tab, which provides tools for testing API latency
        and cache performance.

    --configs
        Start on the Configs tab, where you can manage watchlists, themes,
        and other application settings.

    OUTPUT & SESSION OPTIONS

    -o, --output [LISTS]
        Output data directly to the terminal without launching the TUI.
        If no LISTS are provided, all tickers from all configured lists
        are displayed. LISTS can be a single watchlist name or a comma-
        separated list of names (e.g., stocks,crypto,fred).
        The 'fred' option will output economic data from the Federal Reserve
        Economic Data (FRED) API.

    --session-list NAME=TICKER1,TICKER2 ...
        Create one or more temporary watchlists for the current session only.
        Works in both TUI and --output modes. This option can be specified
        multiple times.
        Example: stockstui -o --session-list mylist=AAPL,MSFT

    --tags TAG1,TAG2,...
        Filter watchlists or CLI output to only show tickers possessing
        one or more of the specified tags.
        Example: stockstui -o stocks --tags tech,ai

    --period {1d,5d,1mo,6mo,ytd,1y,5y,max}
        When used with --history, specifies the initial time period for the
        data chart or table.

    -c, --chart
        When used with --history, shows the chart view by default instead of
        the data table.

KEYBINDINGS

    Global Commands
      ?             Toggle the built-in, context-aware help screen.
      q / Z         Quit the application.
      r             Refresh data for the currently visible tab.
      R (Shift+R)   Force a refresh for all symbols across all watchlists.
      f             Toggle the tag filter view on a watchlist tab.
      1-9, 0        Switch directly to the corresponding tab.

    Navigation
      k / Up        Move cursor up or scroll the view up.
      j / Down      Move cursor down or scroll the view down.
      h / Left      Move cursor left.
      l / Right     Move cursor right.
      Tab           Focus the next widget.
      Shift+Tab     Focus the previous widget.
      Esc           Dismiss menus/dialogs, or navigate back in the Configs tab.
      Backspace     Navigate back in the Configs tab. Does not interfere with text input.
      [ / ]         Cycle between expiration dates (Options View).
      p             Manage position for selected option contract.
      c             Toggle between chart and table view (Options/History).

    Table Interaction
      i             Focus the primary input or table in the current view.
      e             Edit the selected ticker alias/note (Price View) or FRED series.
      o             Open the selected ticker/series in the web browser.
      n / h / O     Quick-switch to News, History, or Options for selected ticker.
      /             Search the currently visible table (Price, Config, Debug).
      Ctrl+C        Copy the currently selected text to the system clipboard.

      Sort Mode (press 's' to enter sort mode when a table is focused):
        d           Sort by Description (Price View) / Date (History View).
        c           Sort by Change (Price View) / Close (History View).
        p, e, t     Sort by Price, % Change, or Ticker (Price View only).
        o, H, L, v  Sort by Open, High, Low, or Volume (History View only).
        u           Restore original view (clears sorting and search filters).

    News View
      Tab           Cycle focus to the next news article link.
      Shift+Tab     Cycle focus to the previous link.
      Enter         Open the currently highlighted link in your default web browser.

CONFIGURATION
    Configuration files are located in the standard user config directory
    (e.g., `~/.config/stockstui/` on Linux).

    - `lists.json`: Defines your watchlists.
    - `portfolios.json`: Defines your portfolios and associated tickers.
    - `settings.json`: Controls application behavior like theme and auto-refresh.
    - `themes.json`: Contains color palettes for different themes.

    Cache and log files are located in the standard user cache directory
    (e.g., `~/.cache/stockstui/` on Linux).

    - `app_cache.db`: A SQLite database used to cache price and ticker metadata.
    - `stockstui.log`: A debug log file.

    These files can be safely deleted to reset caches or configuration.

FRED API KEY
    To use the Economic Data (FRED) features, you must provide a free API key 
    from the Federal Reserve Bank of St. Louis. 

    You can request a free API key at:
    https://fred.stlouisfed.org/docs/api/fred/v2/index.html

    Once obtained, enter the key in the application under Configs > FRED Settings.

PRICE COLUMNS
    When viewing price data for stocks or crypto, the following columns can be 
    displayed (visibility is configurable in Configs > Watchlists):

    - Description: User-defined alias or the company's long name
    - Price: The last known market price
    - Change: Dollar amount change from the previous day's close
    - % Change: Percentage change from the previous day's close
    - Day's Range: The low and high price for the current trading day
    - 52-Wk Range: The low and high price over the last 52 weeks
    - Ticker: The symbol used to identify the asset (e.g., AAPL)
    - Volume: The number of shares or units traded during the current day
    - Open: The price at which the asset began trading today
    - Prev Close: The closing price from the preceding trading day
    - PE Ratio: Price-to-Earnings ratio (trailing 12 months)
    - Market Cap: Total market capitalization of the asset
    - Div Yield: Dividend yield as a percentage
    - EPS: Earnings Per Share (trailing 12 months)
    - Beta: Measure of the asset's volatility compared to the market
    - All Time High: The highest price ever recorded for the asset
    - % Off ATH: Percentage difference between current price and All Time High

OPTIONS COLUMNS
    When viewing options chain data, the following columns are displayed in the
    Calls and Puts tables:

    - Strike: The strike price of the option contract
    - Last: The last traded price of the option
    - Bid: The current bid price (price buyers are willing to pay)
    - Ask: The current ask price (price sellers are willing to accept)
    - Chg %: Percentage change from the previous day's closing price
    - Vol: Trading volume for the day (number of contracts traded)
    - OI: Open Interest (number of outstanding contracts)
    - IV: Implied Volatility (market's expectation of future volatility)
    - Δ (Delta): Sensitivity of option price to changes in underlying stock price
    - Γ (Gamma): Rate of change in Delta for a $1 move in underlying stock
    - Θ (Theta): Time decay of the option (value lost per day)
    - ν (Vega): Sensitivity to changes in implied volatility
    - Pos: Position held in this specific contract (if tracked)
    - P/L: Profit/Loss for the position in this specific contract

FRED COLUMNS
    When viewing FRED (Federal Reserve Economic Data) information, the following
    columns are displayed in the table:

    - Series: The name or ID of the economic series (e.g., GDP, UNRATE)
    - Current: The most recent value for the series
    - YoY %: Year-over-year percentage change showing how the value has changed
             compared to the same period last year
    - Roll-12: 12-month rolling average for trend analysis
    - Roll-24: 24-month rolling average for trend analysis
    - Z-10Y: Z-score relative to the 10-year average, indicating how current
             values compare to long-term trends (values >2 or <-2 are significant)
    - 10Y Min: 10-year historical minimum value
    - 10Y Max: 10-year historical maximum value
    - % Range: Percentage position within the 10-year range
    - Obs Date: Observation date of the most recent data point
    - Freq: Frequency of the data (M for Monthly, Q for Quarterly)
    - Units: The unit of measurement for the series (e.g., Thousands of Persons,
             Index, Percentage)

NOTES
    All ticker symbols must be in the format used by Yahoo Finance
    (e.g., 'AAPL', '^GSPC' for S&P 500, 'BTC-USD' for Bitcoin).
