Commands Reference

stockwise --help lists every command by group; stockwise <command> --help shows its arguments. This page adds detail.

Looking for a walkthrough instead? What do you want to do? lists task-based guides, and each section below links to its guide.

Global options

Other environment variables: STOCKWISE_HOME (data directory), STOCKWISE_REDIS_URL (cache server, or off), STOCKWISE_DATA_PROVIDER and its API key (data-providers.md), STOCKWISE_AI_PROVIDER, STOCKWISE_MODEL, OLLAMA_HOST and the cloud AI keys (ai.md), STOCKWISE_CONFIG (config file path), STOCKWISE_BIND and STOCKWISE_API_TOKEN (serve), and the notification variables (bots.md). NO_COLOR disables colour; colour is also off when output is piped.

Defaults for most of these, and for each command’s -p, can live in a config file. Precedence: command-line flag > environment variable > config file > built-in default. API keys and the server token are read from the environment only.

Crypto and FX: prices show with the precision they need (FX pairs 4 decimals, coins under 1 up to 8) and quote notes trading hours (crypto 24/7; FX 24 hours Monday–Friday, closed at weekends). Commands built on exchange sessions, sectors or fundamentals — sectors, rotation, sectorcmp, screen, picks, matrix, surprise, peers, intraday, longterm, daemon, sim start — refuse -m crypto / -m fx with an explanation; movers, heatmap, history, technical, backtest and friends work.

Global exchanges (-m uk|de|jp|hk|sg|ca|au): quotes, history, charts, technicals, movers (each exchange’s large caps), markets and alerts work as for India and the US. Prices show in the local currency (£, €, ¥, HK$, S$, C$, A$); London quotes in pence, so VOD.L shows 118.20p while its market cap shows in pounds. sectors, rotation and sectorcmp need sector indices or ETFs, which Yahoo has for Japan (TOPIX-17 ETFs), Hong Kong, Canada and Australia only. Sessions, lunch breaks, half days and holidays come from each exchange’s calendar (markets.md). tax has rules for India, the US and the UK only, and names the other listings it leaves out. Backtest costs default to the US model outside India. The bots and the simulator (intraday, longterm, daemon, sim start, sim replay, sim challenge, report) size positions from the capital you type, so they refuse -m uk, whose prices are in pence; replays on other exchanges use their main index as the benchmark.

Commodities (-m commodity): GOLD/SILVER resolve to COMEX futures, so history gold, chart silver, technical gold and alert add gold above 4200 work; commodity and bonds have their own commands (below).

Hindi (--lang hi): help group titles and the main command descriptions, quote, markets, dashboard, portfolio, search and doctor labels, and common errors. Other commands are still English. Indian amounts keep lakh/crore grouping (₹16.27 लाख करोड़).

Periods (-p): 1d, 5d, 1w (same as 5d), 1mo, 3mo, 6mo, ytd, 1y, 2y, 5y, 10y, max. Value names (screen growth, tax in, -s macd) are case-insensitive.

Exit codes: 0 success, 1 runtime error (unknown symbol, no data, network, invalid config file), 2 invalid arguments.

Machine-readable output: commands marked [--json] print JSON, and [--json\|--csv] print JSON or CSV, instead of a table. See Scripting.

Start here

Guide: Quickstart: five minutes walks through the first commands.

stockwise SYMBOL with no command prints a one-screen overview, and bare stockwise prints a quick start. Short names: q (quote), d (dashboard), a (analyze), t (technical), c (compare), p (portfolio), w (watch), ev (events). The aliases are lowercase: a capital single letter is a ticker, so stockwise C -m us (Citigroup), T, D, A and W work as bare symbols, and stockwise c TCS INFY still compares. A longer ticker that spells a command, such as ALL or PATH, is a symbol when you give -m (stockwise PATH -m us). stockwise quote C -m us always works. Common names resolve to NSE symbols (SBI → SBIN, L&T → LT, index names), and quote suggests close matches for a mistyped symbol.

Analysis

Guide: Check a stock or fund fast.

--explain on verdict, technical, score and options oi adds plain-English notes for beginners.

Market

Guide: Check a stock or fund fast.

--universe (Indian market): scan the current members of an NSE index instead of the built-in 30 large caps — nifty50, niftynext50 (next50), nifty100, banknifty (niftybank), niftyit, nifty500, midcap150 or smallcap250. NSE’s website lists the members and prices them in one bulk request (all 500 of nifty500), whichever data provider you use. movers and heatmap rank from that snapshot alone, so they work when Yahoo Finance is unreachable; screen needs P/E and market cap too, so it asks Yahoo for them and falls back to the snapshot (no P/E or market cap) when Yahoo fails. Every scan also saves the prices into cache.db (market_snapshots) and the index members for the cap tiers below. When NSE can’t be reached or refuses, StockWise says so on stderr and scans a built-in list instead (the 30 large caps for nifty50 / nifty100, a built-in member list for banknifty and niftyit); niftynext50 has no built-in list and fails with the reason.

Cap tiers (mega, large, mid, small, micro): a badge such as [Large] next to the market cap in quote, deep, analyze and compare (and a Cap column in movers, screen and portfolio), and a cap_tier field in their --json / --csv (unknown when there is no market cap, or no exchange rate for the currency). Indian stocks follow the SEBI/AMFI ranks when the index members are known: NIFTY 100 is large (the top 10, or above ₹5,00,000 Cr, is mega), NIFTY MIDCAP 150 is mid, NIFTY SMALLCAP 250 is small and anything outside NIFTY 500 is micro. Scanning those indexes with --universe saves their members (cap_membership.json in the data directory); until then, and offline, rupee cut-offs decide (large from ₹1,00,000 Cr, mid from ₹33,000 Cr, small from ₹10,000 Cr). Every other market converts the market cap to dollars at the built-in approximate rates (London pence GBp and Japanese yen JPY included): mega from $200B, large from $10B, mid from $2B, small from $300M. A display and filtering aid, not a regulatory classification.

--cap all|mega|large|mid|small|micro keeps one tier in movers, heatmap and screen. With a tier, -m in and -m us scans read fresh (under 30 minutes old) market_snapshots rows from cache.db when cache warm or the worker has stored most of the market’s list, with no request at all; otherwise they scan live. There is no per-sector drilldown command yet, so --cap has nothing to filter there.

Funds & F&O

Guide: Check a stock or fund fast covers funds and SIP returns.

MF periods (-p) are <n>mo, <n>y or max, e.g. 6mo, 3y, 10y. Expiries (-e) are YYYY-MM-DD.

options payoff legs and presets

• A leg is buy|sell [QTY] call|put STRIKE [@PRICE] or buy|sell [QTY] stock [@PRICE]: --leg "buy call 24500" --leg "sell call 24800", --leg "sell 2 put atm-1", --leg "buy stock @2450". STRIKE is a listed strike, or atm, atm+N, atm-N (N listed strikes from the money). An unlisted strike is an error that names the nearest listed ones.
• Prices: the bid/ask mid where both are quoted, else the last trade (flagged ltp — it can be stale), else the leg needs @PRICE. A stock leg is priced at the current underlying value (for an index that stands in for the future).
• Presets around the at-the-money strike, W = --width (default two strike steps; a strike that isn’t listed snaps to the nearest one, with a note): bull-call (buy ATM call, sell ATM+W), bear-put (buy ATM put, sell ATM−W), straddle (buy ATM call and put), strangle (buy ATM−W put and ATM+W call), iron-condor (sell ATM±W, buy ATM±2W wings — a credit), butterfly (buy ATM±W calls, sell two ATM calls), covered-call (stock at spot, sell ATM+W call). --strategy and --leg combine.
• Sizes: every amount is per position — per-unit P/L × lot size × --lots. Lot sizes come from the chain (NSE/BSE order-book quantities are whole lots; US contracts are 100 shares). After hours BSE shows no order book: pass --lot-size, otherwise amounts are per unit and the output says so.
• Probability of profit: the chance the expiry price lands where P/L > 0 if the price is lognormal with the at-the-money IV (or --iv) and risk-neutral drift. It is a model, not a forecast. Costs (brokerage, STT, exchange charges) are not included. StockWise never places orders from this command.

Where the data comes from, and what has none

• NAVs: AMFI’s public NAVAll.txt, every Indian scheme, cached in the data directory (cache/) and re-downloaded after 12 hours. NAV history: api.mfapi.in, a free community mirror of AMFI data, cached the same way. If a download fails, a stale cached copy is used with a warning on stderr.
• Returns are point-to-point NAV returns of the growth option, before tax and exit load. mf sip buys at the first NAV on or after each monthly due date.
• Expense ratios (TER): AMFI’s monthly TER disclosure (amfiindia.com/ter-of-mf-schemes), fetched from the API behind that page as one spreadsheet export for the month (/api/populate-te-rdata-revised?MF_ID=All&Month=MM-YYYY&strCat=-1&strType=-1&excel=true, ~3 MB; the previous month if the current one isn’t published yet). It lists each scheme’s TER per day for the regular and direct plan — from April 2026 split into base expense ratio, brokerage, transaction costs and statutory levies. StockWise keeps each scheme’s latest day, caches the result in cache/amfi_ter.json for a day, and uses a stale copy with a warning if AMFI is unreachable. The disclosure has no AMFI scheme code, so schemes are joined on their name (case and punctuation ignored); a plan the scheme doesn’t offer (AMFI writes 0) has no TER. When TERs can’t be loaded, mf nav/history/screen still print NAVs and returns with a note; --sort ter and --max-ter fail instead. In JSON, ter holds plan, total, the breakdown, both plans’ totals and the disclosure date, as fractions (null when not disclosed). mf overlap shows Yahoo’s expense ratio for the funds it covers.
• Holdings (mf overlap) come from Yahoo Finance, which publishes the top 10 holdings and sector weights for US ETFs and mutual funds (SPY, QQQ, VTI, VFIAX, … with -m us) and for some funds under Yahoo’s 0P… IDs. NSE-listed ETFs such as NIFTYBEES and AMFI scheme codes have no holdings data — StockWise says so instead of guessing. With only the top 10 known, the holdings overlap is a lower bound; sector weights cover the whole fund.
• Option chains: in the Indian market (the default), NSE’s public option-chain API — index options on NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY and NIFTYNXT50 (^NSEI and ^NSEBANK work too) and NSE F&O stocks such as RELIANCE. NSE serves browser sessions only: StockWise loads its option-chain page once for cookies, makes two API calls, and stops with a clear error if NSE refuses — wait a minute and retry. SENSEX, BANKEX and SENSEX50 (also ^BSESN, BSE-BANK.BO) and BSE stock options as SYMBOL.BO come from BSE’s derivatives API, the one behind bseindia.com’s option-chain page: one session, calls 400 ms apart, answers cached for a minute in cache/, no retries. BSE’s site sometimes refuses scripted requests (HTTP 403) — StockWise then says so; wait and retry, or use the website. BSE stock options are rarely traded. With -m us, Yahoo Finance (delayed quotes) for US stocks and ETFs.
• Lot sizes: NSE and BSE quote order-book quantities in whole lots, so the lot is their greatest common divisor across the chain (with at least five quotes; a divisor of 1 counts as unknown); US contracts are 100 shares. options chain shows it and --json has lot_size (null when unknown).
• IV and greeks: Black-Scholes-Merton. IV is solved from the bid/ask mid (else the last trade) at the data timestamp; when that fails, the source’s IV is shown (iv_from in JSON). Risk-free rate defaults to 6.5% (India) / 4.0% (US) — pass --rate with the current T-bill yield. Theta is per calendar day, vega and rho per percentage point. NSE options are European; US equity options are American, so their greeks are the usual European approximation.
• PCR and max pain describe positioning for one expiry; they are not forecasts.

Commodities & bonds

Where the data comes from, and what has none

• Gold and silver spot: Yahoo Finance has no free spot quote, so spot is the COMEX front-month future (GC=F, SI=F, USD per troy ounce) converted at USDINR=X (1 troy ounce = 31.1035 g). It excludes Indian import duty and GST, so jewellers’ rates, IBJA rates and MCX prices are higher.
• MCX futures have no free public feed (MCX’s site is bot-protected and its data is licensed), so StockWise shows COMEX contracts and labels them.
• ETFs are NSE listings via Yahoo, in ₹ per unit; each ETF holds a different amount of metal per unit, so compare % moves, not prices.
• SGB prices come from NSE’s Sovereign Gold Bond list (/api/sovereign-gold-bonds) through the same polite NSE session as the NSE provider, cached for 5 minutes and kept on disk. When NSE refuses (it often blocks scripts), the last saved list is shown with its date; with none, every outstanding tranche is listed without a price — never a guessed one. Tranche details (series, issue date, issue price, maturity = issue + 8 years, early redemption from year 5) are bundled from public tranche tables; 33 of the 44 issue dates were checked against RBI press releases, and RBI moves a maturity a day or two earlier when it falls on a holiday. Their NSE symbols come from a public list and are only shown when NSE’s own list is unavailable. No new SGBs have been issued since February 2024. SGBs you hold are valued from the same list in portfolio and the other holdings commands (see Mutual funds and SGBs).
• Yields: CCIL’s tenor-wise indicative yields, end of day, cached for 6 hours; when CCIL can’t be reached, the five benchmark G-sec yields and T-bill cut-offs on the RBI home page. CCIL and RBI data are for personal, non-commercial use.
• Outstanding G-secs: RBI’s list of Government of India securities, cached for a day.
• Prices of individual G-secs and T-bills are not shown: neither CCIL nor RBI publishes them as a plain page, and NSE’s live debt quotes have no documented API. Enter the price your broker shows into bonds calc.
• Bond math: half-yearly coupons on the maturity date’s day, 30/360 (European) day count, yield compounded half-yearly, simple interest in the final coupon period — the G-sec convention. T-bill yield = (100 − price) / price × 365 / days. Floating-rate bonds (FRBs) are not supported.

Strategies & bots

Guide: Backtest and practise on past markets and Set up alerts and the daemon.

Every backtest form also takes:

Costs, fills, the metrics, walk-forward and the strategy file format are in backtesting.md.

Portfolio

Guide: Import your trades and see true returns and Rebalance to target weights.

Data lives in the directory shown by stockwise doctor.

Lots, sales and tax

Guide: File your Indian capital-gains tax.

Every purchase is a lot: quantity, price, date and where it came from (manual, import:kite, broker:angel, …). portfolio sell takes shares from the oldest lots first — FIFO, as Indian demat accounts and the IRS default work — and keeps each slice as a realized sale.

tax classifies every lot by its own purchase date (long-term after more than 12 months for India and the US) and shows realized gains (sales this tax year) separately from unrealized ones (if you sold everything today). For India it applies the set-off rules: gains and losses of the same kind net first; a short-term loss is set off against short-term gains, then long-term gains; a long-term loss only against long-term gains; then ₹1.25 lakh of LTCG is exempt and STCG is taxed at 20%, LTCG at 12.5%. Losses left over are shown as carry forward. Holdings in another currency (e.g. US shares in tax in) are listed but not included. It is an estimate — it includes the 4% cess but not surcharge or brought-forward losses.

Grandfathering (India): for a long-term lot bought on or before 31 Jan 2018, the cost is the higher of the actual cost and the lower of the 31 Jan 2018 price and the sale price (Section 112A). tax in, tax export in, tax advance and harvest all use it. The price is the day’s highest for a listed share (Yahoo) and the NAV for a mutual fund with an AMFI code; it is looked up once and cached. A lot whose price cannot be found keeps its actual cost, and tax export in says so in its notes. Prices are split-adjusted, so a lot recorded before a split or bonus must carry its adjusted cost.

Same-day trades (India): a buy and sell of one share on the same day net against each other first, in a tradebook import and in trade sync fills. The matched quantity is recorded as an intraday sale (priced at that day’s average buy and sell) and the older lots are left alone. tax in, tax export in and tax advance keep intraday results out of Sec. 111A/112A and show them separately as speculative business income at your slab rate (losses can only be set off against speculative gains). Without a date-time column a delivery buy and sell of held shares on one day cannot be told apart from intraday.

Mutual funds and SGBs in tax in: equity-oriented funds — by their AMFI category: equity schemes (ELSS included), arbitrage, aggressive hybrid and equity savings funds, and Nifty/Sensex index funds — are counted like listed shares and named under the estimate. Debt and other funds (taxed at your slab rate for units bought from 1 Apr 2023, at 12.5% after 24 months for older units), funds not found in AMFI’s file, and SGBs (tax-free when RBI redeems them; sold on the exchange, 12.5% after 12 months without the ₹1.25 lakh exemption) are left out and listed with the rule that applies (other_rules in --json). So are exchange-traded gold, silver and international ETFs (12.5% after 12 months with no exemption, slab rate before) and liquid and debt ETFs (slab rate at any holding period). StockWise knows them from a built-in list of NSE symbols (GOLDBEES, SILVERBEES, LIQUIDBEES, MON100, Bharat Bond EBBETF…, …) and from …BEES names that say gold, silver, liquid, gilt, Nasdaq or Hang Seng; an ETF it does not know is counted like a listed share, as are equity ETFs such as NIFTYBEES. harvest skips the same holdings (they are listed under “Not checked”) and tax export in and tax advance leave their sales out.

tax in, harvest, tax export in and tax advance share one rule for what counts as a listed share or an equity-oriented fund (Sec. 111A/112A); the other three load AMFI’s file to read the category of any fund you sold. Crypto (such as BTC-INR) is never in 111A/112A: it is taxed at a flat 30% under Sec. 115BBH with no set-off of losses, tax export in lists it under virtual_digital_assets, and the other commands name it among the holdings they leave out.

Mutual funds and SGBs

Guide: Import your trades shows how to load a CAS.

Holdings that Yahoo Finance doesn’t quote are priced by StockWise itself, the same way in portfolio, dashboard, tui, serve, wealth, rebalance, harvest, tax, portfolio sell and report portfolio:

• Mutual funds — MF:<AMFI code> (portfolio add MF:120503 10 50) or MF:<ISIN> (the growth/payout or IDCW-reinvestment ISIN, as import cas and Groww imports store them) — at the latest NAV in AMFI’s NAVAll.txt (cached 12 hours). NAVs are end of day: the table says “NAV as of <date>” for each fund, and --json rows carry name, price_source: "amfi_nav" and nav_date. A code or ISIN that isn’t in AMFI’s file, or a scheme AMFI lists without a NAV, stays N/A with a note (find codes with mf search) — never 0. A scheme whose last NAV is over a month older than the file is flagged as possibly matured. MF: symbols are never sent to Yahoo, and watch/alert see the NAV too.
• Sovereign Gold Bonds — the NSE symbol (SGBNOV26, stored as SGBNOV26.NS) or the tranche’s ISIN — at the last price in NSE’s SGB list (price_source: "nse_sgb"). When NSE refuses or shows no trade, the value is one gram of gold at the international spot price per unit, labelled “estimated from gold spot” (gold_estimate). Values leave out the 2.5% yearly interest, which is paid to your bank every six months.

Older versions stored portfolio add MF:120503 as MF:120503.NS (and watch add / alert add likewise); those symbols are repaired when the files load.

Passive income and dividend calendar

stockwise income (or stockwise portfolio income) is a 12-month trailing and projected dividend, coupon and passive-income engine for dividend-growth investors, retirees, and bond/SGB holders:

• Monthly Cashflow Schedule: Shows month-by-month cash flows across trailing 12 months (received dividends recorded in portfolio.dividends) and forward N months (default 12), with a visual terminal bar chart and --json/--csv serialization.
• Yield on Cost (YoC): Calculates per-holding and per-lot Yield-on-Cost (YoC = Annual Dividend / Original Lot Cost), comparing it against current market yield to reveal dividend-growth compounding over time.
• TDS and Withholding Tax: Automatically computes withholding tax (flat 10% TDS for Indian dividends and 25% WHT for US foreign dividends; 0% assumed for other currencies) to report net spendable income.
• Sovereign Gold Bonds & Fixed Income: Models half-yearly 2.5% p.a. SGB coupons on issue nominal values across maturity cycles.
• Payout Safety & Sustainability: Evaluates earnings payout ratios, diagnosing distributions as SAFE (< 60%), CAUTION (60–85%), or WARNING (> 85% or negative earnings).
• Upcoming Radar (stockwise income upcoming): Checks upcoming ex-dividend and payment dates for holdings and watchlists, showing held share counts and calendar details.

Harvest

Guide: File your Indian capital-gains tax.

harvest lists what you could sell to book a loss, and which long-term winners you could sell to use this year’s unused ₹1.25 lakh LTCG exemption. For India it follows FIFO, as a demat account does: to reach a losing lot you must sell the older lots first, so the row shows that whole sale (shares, and the net st_pnl and lt_pnl it books). If selling up to a losing lot books a net gain in all, the holding is not offered as a loss; fifo_blocked (and a note on screen) says how many shares you would sell and what the sale books. For the US you can choose lots, so only the losing lots are offered.

estimated_tax_saved is how much the tax estimate falls when the loss is booked on top of this year’s realized gains, so set-off order, the exemption and cess are counted; a loss with nothing to offset saves 0 and is carried forward. The remaining exemption is shared: each winner takes its part of it, biggest first, and the saving counts only that part. Holdings in another currency (US shares for in) are listed under other_currency and not counted; holdings taxed under other rules (crypto, debt funds, SGBs, gold and similar ETFs) under other_rules.

Tax export

Guide: File your Indian capital-gains tax.

tax export in writes the realized sales of an Indian financial year as a spreadsheet laid out for ITR Schedule CG and Schedule 112A: one row per lot sold with section (111A short-term, 112A long-term), ISIN, scrip, quantity, sale date and value, purchase date and cost, days held and the gain, then a summary block — gains and losses of each kind, the short-term loss set off against LTCG, the ₹1.25 lakh LTCG exemption, taxable STCG/LTCG, the estimated tax and losses to carry forward. ISINs come from NSE’s equity list (shares) and AMFI’s NAV file (funds imported from a CAS), both cached for 12 hours; one that can’t be found is left blank and named. tax export us writes a Form 8949 worksheet instead: Part I (held one year or less) and Part II rows with description, dates (MM/DD/YYYY), proceeds, cost basis and gain, then the Schedule D totals, the $3,000 loss deduction and the carryover.

stockwise tax export in --fy 2025-26 --out cg-2025-26.csv   # file + summary on screen
stockwise tax export in --fy AY2026-27 > cg.csv            # same year, by assessment year
stockwise tax export us --fy 2025 --json | jq '.summary'

--fy takes 2025-26, 2025-2026 or AY2026-27 (India) and 2025 (US); the default is the current tax year. Without --out the CSV (or --json) goes to stdout. It is an estimate — verify it with your broker’s tax P&L: it only knows sales StockWise recorded (portfolio sell, tradebook and CAS imports) at their recorded prices, without brokerage or STT. Shares bought on or before 31 Jan 2018 are flagged — Schedule 112A lets you use that day’s fair market value as the cost, which StockWise doesn’t apply; sales in another currency (US shares for in) and crypto (taxed at 30% under section 115BBH, Schedule VDA) are listed but left out, and so are debt and other funds and SGBs.

The rates follow the sale date: sales before 23 Jul 2024 are taxed at 15% (STCG) and 10% (LTCG), later ones at 20% and 12.5%. The LTCG exemption is ₹1 lakh up to FY 2023-24 and ₹1.25 lakh from FY 2024-25, for the whole of that year. In a mixed FY 2024-25, losses and the exemption are used against the higher-rate gains first (the lowest tax; the Act does not prescribe an order), and the summary shows how much of the taxable gain came from before 23 Jul 2024.

Advance tax (India)

Guide: File your Indian capital-gains tax.

Under Section 208 and 211 of the Indian Income-tax Act, any taxpayer whose estimated tax liability for the financial year is ₹10,000 or more must pay advance tax in four quarterly instalments:

• By 15 June: At least 15% of estimated tax
• By 15 September: At least 45% of estimated tax
• By 15 December: At least 75% of estimated tax
• By 15 March: 100% of estimated tax (capital gains realized between 16 and 31 March are payable by 31 March)

Because capital gains cannot always be predicted in advance, the proviso to Section 234C(1) specifies that deferment interest is not levied if the shortfall is due to capital gains realized after an instalment date, provided the remaining tax is paid in subsequent instalments. stockwise tax advance groups realized sales into the four statutory quarterly cut-offs and calculates cumulative set-offs under Indian equity rules, by sale date: from 23 July 2024 STCG @ 20% and LTCG @ 12.5%, before it 15% and 10%; the LTCG exemption is ₹1.25L (₹1L up to FY 2023-24):

stockwise tax advance                             # current FY advance tax schedule
stockwise tax advance --fy 2025-26                # specific financial year
stockwise tax advance --paid 2025-06-14:3000 --paid 2026-01-10:17800   # dated payments: exact Section 234C interest
stockwise tax advance --paid 25000                # a total with no date: assumed paid on time
stockwise tax advance --json                      # programmatic JSON output

• Section 208 Check: Automatically flags whether advance tax is mandatory (total liability ≥ ₹10,000) or exempt.
• Status: A quarter is Paid only when payments dated on or before its due date cover the minimum. With no --paid, a quarter past its due date is Overdue, because StockWise has no record of any payment.
• Section 234C Deferment Interest: Section 234C looks at what was paid by each due date, so pass each payment with its date (--paid 2025-06-14:3000, repeated). It then charges 1% a month (3% for Q1–Q3, 1% for Q4) on each shortfall, rounded down to ₹100, when the payments by that date are below the safe-harbour level (12% in Q1, 36% in Q2, 75% in Q3, 100% in Q4). For Q4 the requirement on 15 March is the tax on gains up to 15 March; tax on gains after it carries no interest when paid by 31 March (the proviso). A payment dated before the financial year began is ignored (it was made for an earlier year) and the output says so. A payment without a date is assumed to have been made before every due date, which can understate the interest.
• Cess: The tax and the instalments include the 4% health and education cess; surcharge is left out.
• Section 234B Note: Flags potential Section 234B liability if assessed after 31 March and cumulative advance tax paid is below 90% of total liability.

Benchmark and attribution

Guide: Import your trades and see true returns.

portfolio benchmark rebuilds what you held at each close of the period from your lots and sales (in today’s share count, so splits don’t break the history), and compares the portfolio’s time-weighted return with an index over the same days.

stockwise portfolio benchmark                  # vs NIFTY 50 over 1 year (S&P 500 with -m us)
stockwise portfolio benchmark SENSEX -p 2y
stockwise portfolio benchmark SP500 --base inr # S&P 500 converted to rupees day by day
stockwise portfolio benchmark NIFTYBEES -p 6mo --csv

• Benchmarks by name: NIFTY, SENSEX, BANKNIFTY, NIFTY500, SP500, NASDAQ, NASDAQ100, DOW; or an index symbol (^NSEI) or any ticker. Periods: 1mo, 3mo, 6mo, ytd, 1y (default), 2y, 5y, 10y, max.
• The period starts at the first close where something was held. Returns come from daily closes: a purchase or sale counts at that day’s close, so the figure measures the holdings, not your fill prices. Dividends are left out on both sides (NIFTY 50 and the S&P 500 on Yahoo are price indices).
• Alpha (annualized, risk-free rate 0), beta, tracking error, information ratio and correlation come from the daily returns and need 20 of them.
• Attribution: each holding’s average weight, its return while held, its contribution to the portfolio return and to the return over the index, in percentage points (linked with Carino’s method, so they add up exactly to the totals); the same by sector, from Yahoo’s asset profile (“Unknown” when Yahoo has none, “Mutual fund” for funds imported from a CAS, valued from their NAV history).
• Holdings in another currency are converted into the base currency (--base, else the holdings’ one currency, else the market’s) at each day’s exchange rate; an index in another currency is converted too.
• Flagged under Partial history: holdings with no price history (left out), days held before a holding’s price history starts (left out of those days), and purchases inside the period with an estimated date (the shares may have been held earlier than the history shows).

Public Market Equivalent (Index Twin)

stockwise portfolio pme mirrors your exact tradebook cash flows into a passive benchmark index or ETF (e.g. SPY, VOO, VWCE, NIFTY, NIFTYBEES) on their matching trade dates:

• Every buy of $X on date D buys $X worth of the benchmark twin.
• Every sell on date D distributes the equivalent proceeds from the benchmark twin.
• Recorded dividends are distributed from the twin on matching dates.

It answers: “Did my active trading and stock picking actually beat investing in a passive index on the exact same dates?”

Metrics reported:

• Index Twin Value: Current value of the synthetic benchmark portfolio.
• Value Added / Lost: Terminal portfolio value minus Index Twin value (in exact currency units: +$ / +₹).
• Kaplan-Schoar PME (KS-PME): Compounded future value of distributions + terminal portfolio value over future value of investments (> 1.000 indicates active outperformance; 1.000 is parity).
• Direct Alpha (Gredil, Griffiths, Stucke 2014): Annualized IRR of benchmark-discounted cash flows, yielding 0.00% on parity.
• Holding Breakdown: Direct Alpha and Value Added breakdown for each held asset.

XIRR (in portfolio and portfolio lots) is the money-weighted annual return from each lot’s purchase, each sale, recorded dividends and today’s value. It shows — with under 30 days of history. The portfolio figure includes closed positions and converts other currencies at today’s rate.

Lots marked * have an estimated date: holdings from before lot tracking (dated when they were added to StockWise) or imported from a file without dates. Fix one with portfolio lots SYMBOL --lot N --date YYYY-MM-DD.

Corporate actions. portfolio actions lists splits, bonus issues (Yahoo reports a 1:1 bonus as a 2:1 split) and dividends since each holding’s first purchase. Nothing changes until --apply, which multiplies the quantity and divides the price of lots bought before the split (cost and date unchanged) and records each dividend on the shares held at its ex-date. Each lot remembers the splits applied to it, so running it again is a no-op. Indian tax treats bonus shares as bought at zero cost on the allotment date — check bonus lots against your tax statement.

Imports. A holdings export (Kite, INDmoney) has no purchase dates: existing lots are kept and only the quantity is matched — more shares add a lot dated today, fewer shares come out of the oldest lots (not recorded as a sale). trade holdings syncs the same way. When the snapshot has more shares and a split or bonus isn’t applied to your lots yet, that holding is skipped until you run portfolio actions --apply (otherwise the bonus shares would be counted twice). A file with a date column (Date, Purchase Date, Buy Date, trade_date, …) is a list of lots: each symbol’s lots are rebuilt from it. With a buy/sell column (trade_type, Type, Side) it is a tradebook — such as Zerodha Console’s — sells come out FIFO as realized sales, and splits and bonuses are applied as they happened (this needs a network connection). StockWise keeps the trades of each tradebook import and merges the next file with them, so several yearly tradebooks (Console allows 365 days per download) can be imported one after another, in any order, and re-importing a file changes nothing. A symbol is left unchanged when its sells have no earlier buy yet (the trades are kept; import the earlier tradebook to finish), or when it already has lots or sales from elsewhere (manual entries, another import, or a tradebook imported before StockWise kept trades) — --replace rebuilds it from this file alone anyway. A file of dated buys only (no buy/sell column) is the symbol’s whole list of lots and replaces them. Dates may be YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY (MM/DD/YYYY with -m us) or 15-Mar-2024; a file with an unrecognized date is refused.

Mergers. A dated row (or portfolio add --date) for a ticker that was merged away is restated in the acquirer’s shares, keeping the date and the total cost: HDFC up to the 13 Jul 2023 record date becomes HDFCBANK at 42 shares for every 25, and Mindtree up to 24 Nov 2022 becomes LTIM at 73 for every 100 (quantity × ratio, price ÷ ratio). Rows without a date, and plain renames such as ZOMATO → ETERNAL, are mapped to the new name only. Fractional shares from the swap are kept as a fraction (the cash paid for them is not recorded). Existing lots already imported under the new name are not corrected — re-import the tradebook with --replace.

Accounts. Each lot and sale carries the demat account it came from, named after the broker: import kite and trade … --broker zerodha are zerodha, import groww is groww, and so on. A holdings file or tradebook only matches, rebuilds or sells the lots of its own account, so the same stock held at two brokers is two sets of lots in one holding (portfolio lots shows the account). Lots entered by hand or saved by an older version, with no account of their own, count as the account of their source, or — for manual lots — join the first broker that syncs the symbol. Totals and tax span all accounts. portfolio sell works on the whole holding, oldest lot first.

Groww, Upstox, CAS. Groww and Upstox exports are snapshots (quantity sync, like Kite). A CAS whose transactions cover a fund’s whole balance rebuilds it as dated lots, with redemptions as realized sales; otherwise only the quantity is synced. See brokers.md.

Upgrading. Portfolios saved before lot tracking are upgraded on first load: each holding becomes one lot dated when it was added, and the original file is kept once as portfolio.json.bak.

Planning

--from-portfolio and --holdings value the portfolio (or the named holdings, such as MF:122639 or NIFTYBEES) at live prices, or at cost when offline, and use that as existing savings; they replace --savings. Taxes and exit loads are estimates, not advice; --tax defaults to debt up to 60 months and equity beyond, with a 1% exit load on equity lots held under 12 months in India.

stockwise goal sip --target 1cr --years 15                  # ₹19,819 a month at 12%
stockwise goal sip --target 1cr --years 15 --step-up 10     # ₹11,516 a month, rising 10% a year
stockwise goal sip --target 10L --months 9                  # short goal: 6.75% baseline, month-by-month table
stockwise goal sip --target 50L --by 2031-06 --inflation 6 --from-portfolio
stockwise goal retire --monthly-expense 80k --years-to-retire 20 --years-in-retirement 30
stockwise goal education --cost 25L --years 10 --savings 3L
stockwise goal add house --target 50L --by 2031-06 --holdings NIFTYBEES
stockwise goal swp --corpus 1cr --withdrawal 50k
stockwise goal prepay --principal 50L --loan-rate 9 --remaining-months 240 --extra 10k

Amounts take Indian units — 50k, 25L / 25 lakh, 1cr / 1.5 crore, 2,50,000 — and results print in lakhs and crores (dollars with -m us). The math, as Indian SIP calculators do it: the monthly rate is the annual return ÷ 12 and SIPs are paid at the start of each month; a step-up raises the SIP once a year; --savings already invested grows at the same return and lowers the SIP. In retirement the expense rises with inflation once a year and the corpus earns --return-post until it runs out at the end of the last year. Returns are assumptions, not promises.

AI assistants

Guide: Use StockWise from Claude or Cursor.

Both use the same read-only tools (quotes, history, technicals, risk, scorecards, insights, events, mutual funds, option chains, IPOs, screens, backtests, your portfolio, lots, tax estimate, advance tax, harvest and rebalance plans, calendar, goals, watchlist and alerts). See ai.md.

stockwise ask "how is my portfolio doing?"
claude mcp add stockwise -- stockwise mcp     # Claude Code
stockwise mcp --list-tools | jq '.[].name'

Interfaces

Both are read-only and share the data layer with the commands above, so they show the same numbers. They are on by default and can be left out of a build with --no-default-features (cargo features tui and server).

Live trading

See brokers.md. Orders are previewed and need a typed yes. Every trade command takes --broker angel|zerodha|upstox|dhan|fyers (default angel, or STOCKWISE_BROKER); all but angel are experimental — untested against a live account.

Setup

Scripting with --json and --csv

Guide: Script it with JSON, CSV and jq.

stockwise portfolio --json | jq '.totals'
stockwise portfolio --json | jq -r '.holdings | sort_by(.pnl_percent) | .[:3][] | "\(.symbol) \(.pnl_percent)%"'
stockwise portfolio --csv > portfolio.csv                 # open in a spreadsheet
stockwise history TCS -p 1y --csv > tcs.csv               # every daily bar
stockwise alert check --json | jq -r '.[] | select(.status == "triggered") | .symbol'
stockwise screen dividend --csv | column -s, -t
stockwise tax in --json | jq '.realized.total_tax'
stockwise tax export in --fy 2025-26 --json | jq '.summary.taxable_ltcg'
stockwise portfolio benchmark --json | jq '{portfolio_return, benchmark_return, beta: .metrics.beta}'
stockwise goal sip --target 1cr --years 15 --json | jq '.monthly_sip'
for s in rsi macd sma bb vwap mr; do
  stockwise backtest INFY -s "$s" --json | jq -r '"\(.strategy)\t\(.total_return_percent)"'
done
for s in $(stockwise watch --json | jq -r '.[].symbol'); do
  stockwise technical "$s" --json | jq -r '"\(.symbol)\t\(.rsi_14)\t\(.bias.verdict)"'
done
stockwise quote TCS INFY --json | jq '.[] | {symbol, regularMarketPrice}'
stockwise markets --json | jq '.[] | select(.change_percent < -1)'
stockwise mf sip 122639 5000 -p 3y --json | jq '{invested, value, xirr}'
stockwise options chain NIFTY -n 2 --json | jq '.rows[] | {strike, delta: .call.greeks.delta}'
stockwise options payoff NIFTY -s straddle --json | jq '{breakevens, pop, max_loss}'
stockwise mf screen flexi cap -s ter --json | jq '.[] | {name, ter, return_3y}'

Rules

• stdout holds only the JSON or CSV; errors go to stderr with exit code 1, so set -e and || work. --json and --csv can’t be combined.
• Empty states are not errors: an empty portfolio prints {"holdings": [], ...} or a CSV header with no rows.
• Keys are stable snake_case. The exceptions are quote --json and search --json, which pass Yahoo’s own fields through (camelCase, unchanged since 0.3); their --csv uses snake_case columns.
• A value that isn’t available is null in JSON and an empty cell in CSV — never 0. A holding without a live price keeps its row but is left out of totals and listed in unpriced.
• Fields ending in _percent are percentages (12.5 = 12.5%). dividend_yield in quote, compare and screen is a fraction as Yahoo reports it (0.012 = 1.2%). Prices are as Yahoo returns them; derived money values are rounded to 2 decimals, indicators to 4.
• Dates are YYYY-MM-DD; history bar times are RFC 3339 in UTC.
• CSV follows RFC 4180 quoting (fields with a comma, quote or newline are quoted, quotes doubled), starts with a header row, and ends lines with \n. CSV columns are the same names as the JSON row keys.
• The --ai section is never part of JSON or CSV output.
• mf and options have their own --json (no --csv); fractions there are decimals (0.1234 = 12.34%), and missing values are null, never 0.
• options payoff --json is {symbol, source, underlying, currency, as_of, expiry, days_to_expiry, strategy, width, lot_size, lot_size_from, lots, multiplier, rate, div_yield, legs: [{side, qty, instrument, strike, price, price_from, iv, iv_from, delta}], net_premium, net_premium_total, premium_type, max_profit, max_loss, breakevens, profit_ranges: [{from, to}], pop, pop_iv, pop_iv_from, greeks: {delta, gamma, theta, vega, rho}, notes, curve: [{price, expiry, today}]}. net_premium and leg prices are per unit (positive = debit); money totals, greeks and the curve are for the whole position (× multiplier = lot size × lots). max_profit/max_loss are null when unlimited; max_loss is negative; to: null means “and above”. price_from is mid, ltp, manual or spot. Money values, prices and breakevens are rounded to 2 decimals.

Shapes ([...] is an array; row is described next to it)

Alert conditions

Guide: Set up alerts and the daemon.

stockwise alert add <SYMBOL> <CONDITION> <NUMBER>:

Technical conditions read daily bars (one chart request per symbol per check), with the last bar updated to the live quote, so a cross or breakout fires on the session it happens in. A symbol with too little history reads no_data and never triggers. alert watch notifies each alert once until it re-arms, at most once per trading day.

stockwise alert add INFY rsi-below 30
stockwise alert add INFY rsi-above 70 --period 9
stockwise alert add RELIANCE cross-above-sma 200
stockwise alert add AAPL -m us breakout-high 52
stockwise alert add HDFCBANK change-below 3
stockwise alert add TCS volume-spike 2
stockwise alert add TCS results-in 7

Alerts saved by earlier versions keep working unchanged.

Results and corporate calendar

Guide: Check a stock or fund fast and Set up alerts and the daemon.

stockwise calendar lists what is coming up for your holdings and watchlist (--holdings or --watchlist for one of them, or name symbols), over the next 30 days (--days 1-365):

• For an Indian stock, NSE’s filed results date replaces Yahoo’s estimate, and NSE’s ex-dividend date replaces Yahoo’s.
• Upcoming splits come from NSE only; Yahoo lists splits after they happen, so US splits don’t appear in advance.
• BSE filings are not read; a .BO symbol uses the same company’s NSE filings.
• NSE’s API serves browser sessions. StockWise opens one session per run, waits a second between requests and caches every answer for a day in calendar_cache.json (failures for an hour). When NSE refuses, the table says so and shows Yahoo’s dates.
• Crypto, FX and indices have no calendar and are skipped.

stockwise calendar
stockwise calendar --holdings --days 14
stockwise calendar TCS INFY
stockwise calendar AAPL MSFT -m us --json

Configuration file

Everything works without one. To set your own defaults:

stockwise config init     # write a commented template
stockwise config path     # where it is
stockwise config show     # every effective setting and where it came from

The file is config.toml in your platform’s config directory — ~/Library/Application Support/stockwise/ on macOS, ~/.config/stockwise/ on Linux ($XDG_CONFIG_HOME), %APPDATA%\stockwise\ on Windows — or the file named by STOCKWISE_CONFIG.

market = "us"                       # in | us | crypto | fx | commodity | uk | de | jp | hk | sg | ca | au
lang = "hi"                         # en | hi
quote_currency = "inr"              # BTC → BTC-INR with -m crypto
portfolio = "long-term"             # a named portfolio
ai = false
ai_provider = "ollama"              # ollama | openai | anthropic | gemini
model = "llama3.1:8b"
ollama_host = "http://gpu-box:11434"
data_provider = "yahoo"             # yahoo | alphavantage | massive | twelvedata
redis_url = "off"
home = "~/Dropbox/stockwise"        # data directory; ~ is your home

[periods]                           # default -p per command
technical = "6mo"
backtest = "5y"
sip = "10y"

[notify]                            # STOCKWISE_* notification variables, lower-case, no prefix
telegram_chat_id = "123456789"
smtp_host = "smtp.gmail.com"
email_to = "me@example.com"

[periods] accepts the commands that take -p: deep, technical, history, risk, patterns, support, fibs, volume, gaps, stoploss, forecast, options, backtest, sip. --help shows the default from your file, e.g. [default: 6mo].

A file that doesn’t parse — an unknown key, a wrong type, an unknown market or period — stops every command with exit code 1 and an error naming the file and the key. config, doctor and completions still run, so you can inspect it or replace it with stockwise config init --force.

API keys (OPENAI_API_KEY, the data provider’s key, …) and STOCKWISE_API_TOKEN are read from the environment only. Notification tokens and passwords may go in [notify]; if they do, keep the file private (chmod 600) — config show and doctor warn when other users can read it.

stockwise serve answers with the same shapes over HTTP — see server.md.