stocksTUI 0.1.0b12
A stylish and feature-rich Terminal User Interface for monitoring stock prices, news, and historical data.
Requires Python: >=3.10
Keywords: tui, stocks, finance, terminal, textual, yfinance

# stocksTUI

A fast, minimalist terminal app for checking stock prices, crypto, news, and historical charts — without leaving your shell. Built with [Textual](https://github.com/textualize/textual), powered by [yfinance](https://github.com/ranaroussi/yfinance), and made for people who prefer the command line over CNBC.

![stocksTUI Screenshot - Main Interface](https://raw.githubusercontent.com/andriy-git/stocksTUI/main/assets/com.png)
![stocksTUI Screenshot - CLI Mode](https://raw.githubusercontent.com/andriy-git/stocksTUI/main/assets/cli.png)
![stocksTUI Screenshot - FRED Data](https://raw.githubusercontent.com/andriy-git/stocksTUI/main/assets/fred.png)

---

## ✨ 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](https://finance.yahoo.com/) 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`](https://pypa.github.io/pipx/):

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

```bash
# 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:

```bash
pipx install stocksTUI
```

Done. You can now run `stockstui` from anywhere.

---

## 🧭 Usage

Run the app like so:

```bash
stockstui
```

Need help?

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

---

### 💡 Command-Line Examples

Open on Tesla's History tab.
```bash
stockstui --history TSLA
```

Get combined news for NVIDIA and AMD.
```bash
stockstui --news "NVDA,AMD"
```

Open on Apple's Options tab to view the options chain.
```bash
stockstui --options AAPL
```

Create a temporary watchlist for this session only.
```bash
stockstui --session-list "EV Stocks=TSLA,RIVN,LCID"
```

Launch a 5-day chart for Tesla.
```bash
stockstui --history TSLA --period 5d --chart
```

Open directly to a specific FRED economic series (e.g., Unemployment Rate).
```bash
stockstui --fred UNRATE
```

CLI mode: Output "stocks" list, filtered by the "tech" tag.
```bash
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](https://fred.stlouisfed.org/docs/api/fred/v2/index.html).
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?

```bash
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.