# 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.
---
## ✨ 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.
* **News That Matters**
See the latest headlines per ticker or a combined feed — no ads, no autoplay videos, just info.
* **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.9 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
```bash
stockstui --history TSLA
```
Open on Tesla's History tab.
```bash
stockstui --news "NVDA,AMD"
```
Get combined news for NVIDIA and AMD.
```bash
stockstui --session-list "EV Stocks=TSLA,RIVN,LCID"
```
Create a temporary watchlist for this session only.
```bash
stockstui --history TSLA --period 5d --chart
```
Launch a 5-day chart for Tesla.
---
## ⌨️ 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "stocksTUI",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "tui, stocks, finance, terminal, textual, yfinance",
"author": null,
"author_email": "Andriy <project-git@techie.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/cb/70cfa01a2352a6ff738d456292f5b1493d554a28726acc13a6db3f3125fd/stockstui-0.1.0b5.tar.gz",
"platform": null,
"description": "# stocksTUI\n\nA fast, minimalist terminal app for checking stock prices, crypto, news, and historical charts \u2014 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.\n\n\n\n---\n\n## \u2728 Features\n\n* **Live-ish Price Data**\n Watch your favorite tickers update in near real-time with configurable refresh intervals.\n\n* **Watchlists That Make Sense**\n Organize your assets into lists like \"Tech\", \"Crypto\", \"Dividend Traps\", or \"Memes\". Manage them entirely from the UI \u2014 no need to touch JSON unless you want to.\n\n* **Tag-Based Filtering**\n Assign tags (e.g., `growth`, `ev`, `semiconductor`) to your tickers and instantly filter any watchlist to see only what's relevant.\n\n* **Charts & Tables, Your Way**\n View historical performance from `1D` to `Max`, from a table or a chart.\n\n* **News That Matters**\n See the latest headlines per ticker or a combined feed \u2014 no ads, no autoplay videos, just info.\n\n* **Keyboard-Friendly, Mouse-Optional**\n Navigate everything with Vim-style keys or arrow keys. Bonus: lots of helpful keybindings, fully documented.\n\n* **Custom Themes & Settings**\n 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.\n\n* **Smart Caching**\n The app remembers what it can. Market-aware caching keeps startup fast and avoids pointless API calls on weekends or holidays.\n\n> \u26a0\ufe0f Note: All symbols follow [Yahoo Finance](https://finance.yahoo.com/) format \u2014 e.g., `AAPL` for Apple, `^GSPC` for S\\&P 500, and `BTC-USD` for Bitcoin.\n\n---\n\n## \ud83d\udee0 Requirements\n\n* **Python** 3.9 or newer\n* **OS Support:**\n\n * **Linux / macOS** \u2014 Fully supported\n * **Windows** \u2014 Use **Windows Terminal** with **WSL2**. It *won\u2019t* work in the old `cmd.exe`.\n\n---\n\n## \ud83d\ude80 Installation\n\nThe easiest way to install is with [`pipx`](https://pypa.github.io/pipx/):\n\n### 1. Install pipx (if you don\u2019t already have it):\n\n```bash\n# Debian/Ubuntu\nsudo apt install pipx\n\n# Arch Linux\nsudo pacman -S python-pipx\n\n# macOS\nbrew install pipx\n\n# Or fallback to pip\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n```\n\n### 2. Install stocksTUI:\n\n```bash\npipx install stocksTUI\n```\n\nDone. You can now run `stockstui` from anywhere.\n\n---\n\n## \ud83e\udded Usage\n\nRun the app like so:\n\n```bash\nstockstui\n```\n\nNeed help?\n\n```bash\nstockstui -h # Short help \nstockstui --man # Full user manual \n```\n\n---\n\n### \ud83d\udca1 Command-Line Examples\n\n```bash\nstockstui --history TSLA\n```\n\nOpen on Tesla's History tab.\n\n```bash\nstockstui --news \"NVDA,AMD\"\n```\n\nGet combined news for NVIDIA and AMD.\n\n```bash\nstockstui --session-list \"EV Stocks=TSLA,RIVN,LCID\"\n```\n\nCreate a temporary watchlist for this session only.\n\n```bash\nstockstui --history TSLA --period 5d --chart\n```\n\nLaunch a 5-day chart for Tesla.\n\n---\n\n## \u2328\ufe0f Keybindings\n\n* Press `?` inside the app for a quick keybinding cheat sheet\n* Run `stockstui --man` for the full breakdown\n\n---\n\n## \ud83e\uddd1\u200d\ud83d\udcbb For Developers: Install from Source\n\nWant to try the bleeding-edge version or contribute?\n\n```bash\ngit clone https://github.com/andriy-git/stocksTUI.git\ncd stocksTUI\n./install.sh\n```\n\nThis sets up a virtual environment and a global `stockstui` command so you can test and develop from anywhere.\n\n---\n\n## \u2696\ufe0f License\n\nLicensed under the **GNU GPL v3.0**.\nSee `LICENSE` for the legalese.\n",
"bugtrack_url": null,
"license": null,
"summary": "A stylish and feature-rich Terminal User Interface for monitoring stock prices, news, and historical data.",
"version": "0.1.0b5",
"project_urls": {
"Bug Tracker": "https://github.com/andriy-git/stocksTUI/issues",
"Homepage": "https://github.com/andriy-git/stocksTUI"
},
"split_keywords": [
"tui",
" stocks",
" finance",
" terminal",
" textual",
" yfinance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "392315271d9dcdfe85eca728bb71152df7a2e7681e3ad1e5bc41cba08ac9ccb3",
"md5": "2c26c5ca6b7ca02dbc7acaf608d21c9c",
"sha256": "e07c1bca877819dd9c6ab5b56f089bd6c6c09056ba1bc7547a33fe4687c924fd"
},
"downloads": -1,
"filename": "stockstui-0.1.0b5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c26c5ca6b7ca02dbc7acaf608d21c9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 85531,
"upload_time": "2025-07-23T00:37:47",
"upload_time_iso_8601": "2025-07-23T00:37:47.993076Z",
"url": "https://files.pythonhosted.org/packages/39/23/15271d9dcdfe85eca728bb71152df7a2e7681e3ad1e5bc41cba08ac9ccb3/stockstui-0.1.0b5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ecb70cfa01a2352a6ff738d456292f5b1493d554a28726acc13a6db3f3125fd",
"md5": "21b4518ddbf4ebe9448b44614121453b",
"sha256": "dfa964cdbc94d1de54a9b6e9cfab4898ebada99d799f45610f469917e64e3fd7"
},
"downloads": -1,
"filename": "stockstui-0.1.0b5.tar.gz",
"has_sig": false,
"md5_digest": "21b4518ddbf4ebe9448b44614121453b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 74278,
"upload_time": "2025-07-23T00:37:49",
"upload_time_iso_8601": "2025-07-23T00:37:49.535703Z",
"url": "https://files.pythonhosted.org/packages/0e/cb/70cfa01a2352a6ff738d456292f5b1493d554a28726acc13a6db3f3125fd/stockstui-0.1.0b5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 00:37:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andriy-git",
"github_project": "stocksTUI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "textual",
"specs": [
[
"==",
"3.5.0"
]
]
},
{
"name": "yfinance",
"specs": [
[
"==",
"0.2.65"
]
]
},
{
"name": "pandas-market-calendars",
"specs": [
[
"==",
"5.1.1"
]
]
},
{
"name": "plotext",
"specs": [
[
"==",
"5.3.2"
]
]
},
{
"name": "textual_plotext",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.3.0"
]
]
}
],
"lcname": "stockstui"
}
JSON
