A beautiful, interactive terminal UI stock screener built with Go and the Charm ecosystem.
Find undervalued stocks using technical analysis, valuation metrics, and confluence scoring.
| Feature | Description |
|---|---|
| Real-time Data | Fetches live stock data from Yahoo Finance API |
| Technical Analysis | RSI, ATR, SMA/EMA, MACD, Bollinger Bands indicators |
| Valuation Metrics | P/B Ratio, P/E Ratio, Graham Number, Book Value |
| Risk Management | Dynamic Stop-Loss/Take-Profit based on ATR volatility |
| Confluence Scoring | Combined weighted score (Technical + Valuation + Risk) |
| Price Alerts | Set alerts for Price, RSI, or % Change with visual notifications |
| Filter Controls | Adjust RSI, PBV, and Score thresholds dynamically |
| Search & Sort | Quick filter by symbol and sort by any column |
| Auto-load History | Automatically loads last scan on startup |
| Auto-scan | Starts scanning automatically if no history exists |
| Help & Legends | Built-in help with color legends and shortcuts |
| Responsive UI | Adapts to different terminal sizes |
| Interactive TUI | Navigate with arrow keys or vim-style bindings |
| Watchlist | Pin favorite stocks with persistent JSON storage |
| Scan History | Browse and reload previous scan results |
| 154+ Stocks | Default scan covers major US equities across all sectors |
┌──────────────────────────────────────────────────────────────────┐
│ ◉ STOCKMAP v1.0 Market: OPEN Strategy: Deep Value │
├──────────────────────────────────────────────────────────────────┤
│ │
│ TICKER │ PRICE │ TP │ SL │ RSI │ VOL │ SCORE │
│ ───────┼─────────┼─────────┼─────────┼──────┼──────┼───────────│
│ * SLV │ $22.10 │ $24.50 │ $20.80 │ 31.2 │ 18 │ 88 ██████ │
│ * WDC │ $64.50 │ $72.10 │ $61.20 │ 34.5 │ 22 │ 82 █████ │
│ INTC │ $30.15 │ $35.00 │ $28.50 │ 28.9 │ 15 │ 95 ██████ │
│ VZ │ $39.80 │ $43.20 │ $38.10 │ 30.1 │ 12 │ 78 █████ │
│ │
├──────────────────────────────────────────────────────────────────┤
│ [S]can [R]eload [F]ilter [D]etails [W]atch [H]istory [I]nfo [Q] │
│ Scanned: 154 │ Found: 4 │ Updated: 12:34:56 │
└──────────────────────────────────────────────────────────────────┘
curl -sSL https://raw.githubusercontent.com/febritecno/stockmap-cli/main/install.sh | bashgo install github.com/febritecno/stockmap-cli@latest# Clone repository
git clone https://github.com/febritecno/stockmap-cli.git
cd stockmap-cli
# Build using Make
make build
# Install using Make (installs to $GOPATH/bin)
make install
# Run
./stockmapDownload from the Releases page.
To uninstall StockMap and remove it from your system:
curl -sL https://raw.githubusercontent.com/febritecno/stockmap-cli/main/uninstall.sh | bash# Launch interactive TUI
stockmap
# Show version
stockmap version
# Quick scan
stockmap scan- With History: Automatically loads the most recent scan results
- Without History: Automatically starts scanning all stocks
| Key | Action |
|---|---|
S |
Open scan mode selection |
R |
Reload/Refresh data (toggle) |
T |
Toggle auto-reload (60s interval) |
F |
Open filter criteria editor |
D / Enter |
View stock details |
I |
Show help/tutorial/legends |
W |
View watchlist |
H |
View scan history |
P |
View price alerts |
A |
Add selected to watchlist |
X |
Clear all results |
C |
Check connection status |
/ |
Quick search by symbol |
Tab |
Cycle sort column |
Shift+Tab |
Toggle sort direction |
↑ / k |
Move up |
↓ / j |
Move down |
Esc |
Go back / Clear search |
Q / Ctrl+C |
Quit |
| Key | Action |
|---|---|
G |
Toggle price chart |
A |
Add to watchlist |
R |
Remove from watchlist |
Esc |
Back to dashboard |
| Key | Action |
|---|---|
A |
Add new symbol |
H |
Browse stock categories |
R |
Remove selected |
D / Enter |
View details |
Esc |
Back to dashboard |
| Key | Action |
|---|---|
N |
Create new alert |
D |
Delete selected alert |
T |
Toggle alert active/inactive |
R |
Reset triggered status |
C |
Clear all triggered alerts |
Space |
Cycle alert type (in input mode) |
Esc |
Back to dashboard |
| Key | Action |
|---|---|
↑ / k |
Select previous field |
↓ / j |
Select next field |
+ / = / → |
Increase value |
- / ← |
Decrease value |
Enter |
Edit value directly |
R |
Reset to defaults |
Esc |
Apply and go back |
| Key | Action |
|---|---|
Enter |
Load selected scan |
X |
Delete selected scan |
↑ / k |
Move up |
↓ / j |
Move down |
Esc |
Back to dashboard |
| Key | Action |
|---|---|
Esc / I |
Close help |
Press I to view the built-in help with color legends:
| Range | Color | Meaning |
|---|---|---|
| 75-100 | Green | Strong Buy Signal |
| 50-74 | Yellow | Moderate Signal |
| 0-49 | Red | Weak Signal |
| Range | Color | Meaning |
|---|---|---|
| < 30 | Green | Oversold (Buy opportunity) |
| 30-70 | White | Neutral |
| > 70 | Red | Overbought (Sell signal) |
| Range | Color | Meaning |
|---|---|---|
| < 1.0 | Green | Undervalued |
| 1.0-2.0 | White | Fair value |
| > 2.0 | Red | Overvalued |
| Range | Color | Meaning |
|---|---|---|
| < 20% | Green | Low risk |
| 20-40% | White | Moderate risk |
| > 40% | Red | High risk |
| Symbol | Meaning |
|---|---|
* |
Pinned/Watchlist stock |
TP |
Take Profit target price |
SL |
Stop Loss price |
StockMap uses a Deep Value strategy combining multiple factors:
- RSI < 40 - Oversold/neutral territory preferred
- Price < SMA20 - Trading below short-term average
- Risk:Reward >= 1:1.5 - Favorable entry points
- P/B Ratio < 2.0 - Trading near or below book value
- Graham Upside > 0% - Potential upside to intrinsic value
- Low P/E Ratio - Earnings relative to price
| Component | Weight | Criteria |
|---|---|---|
| Technical | 30% | RSI, price vs SMA, risk/reward |
| Valuation | 40% | PBV, Graham upside, P/E |
| Risk | 30% | Volatility-adjusted |
Bonus Points:
- Both oversold AND undervalued
- PBV < 1.0 (below book value)
- Graham Upside > 50%
- Risk:Reward >= 1:2.5
Default watchlist stored in config/watchlist.json:
{
"symbols": ["SLV", "GDX"]
}Edit this file to customize your pinned stocks.
Alerts are stored in config/alerts.json. You can configure:
- Price Above/Below: Trigger when price crosses a threshold
- RSI High/Low: Trigger on overbought/oversold conditions
- % Change: Trigger on significant price movements
Scan results are automatically saved to config/history/ as JSON files:
config/history/
├── scan_20240207_143052.json
├── scan_20240207_120000.json
└── scan_20240206_093015.json
Features:
- Auto-save after each scan completes
- Auto-load last scan on startup
- Browse history with
[H]key - Load any previous scan with
[Enter] - Delete old scans with
[X]
| Element | Color |
|---|---|
| Background | #1a1b26 |
| Primary | #7aa2f7 |
| Success | #9ece6a |
| Warning | #e0af68 |
| Danger | #f7768e |
| Cyan | #7dcfff |
stockmap/
├── cmd/
│ └── root.go # Cobra CLI entry
├── internal/
│ ├── alerts/
│ │ └── alerts.go # Price & RSI alert manager
│ ├── analysis/
│ │ ├── indicators.go # RSI, ATR, SMA, EMA, MACD, Bollinger
│ │ ├── valuation.go # PBV, Graham Number
│ │ └── risk.go # SL/TP calculations
│ ├── fetcher/
│ │ ├── yahoo.go # Yahoo Finance client (library)
│ │ ├── yahoo_direct.go # Direct API client
│ │ ├── symbols.go # Categorized stock symbols
│ │ └── pool.go # Worker pool (10 concurrent)
│ ├── history/
│ │ └── history.go # Scan history management
│ ├── screener/
│ │ ├── engine.go # Core screening logic
│ │ └── scoring.go # Confluence score calculation
│ ├── styles/
│ │ └── styles.go # Lipgloss styling (Tokyo Night)
│ ├── ui/
│ │ ├── app.go # Main Bubble Tea model
│ │ ├── views/
│ │ │ ├── dashboard.go # Main dashboard
│ │ │ ├── scanner.go # Scan progress view
│ │ │ ├── details.go # Stock details with chart
│ │ │ ├── watchlist.go # Watchlist management
│ │ │ ├── history.go # Scan history browser
│ │ │ ├── alerts.go # Price alerts view
│ │ │ ├── filter.go # Filter criteria editor
│ │ │ └── help.go # Help/legends view
│ │ └── components/
│ │ ├── table.go # Responsive data table
│ │ ├── header.go # App header
│ │ └── statusbar.go # Status bar with keys
│ └── watchlist/
│ └── watchlist.go # JSON CRUD operations
├── config/
│ ├── history/ # Saved scan results
│ ├── alerts.json # User alerts
│ └── watchlist.json # User watchlist
├── main.go
├── go.mod
└── README.md
- Go v1.21 or higher
- Terminal with UTF-8 and True Color support
- Internet connection for Yahoo Finance API
| Package | Purpose |
|---|---|
| bubbletea | TUI framework |
| lipgloss | Terminal styling |
| finance-go | Yahoo Finance API |
| cobra | CLI framework |
Run the test suite to verify functionality:
# Run all tests
go test -v ./...
# Run short tests
go test -short ./...
# Run screener tests specifically
go test -v ./internal/screener/...If you encounter errors connecting to the Yahoo Finance API on Termux (e.g., certificate errors or "no such host"), try the following:
-
Run Connection Diagnostics:
stockmap debug
This will test your connectivity and print detailed error messages.
-
Install CA Certificates: Termux might be missing root certificates.
pkg install ca-certificates
-
DNS Issues: If you see DNS resolution errors (e.g.,
dial tcp: lookup ...: no such host), try using the new--dnsflag to force a working resolver (like Google DNS):stockmap scan --dns=8.8.8.8
Or use the
debugcommand to test connectivity:stockmap debug --dns=8.8.8.8
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
This tool is for educational and informational purposes only.
It is not financial advice. The screening criteria and confluence scores are based on quantitative metrics and do not guarantee future performance. Always do your own research before making investment decisions.
Made with Go using Bubble Tea