# stocksTUI
A Terminal User Interface for monitoring stock prices, news, and historical data, built with [Textual](https://github.com/textualize/textual). Information is fetched using the [yfinance](https://github.com/ranaroussi/yfinance) API.
## Features
- 📈 **Real-Time(ish) Price Data** – Because latency is still better than CNBC ads.
- 🧮 **Custom Watchlists** – Sort your tech bros from your energy overlords.
- 📊 **Historical Charts** – Plots your portfolio’s regrets with style.
- 📰 **Ticker News** – Stay smarter than the talking heads.
- 🎨 **Theming** – Dark mode? Light mode? You've got taste, and now you’ve got options.
- ⚙️ **Configurable Everything** – Refresh rate, default views, and more are all tweakable from the config screen.
**Note:** All ticker symbols must be in the format used by [Yahoo Finance](https://finance.yahoo.com/) (e.g., `AAPL` for Apple, `^GSPC` for S&P 500, `BTC-USD` for Bitcoin).
## Requirements
- **Python:** 3.9 or newer.
- **Operating System:**
- **Linux / macOS:** Fully supported.
- **Windows:** Requires **Windows Terminal** with PowerShell, or **WSL2**. The application will *not* work correctly in the legacy `cmd.exe` console due to its reliance on advanced terminal features.
## Installation
The recommended way to install stocksTUI is with `pipx`. This installs the application and its dependencies in an isolated environment, ensuring that it does not conflict with any other Python packages on your system.
#### 1. Install `pipx`
If you don't have `pipx` installed, you can install it with your system's package manager or with `pip`.
```bash
# On Debian/Ubuntu
sudo apt install pipx
# On Arch Linux
sudo pacman -S python-pipx
# On macOS
brew install pipx
# Or, using pip (ensure ~/.local/bin is in your PATH)
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
#### 2. Install stocksTUI
Once `pipx` is installed, you can install stocksTUI with a single command:
```bash
pipx install stocksTUI
```
## Usage
To run the application, simply execute the following command in your terminal:
```bash
stockstui
```
## Keybindings
| Key | Action | Context |
| --------------- | ----------------------------- | ------------ |
| `q` | Quit the application | Global |
| `r` | Refresh current view | Global |
| `R` (`Shift+R`) | Refresh all lists in background | Global |
| `s` | Enter Sort Mode | Price/History |
| `?` | Toggle Help Screen | Global |
| `/` | Search in current table | Tables |
| `1-0` | Switch to corresponding tab | Global |
| `h, j, k, l` | Navigate / Scroll | All |
| `Up, Down` | Navigate / Scroll | All |
| `Left, Right` | Navigate | All |
| `Tab, Shift+Tab`| Focus next/previous widget | Global |
| `Enter` | Select / Action | All |
| `Esc` | Close dialog/search, exit sort mode, or focus tabs | Global |
In Sort Mode (after pressing `s`):
| Key | Action | Context |
| --- | -------------------- | ------------- |
| `d` | Sort by Description/Date | Price/History |
| `p` | Sort by Price | Price |
| `c` | Sort by Change/Close | Price/History |
| `e` | Sort by % Change | Price |
| `t` | Sort by Ticker | Price |
| `u` | Undo Sort | Price |
| `H` | Sort by High | History |
| `L` | Sort by Low | History |
| `v` | Sort by Volume | History |
## For Developers: Installing from Source
If you want to run the latest code or contribute to development, you can install from the source repository.
1. **Clone the repository:**
```bash
git clone https://github.com/andriy-git/stocksTUI.git
cd stocksTUI
```
2. **Run the installation script:**
This script will create a virtual environment, install all dependencies in editable mode, and create a symlink for the `stockstui` command.
```bash
./install.sh
```
3. **Run the application:**
You can now run the application from anywhere.
```bash
stockstui
```
## License
This project is licensed under the GNU General Public License v3.0. See the `LICENSE` file for details.
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/c2/55/eefc04bc526e827d7e4b5783e5dd013b50abfe040e414884b3091ce10448/stockstui-0.1.0b2.tar.gz",
"platform": null,
"description": "# stocksTUI\n\nA Terminal User Interface for monitoring stock prices, news, and historical data, built with [Textual](https://github.com/textualize/textual). Information is fetched using the [yfinance](https://github.com/ranaroussi/yfinance) API.\n\n\n\n## Features\n\n- \ud83d\udcc8 **Real-Time(ish) Price Data** \u2013 Because latency is still better than CNBC ads.\n- \ud83e\uddee **Custom Watchlists** \u2013 Sort your tech bros from your energy overlords.\n- \ud83d\udcca **Historical Charts** \u2013 Plots your portfolio\u2019s regrets with style.\n- \ud83d\udcf0 **Ticker News** \u2013 Stay smarter than the talking heads.\n- \ud83c\udfa8 **Theming** \u2013 Dark mode? Light mode? You've got taste, and now you\u2019ve got options.\n- \u2699\ufe0f **Configurable Everything** \u2013 Refresh rate, default views, and more are all tweakable from the config screen.\n\n**Note:** All ticker symbols must be in the format used by [Yahoo Finance](https://finance.yahoo.com/) (e.g., `AAPL` for Apple, `^GSPC` for S&P 500, `BTC-USD` for Bitcoin).\n\n## Requirements\n\n- **Python:** 3.9 or newer.\n- **Operating System:**\n - **Linux / macOS:** Fully supported.\n - **Windows:** Requires **Windows Terminal** with PowerShell, or **WSL2**. The application will *not* work correctly in the legacy `cmd.exe` console due to its reliance on advanced terminal features.\n\n## Installation\n\nThe recommended way to install stocksTUI is with `pipx`. This installs the application and its dependencies in an isolated environment, ensuring that it does not conflict with any other Python packages on your system.\n\n#### 1. Install `pipx`\n\nIf you don't have `pipx` installed, you can install it with your system's package manager or with `pip`.\n\n```bash\n# On Debian/Ubuntu\nsudo apt install pipx\n\n# On Arch Linux\nsudo pacman -S python-pipx\n\n# On macOS\nbrew install pipx\n\n# Or, using pip (ensure ~/.local/bin is in your PATH)\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n```\n\n#### 2. Install stocksTUI\n\nOnce `pipx` is installed, you can install stocksTUI with a single command:\n\n```bash\npipx install stocksTUI\n```\n\n## Usage\n\nTo run the application, simply execute the following command in your terminal:\n\n```bash\nstockstui\n```\n\n## Keybindings\n\n| Key | Action | Context |\n| --------------- | ----------------------------- | ------------ |\n| `q` | Quit the application | Global |\n| `r` | Refresh current view | Global |\n| `R` (`Shift+R`) | Refresh all lists in background | Global |\n| `s` | Enter Sort Mode | Price/History |\n| `?` | Toggle Help Screen | Global |\n| `/` | Search in current table | Tables |\n| `1-0` | Switch to corresponding tab | Global |\n| `h, j, k, l` | Navigate / Scroll | All |\n| `Up, Down` | Navigate / Scroll | All |\n| `Left, Right` | Navigate | All |\n| `Tab, Shift+Tab`| Focus next/previous widget | Global |\n| `Enter` | Select / Action | All |\n| `Esc` | Close dialog/search, exit sort mode, or focus tabs | Global |\n\nIn Sort Mode (after pressing `s`):\n\n| Key | Action | Context |\n| --- | -------------------- | ------------- |\n| `d` | Sort by Description/Date | Price/History |\n| `p` | Sort by Price | Price |\n| `c` | Sort by Change/Close | Price/History |\n| `e` | Sort by % Change | Price |\n| `t` | Sort by Ticker | Price |\n| `u` | Undo Sort | Price |\n| `H` | Sort by High | History |\n| `L` | Sort by Low | History |\n| `v` | Sort by Volume | History |\n\n## For Developers: Installing from Source\n\nIf you want to run the latest code or contribute to development, you can install from the source repository.\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/andriy-git/stocksTUI.git\n cd stocksTUI\n ```\n\n2. **Run the installation script:**\n This script will create a virtual environment, install all dependencies in editable mode, and create a symlink for the `stockstui` command.\n ```bash\n ./install.sh\n ```\n\n3. **Run the application:**\n You can now run the application from anywhere.\n ```bash\n stockstui\n ```\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0. See the `LICENSE` file for details.\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.0b2",
"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": "1e9d2d39ec9e2de530e3918af03f69dfd02aa505657a598e0963838316d54394",
"md5": "b6c8c998fa06590ae0e1c13930122ad1",
"sha256": "34813e8400f32592c1e24996d2abfad18724e466a8d23b11be4c73f42e488d20"
},
"downloads": -1,
"filename": "stockstui-0.1.0b2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b6c8c998fa06590ae0e1c13930122ad1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 66540,
"upload_time": "2025-07-12T02:35:11",
"upload_time_iso_8601": "2025-07-12T02:35:11.666199Z",
"url": "https://files.pythonhosted.org/packages/1e/9d/2d39ec9e2de530e3918af03f69dfd02aa505657a598e0963838316d54394/stockstui-0.1.0b2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c255eefc04bc526e827d7e4b5783e5dd013b50abfe040e414884b3091ce10448",
"md5": "7f283ce2f44b14ad6b48522ed4a61205",
"sha256": "b54c9e30b2a013e2630995fd7cebc44d93ee7157be2101a4566767a7e3800733"
},
"downloads": -1,
"filename": "stockstui-0.1.0b2.tar.gz",
"has_sig": false,
"md5_digest": "7f283ce2f44b14ad6b48522ed4a61205",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 59221,
"upload_time": "2025-07-12T02:35:13",
"upload_time_iso_8601": "2025-07-12T02:35:13.085734Z",
"url": "https://files.pythonhosted.org/packages/c2/55/eefc04bc526e827d7e4b5783e5dd013b50abfe040e414884b3091ce10448/stockstui-0.1.0b2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 02:35:13",
"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
