# StockWise

> Stock market toolkit for the terminal, built for Indian (NSE/BSE) and US stocks: quotes, charts, technicals, screeners, mutual funds (AMFI), F&O option chains, commodities, G-secs, crypto and FX, backtests, paper trading, portfolio tracking with XIRR, capital-gains and advance tax, goal planning. One binary, no API keys, no account. Also an MCP server (`stockwise mcp`) that gives AI assistants the same data as 35 read-only tools.

Key facts for agents:

- Install: `cargo binstall stockwise`, the one-line installer, `.deb`/`.rpm`, Scoop, Nix or Docker (`ghcr.io/iamsaquib8/stockwise`). PyPI, Homebrew, winget and the AUR are not published yet. Check with `stockwise doctor`.
- Bare tickers are Indian (`TCS` means `TCS.NS`); add `-m us`, `-m crypto`, `-m fx`, `-m commodity` or an exchange (`-m uk`, `de`, `jp`, `hk`, `sg`, `ca`, `au`).
- Add `--json` for machine-readable output (many commands; tables also take `--csv`; `stockwise <command> --help` shows which). stdout then holds only JSON; errors go to stderr with exit code 1.
- Prefer the MCP server when it is connected: `stockwise mcp` (stdio) or `stockwise mcp --http 127.0.0.1:8788`. Its tools are read-only; `stockwise mcp --list-tools` prints them with their schemas.
- Live orders (`stockwise trade`) move real money: never run them for a user without their explicit request, and they always ask for a typed confirmation.
- Output is educational information, not financial advice.

## Docs

- [Introduction](https://iamsaquib8.github.io/stockwise/index.md): A command-line tool for investors in Indian (NSE/BSE) and US markets.
- [Install](https://iamsaquib8.github.io/stockwise/install.md): StockWise is one binary with no runtime dependencies.
- [Quickstart: five minutes](https://iamsaquib8.github.io/stockwise/quickstart.md): Five minutes from install to a quote, a portfolio with XIRR and a tax estimate.
- [Pick your path](https://iamsaquib8.github.io/stockwise/guides.md): Task-based guides: import trades, Indian capital-gains tax, quick lookups, rebalancing, AI assistants over MCP, alerts, backtests and practice, scripting.
- [Import your trades and see true returns](https://iamsaquib8.github.io/stockwise/guide-portfolio.md): This guide loads your broker trades and mutual-fund statement into StockWise and shows your holdings with profit and XIRR.
- [File your Indian capital-gains tax](https://iamsaquib8.github.io/stockwise/guide-tax.md): This guide takes the lots and sales in your portfolio and turns them into a capital-gains estimate, a list of what you could book before 31 March, an advance-tax schedule, and a CSV laid out for ITR Schedule CG and Schedule 112A.
- [Check a stock or fund fast](https://iamsaquib8.github.io/stockwise/guide-research.md): This guide shows how to size up a stock or a mutual fund in a few minutes: a quote, a one-page overview, accounting-quality scores, a timeline of events and what a fund's past SIP returned.
- [Rebalance to target weights](https://iamsaquib8.github.io/stockwise/guide-rebalance.md): This guide sets the weight you want for each holding and shows how many shares to buy to move toward it.
- [Use StockWise from Claude or Cursor](https://iamsaquib8.github.io/stockwise/guide-mcp.md): This guide connects an AI assistant to StockWise so you can ask questions about quotes, your portfolio and your tax estimate in plain English.
- [Set up alerts and the daemon](https://iamsaquib8.github.io/stockwise/guide-alerts.md): This guide makes StockWise tell you when a price, RSI level or result date needs your attention, and shows how to leave it running.
- [Backtest and practise on past markets](https://iamsaquib8.github.io/stockwise/guide-practice.md): This guide covers two ways to learn from history without risking money.
- [Script it with JSON, CSV and jq](https://iamsaquib8.github.io/stockwise/guide-scripting.md): This guide shows how to take StockWise output into a spreadsheet, a shell script, a cron job or another program.
- [Cheatsheet](https://iamsaquib8.github.io/stockwise/cheatsheet.md): One page of the commands people use most.
- [Commands](https://iamsaquib8.github.io/stockwise/commands.md): `stockwise --help` lists every command by group; `stockwise <command> --help` shows its arguments.
- [Markets](https://iamsaquib8.github.io/stockwise/markets.md): `-m` picks the market bare tickers belong to.
- [Data providers](https://iamsaquib8.github.io/stockwise/data-providers.md): StockWise gets market data from Yahoo Finance by default — no account or key needed.
- [AI](https://iamsaquib8.github.io/stockwise/ai.md): StockWise works with AI in three ways:
- [Backtesting](https://iamsaquib8.github.io/stockwise/backtesting.md): `stockwise backtest` replays a strategy over daily price history and reports what it would have made after trading costs.
- [Simulator and practice](https://iamsaquib8.github.io/stockwise/simulator.md): Practice mode turns the paper-trading simulator into a way to learn.
- [Bots and alerts](https://iamsaquib8.github.io/stockwise/bots.md): 9-strategy multi-signal engine for day trading.
- [Bot design](https://iamsaquib8.github.io/stockwise/bot-design.md): How the intraday and long-term bots and the daemon work, and what is planned.
- [Brokers and live trading](https://iamsaquib8.github.io/stockwise/brokers.md): StockWise can read your holdings and place orders through a broker's API, and import holdings from broker exports and CAS statements.
- [Terminal dashboard](https://iamsaquib8.github.io/stockwise/tui.md): A full-screen, live version of `stockwise dashboard`: market indices, your watchlist, portfolio P&L, price alerts, and a chart of the selected symbol, refreshed in place.
- [Web dashboard and API](https://iamsaquib8.github.io/stockwise/server.md): `stockwise serve` runs a small web dashboard for your browser, exposes StockWise data as JSON for remote dashboards, spreadsheets, Grafana or Home Assistant, and serves Prometheus metrics for the server and the intraday daemon.
- [Troubleshooting](https://iamsaquib8.github.io/stockwise/troubleshooting.md): What to do when Yahoo or NSE does not answer, price data is missing, a ticker is unknown or an import skips a symbol, and where your data folder is.
- [How StockWise compares](https://iamsaquib8.github.io/stockwise/comparison.md): StockWise is a free, open-source command-line toolkit that runs on your own machine.

## AI assistants

- [MCP server and `stockwise ask`](https://iamsaquib8.github.io/stockwise/ai.md): tools, resources, prompts, client setup for Claude Desktop, Claude Code and Cursor
- [Agent Skill](https://github.com/iamsaquib8/stockwise/blob/main/skills/stockwise/SKILL.md): how an agent should use the CLI and the MCP server
- [MCP registry entry](https://github.com/iamsaquib8/stockwise/blob/main/server.json): `io.github.iamsaquib8/stockwise`

## Commands

### Quotes and markets

- Quote Indian stocks: `stockwise quote RELIANCE TCS` (or bare `stockwise RELIANCE`)
- Quote US stocks: `stockwise quote AAPL NVDA -m us`
- Everything about one stock: `stockwise deep HDFCBANK`
- Indian and US indices: `stockwise markets`
- One index per exchange worldwide: `stockwise markets --global`
- Gainers and losers: `stockwise movers`
- Scan all of NIFTY 500 in one NSE request, one cap tier: `stockwise -m in movers --universe nifty500 --cap mid`
- Large / mid / small / micro stocks of a screen or heatmap: `stockwise screen momentum --cap small`, `stockwise heatmap --cap large`
- Sector performance: `stockwise sectors`
- Find a ticker by name: `stockwise search "tata motors"`
- First-run setup: market, holdings import, MCP snippet: `stockwise init` (no prompts without a TTY: `init --market in --import groww:FILE --no-mcp`)
- Check your setup: `stockwise doctor`
- Persistent response cache: size, clear: `stockwise cache status` / `stockwise cache clear`
- Pre-load the market universe into `cache.db`: `stockwise cache warm` (or `--background`)
- Filter cached stocks offline by cap, sector, P/E, RVOL: `stockwise cache snapshots --cap large --min-pe 10 --sort roe`
- Run the background worker (live quotes, tasks, alerts, post-close sync): `stockwise worker start` / `status` / `stop`
- Post-close notices: LTCG turns, new quarters, new non-routine NSE filings of held `.NS` stocks (each sent once): `stockwise tasks add eod` queues it for a running worker (`worker start`)
- Queue a long job and follow it: `stockwise tasks add run -- backtest TCS` then `stockwise tasks` / `tasks show 1`

### Analysis

- Fundamentals in plain English: `stockwise analyze INFY`
- Key events & filings timeline: `stockwise events LT`
- Last 8 quarters: YoY, QoQ, OPM, TTM, beat/miss: `stockwise results TCS` · `results AAPL -m us --quarters 12` · `results TCS --annual`
- Earnings-season scoreboard: `stockwise results --universe nifty50` · `results --holdings --csv`
- Positive and negative findings: `stockwise insights LT`
- 6-pillar score (not a recommendation): `stockwise verdict LT` · `stockwise verdict LT --explain`
- Piotroski F-score & Altman Z-score: `stockwise score INFY --explain` · `stockwise scorecard TCS --json`
- Open and upcoming IPOs: `stockwise ipo`
- One IPO: demand, scores and allotment odds: `stockwise ipo BCSSL --capital 2.5L`
- RSI, MACD, Bollinger Bands: `stockwise technical TCS -p 6mo --explain`
- Price chart with volume: `stockwise history AAPL -m us -p 1y`
- Compare stocks: `stockwise compare TCS INFY WIPRO`
- Volatility, Sharpe, drawdown: `stockwise risk HDFCBANK`
- Support and resistance: `stockwise support RELIANCE`
- Stop-loss levels: `stockwise stoploss TCS --entry 3500`
- Preset screens: `stockwise screen growth`
- Results and dividend dates: `stockwise calendar`

### Funds, options, commodities, bonds

- Find a mutual fund: `stockwise mf search parag flexi direct`
- SIP returns (XIRR) for a fund: `stockwise mf sip 122639 5000 -p 5y`
- Rank a category by return: `stockwise mf screen flexi cap`
- Regular vs Direct plan cost of the funds you hold: `stockwise mf bleed --return 10`
- Option chain with greeks: `stockwise options chain NIFTY`
- Put/call ratio, max pain: `stockwise options pcr BANKNIFTY` · `stockwise options maxpain NIFTY`
- OI build-up & resistance/support walls: `stockwise fno oi NIFTY` · `stockwise options oi BANKNIFTY -n 5 --explain`
- Strategy payoff: `stockwise options payoff NIFTY --strategy iron-condor --width 200`
- Gold and silver in ₹/10 g: `stockwise commodity spot`
- Sovereign Gold Bonds: `stockwise commodity sgb`
- G-sec and T-bill yields: `stockwise bonds yields`

### Portfolio and tax

- Add a purchase (a lot): `stockwise portfolio add TCS 10 3500 --date 2023-04-12`
- Sell (oldest lots first): `stockwise portfolio sell TCS 5 3900`
- Preview a sale: lots, STCG/LTCG tax, LTCG countdown (saves nothing): `stockwise portfolio sell TCS 5 --preview` (alias `--dry-run`)
- Regular-plan funds vs Direct: TER gap, yearly and 10Y cost, switch units: `stockwise mf bleed`
- Holdings, P&L and XIRR: `stockwise portfolio`
- Track a mutual fund (AMFI code or ISIN, valued at its NAV): `stockwise portfolio add MF:122639 100 80 --date 2024-01-10`
- Portfolio X-Ray (overlap, concentration, sectors): `stockwise portfolio xray` · `stockwise portfolio xray --json`
- Import from your broker: `stockwise import kite holdings.xlsx` (CSV or `.xlsx`; also `groww`, `upstox`, `indmoney`, `cas`)
- Import a password-protected CAS PDF (needs `casparser`): `stockwise import cas CAS.pdf` · `casparser ... | stockwise import cas -`
- Rebuild a symbol's lots from a dated file: `stockwise import kite tradebook.csv --replace`
- One holding's lots, sales and XIRR: `stockwise portfolio lots TCS`
- Compare with NIFTY: `stockwise portfolio benchmark NIFTY -p 1y`
- Splits, bonuses, dividends: `stockwise portfolio actions --apply`
- Set target allocation: `stockwise portfolio target set TCS 25` · `stockwise portfolio target show`
- Inflow rebalance (buy-only): `stockwise rebalance --inflow 50000` (buy underweight without selling)
- Rebalance with drift band: `stockwise rebalance --drift 2.0`
- Tax-loss & LTCG exemption harvest: `stockwise harvest` · `stockwise harvest --json`
- Capital-gains estimate: `stockwise tax in`
- ITR Schedule CG CSV: `stockwise tax export in --out cg.csv`
- Advance tax schedule & 234C estimator: `stockwise tax advance` · `stockwise tax advance --paid 25000`
- Advance tax with each payment dated (exact 234C): `stockwise tax advance --fy 2025-26 --paid 2025-06-14:3000 --paid 2025-09-10:5000`
- Everything on one screen: `stockwise dashboard`

### Alerts and watchlist

- Watch stocks: `stockwise watch add INFY HDFCBANK`
- Price alert: `stockwise alert add RELIANCE below 1200`
- RSI alert: `stockwise alert add TCS rsi-below 30`
- Moving-average cross: `stockwise alert add INFY cross-above-sma 200`
- Breakout alert: `stockwise alert add SBIN breakout-high 52`
- Keep checking during market hours: `stockwise alert watch`
- Set up Telegram/Slack/email: `stockwise notify`

### Planning

- SIP needed for a target: `stockwise goal sip --target 1cr --years 15`
- Retirement corpus and SIP: `stockwise goal retire --monthly-expense 80000 --years-to-retire 20 --years-in-retirement 30`
- Education fund: `stockwise goal education --cost 25L --years 10`
- Short goal, ₹10L in hand after tax: `stockwise goal sip --target 10L --months 9 --net`
- Save a goal, track it: `stockwise goal add house --target 50L --by 2031-06` · `stockwise goal list`
- How long a corpus lasts: `stockwise goal swp --corpus 1cr --withdrawal 50k`
- Prepay a loan or invest: `stockwise goal prepay --principal 50L --loan-rate 9 --remaining-months 240 --extra 10k`
- What a past SIP became: `stockwise sip NIFTYBEES 5000 -p 5y`
- What a lump sum became: `stockwise whatif TCS 100000 2015-01-01`

### Strategies and practice

- Backtest a strategy (after costs): `stockwise backtest INFY -s macd`
- Backtest a basket: `stockwise backtest portfolio TCS INFY WIPRO -s rsi`
- Walk-forward test: `stockwise backtest walkforward TCS -s sma --train 1y --test 3mo`
- Paper-trade one session, then exit (for cron): `stockwise daemon intraday 25000 --once`
- Replay the 2020 crash: `stockwise sim replay start covid-crash-2020`
- Take a challenge: `stockwise sim challenge start beat-the-index`
- Your badges and best scores: `stockwise sim profile`
- Shareable result card: `stockwise sim card --svg card.svg`

### AI assistants

- Ask in plain English (local Ollama by default): `stockwise ask "how did my portfolio do this month?"`
- See which tools it ran: `stockwise ask "compare TCS and INFY on RSI and risk" --verbose`
- MCP server for Claude, Cursor and other assistants: `stockwise mcp`
- Add it to Claude Code: `claude mcp add stockwise -- stockwise mcp`
- The MCP tools and their schemas: `stockwise mcp --list-tools`
- MCP over HTTP: `stockwise mcp --http 127.0.0.1:8788`

### Dashboards and scripting

- Live terminal dashboard: `stockwise tui`
- Web dashboard and JSON API: `stockwise serve --open`
- Pipe into jq: `stockwise quote TCS INFY --json | jq '.[].regularMarketPrice'`
- Save your defaults: `stockwise config init`
- Shell completion: `stockwise completions zsh > ~/.zfunc/_stockwise`

### Live trading (real money)

- Connect a broker: `stockwise trade setup`
- Check a broker read-only: `stockwise trade selftest`
- Preview an order, send nothing: `stockwise trade buy RELIANCE 1 --dry-run`
- Live holdings: `stockwise trade holdings`

## Optional

- [Roadmap](https://iamsaquib8.github.io/stockwise/roadmap.md): The plan from today to a public 1.0, then what comes after.
- [Changelog](https://iamsaquib8.github.io/stockwise/changelog.md): All notable changes to this project are documented here.
- [Contributing](https://iamsaquib8.github.io/stockwise/contributing.md): How to build StockWise, run the checks and send a change.
- [Architecture](https://iamsaquib8.github.io/stockwise/architecture.md): Map of the source tree, data flow, caching, storage and dependencies.
- [Exchange response fixtures](https://iamsaquib8.github.io/stockwise/exchange-responses.md): The `nse`, `bse` and `exchange` data providers (data-providers.md) read the JSON endpoints behind nseindia.com and bseindia.com.
- [Disclaimer](https://iamsaquib8.github.io/stockwise/disclaimer.md): StockWise is for educational and informational purposes only.