stocksTUI

A fast, minimalist terminal app for checking stock prices, crypto, news, and historical charts — without leaving your shell. Built with Textual, powered by yfinance, and made for people who prefer the command line over CNBC.

✨ Features

• Live-ish Price Data Watch your favorite tickers update in near real-time with configurable refresh intervals.

• Watchlists That Make Sense Organize your assets into lists like "Tech", "Crypto", "Dividend Traps", or "Memes". Manage them entirely from the UI — no need to touch JSON unless you want to.

• Tag-Based Filtering Assign tags (e.g., growth, ev, semiconductor) to your tickers and instantly filter any watchlist to see only what's relevant.

• Charts & Tables, Your Way View historical performance from 1D to Max, from a table or a chart.

• Options Chain Support View detailed options chains with strike prices, bid/ask spreads, Greeks (Delta, Gamma, Theta, Vega), and open interest visualization. Track your positions with quantity and average cost.

• News That Matters See the latest headlines per ticker or a combined feed — no ads, no autoplay videos, just info.

• Economic Data (FRED) Monitor key economic indicators directly with integration for St. Louis Fed (FRED) data. Track GDP, Unemployment, CPI, and more with rolling averages and Z-score trend analysis.

• Deep Market Context View comprehensive asset details including All Time High (ATH), % Off ATH, PE Ratio, Market Cap, and historical performance charts.

• Quick Actions & Open Mode Instantly edit ticker aliases and notes with e. Use "Open Mode" (o) to quickly jump to external resources or switch between news, history, and options.

• Keyboard-Friendly, Mouse-Optional Navigate everything with Vim-style keys or arrow keys. Bonus: lots of helpful keybindings, fully documented.

• Custom Themes & Settings Tweak the look and feel with built-in themes or your own. Set your default tab, hide unused ones, and make it feel like your dashboard.

• Smart Caching The app remembers what it can. Market-aware caching keeps startup fast and avoids pointless API calls on weekends or holidays.

⚠️ Note: All symbols follow Yahoo Finance format — e.g., AAPL for Apple, ^GSPC for S&P 500, and BTC-USD for Bitcoin.

🛠 Requirements

• Python 3.10 or newer

• OS Support:

  • Linux / macOS — Fully supported
  • Windows — Use Windows Terminal with WSL2. It won’t work in the old cmd.exe.

🚀 Installation

The easiest way to install is with pipx:

1. Install pipx (if you don’t already have it):

# Debian/Ubuntu
sudo apt install pipx

# Arch Linux
sudo pacman -S python-pipx

# macOS
brew install pipx

# Or fallback to pip
python3 -m pip install --user pipx
python3 -m pipx ensurepath

2. Install stocksTUI:

pipx install stocksTUI

Done. You can now run stockstui from anywhere.

🧭 Usage

Run the app like so:

stockstui

Need help?

stockstui -h          # Short help
stockstui --man       # Full user manual

💡 Command-Line Examples

Open on Tesla's History tab.

stockstui --history TSLA

Get combined news for NVIDIA and AMD.

stockstui --news "NVDA,AMD"

Open on Apple's Options tab to view the options chain.

stockstui --options AAPL

Create a temporary watchlist for this session only.

stockstui --session-list "EV Stocks=TSLA,RIVN,LCID"

Launch a 5-day chart for Tesla.

stockstui --history TSLA --period 5d --chart

Open directly to a specific FRED economic series (e.g., Unemployment Rate).

stockstui --fred UNRATE

CLI mode: Output "stocks" list, filtered by the "tech" tag.

stockstui -o stocks --tags tech

🔑 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.

1. Create a free account and request an API key at fred.stlouisfed.org.
2. Once you have your key, enter it in the app under Configs > FRED Settings.
3. Click Save to enable FRED data fetching.

⌨️ Keybindings

• Press ? inside the app for a quick keybinding cheat sheet
• Run stockstui --man for the full breakdown

🧑‍💻 For Developers: Install from Source

Want to try the bleeding-edge version or contribute?

git clone https://github.com/andriy-git/stocksTUI.git
cd stocksTUI
./install.sh

This sets up a virtual environment and a global stockstui command so you can test and develop from anywhere.

⚖️ License

Licensed under the GNU GPL v3.0. See LICENSE for the legalese.