Skip to content

igoropaniuk/stonks-cli

BranchesTags

Repository files navigation

stonks-cli

PyPI version Python versions Install Downloads CI Coverage License CLI

Track your investment portfolio directly from the terminal.

demo

Features

  • Terminal dashboard (TUI) -- live prices refresh automatically every 60 seconds (configurable)
  • Extended-hours quotes -- pre-market, regular, after-hours, and closed session labels for US equities
  • Daily % change -- shows today's gain/loss vs. the previous close for every position and watchlist item
  • Stock detail screen -- press Enter on any row to open charts, earnings trends, analyst insights, and key statistics
  • Watchlist -- track symbols without holding a position; shown in the dashboard with dimmed styling
  • Multi-portfolio -- open several YAML files side-by-side with multiple -p flags
  • Multi-currency -- portfolio totals are converted to a base currency using live forex rates
  • 50+ exchanges -- US, Europe, Asia-Pacific, Americas, and crypto (no dot-suffix for US tickers)
  • Yahoo Finance -- no API token required
  • Holiday-aware sessions -- uses exchange-calendars to detect market holidays correctly
  • Open source -- MIT licensed

Installation

Requirements: Python 3.11+

pip install stonks-cli

Or with pipx (recommended -- keeps the tool isolated):

pipx install stonks-cli

Portfolio configuration

stonks-cli stores your portfolio in a YAML file. By default the file is read from ~/.config/stonks/portfolio.yaml; you can override this with the -p / --portfolio option (see Usage).

First run: if ~/.config/stonks/ contains no .yaml files, stonks-cli automatically creates a sample portfolio at ~/.config/stonks/portfolio.yaml so you can explore the dashboard right away. Replace its contents with your own positions whenever you are ready.

File structure

portfolio:
  positions:
    - symbol: AAPL
      quantity: 10
      avg_cost: 150.00
      currency: USD

    - symbol: ASML.AS
      quantity: 5
      avg_cost: 680.00
      currency: EUR

    - symbol: 7203.T
      quantity: 100
      avg_cost: 1850.00
      currency: JPY

  cash:
    - currency: USD
      amount: 4250.00

    - currency: EUR
      amount: 2100.00

  watchlist:
    - symbol: TSLA
    - symbol: NVDA

Positions fields:

Field Type Required Description
symbol string yes Yahoo Finance ticker (case-insensitive)
quantity int yes Shares held (positive integer)
avg_cost float yes Average cost per share (positive)
currency string no ISO 4217 code; defaults to USD

Cash fields:

Field Type Required Description
currency string yes ISO 4217 code (e.g. USD, EUR)
amount float yes Cash held (positive)

Watchlist fields:

Field Type Required Description
symbol string yes Yahoo Finance ticker (case-insensitive)

Watchlist items are displayed in the dashboard with a dimmed style and only show the live price and daily change -- they have no quantity, cost, or market value and are not included in the portfolio total. Press Enter on a watchlist row to open the detail screen.

The file is created and updated automatically when you use the add, remove, add-cash, and remove-cash commands, so you only need to create it manually if you prefer to seed your data by hand.

Ticker symbols and exchange suffixes

Yahoo Finance uses a dot-suffix convention to identify non-US exchanges. Append the appropriate suffix to the base ticker symbol.

Americas

Suffix Exchange Country
(none) NYSE / NASDAQ / AMEX USA
.SA B3 (São Paulo) Brazil
.BA Buenos Aires Stock Exchange Argentina
.MX Bolsa Mexicana de Valores Mexico
.SN Santiago Stock Exchange Chile
.LIM Lima Stock Exchange Peru

Canada

Suffix Exchange Country
.TO Toronto Stock Exchange Canada
.V TSX Venture Exchange Canada

Europe

Suffix Exchange Country
.L London Stock Exchange UK
.PA Euronext Paris France
.AS Euronext Amsterdam Netherlands
.BR Euronext Brussels Belgium
.LS Euronext Lisbon Portugal
.MI Borsa Italiana Italy
.DE XETRA Germany
.F Frankfurt Stock Exchange Germany
.SW SIX Swiss Exchange Switzerland
.ST Nasdaq Stockholm Sweden
.HE Nasdaq Helsinki Finland
.CO Nasdaq Copenhagen Denmark
.OL Oslo Børs Norway
.WA Warsaw Stock Exchange Poland
.AT Athens Stock Exchange Greece

Asia-Pacific

Suffix Exchange Country
.AX Australian Securities Exchange Australia
.NZ New Zealand Exchange New Zealand
.HK Hong Kong Stock Exchange Hong Kong
.T Tokyo Stock Exchange Japan
.KS Korea Exchange (KOSPI) South Korea
.KQ KOSDAQ South Korea
.TW Taiwan Stock Exchange Taiwan
.TWO Taiwan OTC Taiwan
.SS Shanghai Stock Exchange China
.SZ Shenzhen Stock Exchange China
.NS National Stock Exchange India
.BO Bombay Stock Exchange India
.JK Indonesia Stock Exchange Indonesia
.SI Singapore Exchange Singapore
.KL Bursa Malaysia Malaysia
.BK Stock Exchange of Thailand Thailand
.VN Ho Chi Minh Stock Exchange Vietnam

Examples

Symbol Instrument
AAPL Apple (NASDAQ)
ASML.AS ASML (Euronext Amsterdam)
7203.T Toyota (Tokyo SE)
HSBA.L HSBC (London SE)
005930.KS Samsung (KOSPI)
BTC-USD Bitcoin / USD
ETH-EUR Ethereum / EUR

Usage

stonks [OPTIONS] COMMAND [ARGS]...

Options:
  -p, --portfolio PATH                    Portfolio YAML file or name
                                          (repeatable; default:
                                          ~/.config/stonks/portfolio.yaml)
  --log-level [DEBUG|INFO|WARNING|ERROR]  Log verbosity written to the log
                                          file  [default: WARNING]
  -V, --version                           Show the version and exit.
  --help                                  Show this message and exit.

Commands:
  add          Add QUANTITY shares of SYMBOL at PRICE to the portfolio.
  remove       Remove QUANTITY shares of SYMBOL from the portfolio.
  add-cash     Add AMOUNT of CURRENCY cash to the portfolio.
  remove-cash  Remove AMOUNT of CURRENCY cash from the portfolio.
  dashboard    Display the current portfolio with live prices and P&L.
  list         List all portfolios in ~/.config/stonks/.

Launch the dashboard

Running stonks without a subcommand launches the dashboard automatically. Prices refresh every 60 seconds by default.

# Launch the TUI (dashboard is the default command)
stonks

# Equivalent -- explicit subcommand
stonks dashboard

# Refresh prices every 30 seconds instead
stonks dashboard --refresh 30

# Open two portfolios side by side
stonks -p personal -p work

Add a position

# Add 10 shares of Apple at $150.00
stonks add AAPL 10 150.00

# Add a non-US stock (ASML on Euronext Amsterdam)
stonks add ASML.AS 5 680.00

# Add crypto
stonks add BTC-USD 0.5 60000.00

# Use a named portfolio (resolves to ~/.config/stonks/work.yaml)
stonks -p work add NVDA 2 800.00

When a symbol is added a second time, the quantity is increased and the average cost is recalculated as a weighted average automatically.

Remove a position

# Remove 5 shares (partial close)
stonks remove AAPL 5

# Remove all shares (position deleted)
stonks remove AAPL 10

Manage cash

# Deposit cash
stonks add-cash USD 5000.00
stonks add-cash EUR 2000.00

# Withdraw cash (partial)
stonks remove-cash USD 500.00

# Withdraw all remaining cash of a currency (position deleted)
stonks remove-cash EUR 2000.00

Cash is displayed in the dashboard below the stock positions and is included in the total portfolio value converted to the base currency.

List portfolios

stonks list

Lists all .yaml files found in ~/.config/stonks/.

Dashboard

Columns

Column Description
Instrument Ticker symbol
Exchange Exchange name derived from ticker suffix (e.g. NYSE/NASDAQ, Crypto)
Qty Number of shares held
Avg Cost Average purchase price per share
Last Price Most recent price; tagged PRE, AH, or CLS for non-regular sessions
Daily Chg Percentage change vs. the previous close (green / red)
Mkt Value Current market value (Qty * Last Price)
Unrealized P&L Profit/loss vs. average cost (bold green / bold red)

A Total line at the bottom converts all positions and cash to the portfolio's base currency using live forex rates.

Watchlist rows are dimmed and only show Instrument, Exchange, Last Price, and Daily Chg -- all other columns display --.

Session labels

US equities on exchanges that support extended hours show a session tag next to the price:

Tag Session
PRE Pre-market
AH After-hours / post-market
CLS Market closed
(none) Regular trading hours

Non-US equities and crypto show no tag during regular hours and CLS when the market is closed (using holiday-aware calendar data).

Keyboard shortcuts

Key Action
a Add a new position (equity, crypto, ETF, cash)
e Edit the currently selected position
r Remove the currently selected position
Enter Open the detail screen for the selected row
Tab Switch focus between portfolio tables
q Quit

Column headers are clickable -- click once to sort ascending, again to sort descending.

Stock detail screen

Press Enter on any equity or watchlist row to open a full-screen detail view. Press Escape or Q to return to the dashboard.

The detail screen displays:

  • Performance -- trailing returns (YTD, 1Y, 3Y, 5Y) compared side-by-side with the S&P 500
  • Price charts -- interactive terminal charts for 1 Day, 1 Month, 1 Year, and 5 Years
  • Financial summary -- previous close, open, bid/ask, day range, 52-week range, volume, market cap, P/E, EPS, earnings date, dividend yield
  • Earnings trends -- quarterly EPS actual vs. estimate bar chart; revenue vs. net income chart
  • Analyst insights -- price targets (low / mean / high), consensus rating, and a monthly recommendations breakdown (Strong Buy to Strong Sell)
  • Statistics -- valuation measures and financial highlights

Logging

stonks-cli writes structured log messages to a platform-specific file:

Platform Path
Linux ~/.local/state/stonks/log/stonks.log
macOS ~/Library/Logs/stonks/stonks.log
Windows %LOCALAPPDATA%\stonks\Logs\stonks.log

The default verbosity is WARNING (only warnings and errors are recorded). Use --log-level to capture more detail:

# Capture all debug output
stonks --log-level DEBUG

# Capture info and above
stonks --log-level INFO dashboard --refresh 30

Log entries follow the format:

YYYY-MM-DDTHH:MM:SS  LEVEL     logger_name  message

Running with Docker

Build the image

docker build -t stonks .

Run the container

docker run --rm -it \
  -v ./config/sample_portfolio.yaml:/data/portfolio.yaml:ro \
  stonks --portfolio /data/portfolio.yaml dashboard

The -v flag bind-mounts a local YAML file into the container. Replace ./config/sample_portfolio.yaml with the path to your own portfolio file. Drop :ro if you want add / remove commands to persist changes back to the host.

Market analysis

stonks

Looks bullish.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for development setup, coding style, commit message conventions, and the pull request workflow.

For the release process, see RELEASING.md.

License

MIT License. See LICENSE for details.

About

A terminal-based investment portfolio tracker. Displays your holdings with live market prices, unrealized P&L, and a total portfolio value

Topics

python cli portfolio finance terminal tui forex cryptocurrency markets stock-market market-data stocks investment etf portfolio-tracker yfinance

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

24 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 5

stonks-cli v0.3.1 Latest
Mar 23, 2026
+ 4 releases

Contributors

Languages