Track your investment portfolio directly from the terminal.

Quick start:

pip install stonks-cli
stonks demo # create demo portfolio

Features:

• Terminal dashboard (TUI) -- live prices with auto-refresh
• Extended-hours quotes -- PRE / AH / CLS session labels for US equities
• Candlestick chart screen -- zoomable OHLC chart
• News feed panel -- per-symbol headlines
• Stock detail screen -- charts, earnings, analyst insights, key statistics
• Backtesting -- simulate historical portfolio performance vs. a benchmark
• AI chat assistant -- ask questions about your portfolio
• Watchlist -- track symbols without a position; dimmed in the dashboard
• Cryptocurrency -- BTC-USD-style symbols priced via CoinGecko
• Multi-portfolio -- side-by-side YAML files with multiple -p flags
• Multi-currency -- totals converted to a base currency using forex rates

Table of Contents

• Installation
• Portfolio configuration
  • File structure
  • Ticker symbols and exchange suffixes
  • Americas
  • Canada
  • Europe
  • Asia-Pacific
  • Cryptocurrency
  • Examples
• Usage
  • Quick snapshot (stdout)
  • Interactive dashboard (TUI)
  • Add a position
  • Remove a position
  • Manage cash
  • List portfolios
  • Importing positions
  • Health checks (doctor)
• Dashboard
  • Columns
  • Session labels
  • Keyboard shortcuts
• News feed
• Candlestick chart
  • Time ranges
  • Keyboard shortcuts
• Stock detail screen
• AI Chat
  • Requirements
  • Environment variables
  • Usage
  • What the assistant can help with
• Logging
• Running with Docker
  • Build the image
  • Run the container
• Backtesting
• Market analysis
• Contributing
• License

Installation

Requirements: Python 3.11+

Homebrew (macOS / Linux)

brew tap igoropaniuk/tap
brew install stonks-cli

pip

pip install stonks-cli

pipx (recommended -- keeps the tool isolated)

pipx install stonks-cli

uv

uv tool 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).

Try it first: run stonks demo to explore the dashboard with a sample portfolio created in the system temporary directory. Your own portfolio at ~/.config/stonks/portfolio.yaml is never touched.

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

    - symbol: BTC-USD
      quantity: 0.5
      avg_cost: 60000.00
      currency: USD
      asset_type: crypto
      external_id: bitcoin

  cash:
    - currency: USD
      amount: 4250.00

    - currency: EUR
      amount: 2100.00

  watchlist:
    - symbol: TSLA
    - symbol: NVDA
    - symbol: LINK-USD
      asset_type: crypto
      external_id: chainlink

Positions fields:

Cash fields:

Watchlist fields:

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

Canada

Europe

Asia-Pacific

Cryptocurrency

Crypto symbols follow Yahoo Finance's BASE-QUOTE convention (e.g. BTC-USD). Prices are fetched from the CoinGecko public API instead of Yahoo Finance. No API key is required; set COINGECKO_DEMO_API_KEY in your environment to use a Demo key for higher rate limits.

Set asset_type: crypto and provide an external_id (the CoinGecko coin ID) for each crypto position or watchlist item. The external_id disambiguates symbols that map to multiple coins and avoids a runtime search API call.

If external_id is omitted, stonks-cli resolves the coin automatically using a bundled symbol map (11 000+ entries) and falls back to the CoinGecko /search endpoint for ambiguous symbols, ranked by market cap.

Examples

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.
  show        Print a snapshot of portfolio positions with current prices to stdout.
  dashboard   Display the current portfolio with live prices and P&L.
  list        List all portfolios in ~/.config/stonks/.
  demo        Launch the TUI with a sample portfolio (your portfolio is untouched).
  feed        Print the latest news headlines for a symbol to stdout.
  detail      Print a financial summary for a symbol to stdout.
  doctor      Run environment health checks.
  import      Import positions from a broker export (subcommands: ibkr).

Quick snapshot (stdout)

Print the current portfolio state with live prices to stdout and exit:

# One-shot table output (no TUI)
stonks show

# With a specific portfolio
stonks -p work show

The output includes the same columns as the dashboard (Instrument, Exchange, Qty, Avg Cost, Last Price, Daily Chg, Daily Chg %, Mkt Value, Unrealized P&L) plus a Total line. Session badges (PRE/AH/CLS) are appended to the last price when applicable. If a price cannot be fetched, N/A is shown instead.

Interactive dashboard (TUI)

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 (symbol is resolved automatically via the bundled coin map)
stonks add BTC-USD 0.5 60000.00

# For precise control, set external_id directly in the YAML:
#   external_id: bitcoin

# 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/.

Importing positions

Positions can be bulk-imported from broker exports instead of being added one by one.

Health checks (doctor)

Run stonks doctor to verify that the environment is configured correctly before opening the TUI:

stonks doctor

# Check a specific portfolio
stonks -p work doctor

# Check multiple portfolios at once
stonks -p personal -p work doctor

Each check prints a coloured OK, WARN, or FAIL line. The command exits with code 0 when everything passes and code 1 if any hard check fails.

Symbol validation is skipped for equity symbols when yfinance is unreachable, and for crypto symbols when CoinGecko is unreachable, to avoid a flood of redundant errors.

Dashboard

Columns

Both daily change columns show -- for closed-session tickers (CLS).

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 columns -- all other columns display --.

Column widths are distributed proportionally and reflow automatically when the terminal is resized.

Session labels

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

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

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

News feed

Press n from the dashboard to toggle the news feed panel. It shows the most recent headlines across all your portfolio symbols and watchlist items, sourced from Yahoo Finance. Articles older than 3 days are filtered out automatically.

Each row shows the publication time, symbol, headline, and source. Click a headline to open it in your browser.

Candlestick chart

Press g on any equity or watchlist row to open an interactive OHLC candlestick chart directly in the terminal. Press Escape or Q to return to the dashboard.

Time ranges

The default view opens at 5D 5m.

Keyboard shortcuts

When you reach the leftmost or rightmost candle, the chart automatically prefetches older or newer data so you can scroll continuously through history. Zooming recentres on the candle under the cursor.

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

AI Chat

Press c from the dashboard to open the AI chat assistant. The assistant has access to your live portfolio snapshot, current prices, forex rates, and recent news headlines, so it can answer questions grounded in your actual data.

Requirements

Set the OPENAI_API_KEY environment variable before starting stonks:

export OPENAI_API_KEY=sk-...
stonks

The input field is disabled with an error message if the key is missing or if live prices have not yet loaded.

Environment variables

OPENAI_BASE_URL is useful for pointing the client at any OpenAI-compatible server -- for example Ollama, LM Studio, or a corporate proxy:

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3
stonks

Usage

• Type a question in the input field and press Enter to send.
• The assistant streams the reply as Markdown directly in the chat log.
• Previous messages are kept in context within the session.
• Press Escape to close the chat and return to the dashboard.

What the assistant can help with

• Portfolio breakdown -- positions, P&L, concentration risk
• Market context -- connecting recent headlines to your holdings
• App usage -- how to load portfolios, configure watchlists, use the CLI

The assistant will not invent prices, news, or ratings. If data is unavailable it will say so explicitly.

Logging

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

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.

Backtesting

Press b from the dashboard to open the backtest configuration form. Backtesting simulates how your portfolio's current allocation would have performed over a historical period, compared against a benchmark index.

Configuration

The portfolio's current allocation weights are held constant throughout the simulation. Historical prices are fetched from Yahoo Finance.

Results

The backtest results screen displays:

• Portfolio Growth chart -- cumulative value of the portfolio vs. the benchmark over the full period
• Annual Returns chart -- side-by-side grouped bar chart showing yearly returns for the portfolio and benchmark, with annotated values
• Summary statistics -- CAGR, max drawdown, Sharpe ratio, best/worst year, and final portfolio value for both the portfolio and the benchmark

If any position symbols lack historical data for the requested start year and Skip unavailable is unchecked, an error message is shown with the earliest available date for each symbol. When the checkbox is enabled (the default), those positions are excluded automatically and their weights are redistributed among the remaining symbols. Skipped positions are listed at the top of the results screen. The benchmark symbol is always required regardless of this setting.

Press Escape or Q to return to the dashboard.

Market analysis

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.