@pungoyal/kite-cli 0.2.1 → 0.3.0

package/README.md

@@ -78,6 +78,19 @@ kite authorise                   # authorise demat holdings for selling
 
 If a sell order fails with exit code 12 ("needs authorisation at depository"), run `kite authorise` — it requests a CDSL authorisation and opens the browser page that completes it. Pass specific ISINs to authorise only those instruments.
 
+### Mutual funds
+
+```bash
+kite mf holdings                 # your MF holdings with P&L
+kite mf orders                   # MF orders from the last 7 days
+kite mf sips                     # your active SIPs
+```
+
+Mutual funds are read-only over Kite Connect — placing MF orders and managing
+SIPs is not available via the API (a purchase needs a bank debit the API can't
+authorise). `mf orders` only reaches back 7 days, so an empty list doesn't mean
+you have no MF history.
+
 ### Market data
 
 ```bash
@@ -160,12 +173,48 @@ kite alerts create NSE:INFY --operator below --value 1400 \
   --type ato --side BUY --quantity 10 --order-type LIMIT --price 1400
 ```
 
+The order an ATO fires need not be on the instrument you watch, and it can be a
+**basket of several orders** across different instruments. Use `--order` — one
+per leg, repeatable — where each leg is
+`EXCHANGE:SYMBOL:SIDE:QTY` followed by optional attributes (an order type,
+product, validity, a bare price, or `trigger=<n>`), in any order:
+
+```bash
+# Watch INDIGO's spot price; when it drops, buy the future and trim a hedge.
+kite alerts create NSE:INDIGO --operator below --value 3850 --type ato \
+  --order 'NFO:INDIGO25AUGFUT:BUY:150:MARKET:NRML' \
+  --order 'NSE:RELIANCE:SELL:10:LIMIT:2900'
+```
+
+The value cap sums every leg and fails closed if any one cannot be priced. The
+`--order` form and the single-order flags above (`--side`/`--quantity`/…) are
+mutually exclusive.
+
 `--operator` accepts the raw symbols (`>=`, `<=`, `>`, `<`, `==`) or the aliases
 `above`, `below`, `ge`, `le`, `gt`, `lt`, `eq`. Compare against another instrument
 instead of a constant with `--rhs-instrument EXCHANGE:SYMBOL`.
 
 Add `--dry-run` to any of these to see exactly what would be sent, without sending it.
 
+### Margins & charges
+
+Work out what an order or a basket would cost before placing it. Nothing is
+sent to the exchange — these only call Kite's calculators:
+
+```bash
+kite margins order NFO:NIFTY25AUGFUT:BUY:75:NRML       # required margin, per order
+kite margins basket NFO:NIFTY25AUGFUT:BUY:75:NRML \
+  NFO:NIFTY25AUGFUT:SELL:75:NRML                        # net margin, with hedge benefit
+kite margins charges NSE:INFY:BUY:10:1500              # brokerage + taxes (contract note)
+```
+
+Each order is `EXCHANGE:SYMBOL:SIDE:QTY` followed by optional attributes (an
+order type, product, variety, a bare price, or `trigger=<n>`), in any order;
+product defaults to CNC and variety to regular. `margins basket` accepts
+`--no-consider-positions` to ignore your existing positions when netting.
+`margins charges` needs a real price (the execution price), since charges are a
+percentage of quantity × price.
+
 ### Scripting
 
 Every command supports `--json`, writes data to stdout and everything else to stderr, and returns a meaningful exit code.

package/dist/commands/alerts.d.ts

@@ -1,3 +1,4 @@
+import { type OrderType, type Product, type TransactionType, type Validity } from '../core/api.js';
 import type { CommandFactory } from './types.js';
 /**
  * Price alerts.
@@ -10,3 +11,30 @@ import type { CommandFactory } from './types.js';
  *            disguise, so it gets the same safety treatment as `orders place`.
  */
 export declare const alertCommands: CommandFactory;
+/** One order in an ATO basket, fully resolved and validated. */
+export interface AtoLeg {
+    exchange: string;
+    tradingsymbol: string;
+    side: TransactionType;
+    quantity: number;
+    orderType: OrderType;
+    price: number | undefined;
+    triggerPrice: number | undefined;
+    product: Product;
+    validity: Validity;
+}
+/**
+ * Parse one `--order` spec into a leg.
+ *
+ * Grammar: `EXCHANGE:SYMBOL:SIDE:QTY` followed by any number of optional
+ * attribute tokens. Each attribute is either a bare vocabulary word (an order
+ * type, a product, a validity, or a number read as the price) or an explicit
+ * `key=value` (type, product, validity, price, trigger).
+ *
+ * Fails closed (invariant #1): every trailing token must be classified exactly
+ * once. An unrecognised token, a duplicated field, or an empty field rejects the
+ * whole spec — a silently mis-parsed leg is a real order with the wrong
+ * parameters. A trigger price is only ever set explicitly (`trigger=<n>`), never
+ * positionally, so an SL order can't be misread from two bare numbers.
+ */
+export declare function parseOrderSpec(spec: string): AtoLeg;

package/dist/commands/alerts.js

@@ -35,14 +35,24 @@ export const alertCommands = (program, run) => {
         .option('--name <name>', 'Alert name (defaults to a description of the condition)')
         .option('--attribute <attribute>', 'Attribute to compare', ALERT_DEFAULT_ATTRIBUTE)
         .option('--type <type>', 'simple or ato (ato places an order when it fires)', 'simple')
-        // ATO order flags — mirror `orders place`. Only read when --type ato.
-        .option('-s, --side <side>', 'ATO: order side, BUY or SELL')
-        .option('-q, --quantity <n>', 'ATO: order quantity')
-        .option('--order-type <type>', `ATO: order type (${ORDER_TYPES.join(', ')})`, 'MARKET')
-        .option('-p, --price <price>', 'ATO: limit price (for LIMIT/SL orders)')
-        .option('--trigger-price <price>', 'ATO: trigger price (for SL/SL-M orders)')
-        .option('--product <product>', `ATO: product (${PRODUCTS.join(', ')})`, 'CNC')
-        .option('--validity <validity>', `ATO: validity (${VALIDITIES.join(', ')})`, 'DAY')
+        // ATO basket. Two shapes, never mixed:
+        //   --order  — a full basket leg, repeatable, each on its own instrument
+        //              (independent of the watched one). This is how you place
+        //              orders on a different symbol, or several at once.
+        //   the flags below — a shorthand for a single order on the *watched*
+        //              instrument, kept for back-compat.
+        .option('--order <spec>', 'ATO: a basket leg as EXCHANGE:SYMBOL:SIDE:QTY[:TYPE][:PRICE][:PRODUCT][:VALIDITY][:trigger=<n>]. Repeatable.', collect, [])
+        // ATO single-order flags — a shorthand for one order on the watched
+        // instrument. Read only when --type ato and no --order is given; combining
+        // them with --order is a hard error, so they carry NO defaults here (a
+        // default would be invisible to that guard and silently ignored).
+        .option('-s, --side <side>', 'ATO: order side, BUY or SELL (single-order form)')
+        .option('-q, --quantity <n>', 'ATO: order quantity (single-order form)')
+        .option('--order-type <type>', `ATO: order type, default MARKET (${ORDER_TYPES.join(', ')}) (single-order form)`)
+        .option('-p, --price <price>', 'ATO: limit price (single-order form; for LIMIT/SL)')
+        .option('--trigger-price <price>', 'ATO: trigger price (single-order form; for SL/SL-M)')
+        .option('--product <product>', `ATO: product, default CNC (${PRODUCTS.join(', ')}) (single-order form)`)
+        .option('--validity <validity>', `ATO: validity, default DAY (${VALIDITIES.join(', ')}) (single-order form)`)
         .action(run(createAlert));
     alerts
         .command('modify')
@@ -183,13 +193,16 @@ const CreateOptionsSchema = z.object({
     name: z.string().optional(),
     attribute: z.string().default(ALERT_DEFAULT_ATTRIBUTE),
     type: z.string().default('simple'),
+    order: z.array(z.string()).default([]),
     side: z.string().optional(),
     quantity: z.coerce.number().int().positive().optional(),
-    orderType: z.string().default('MARKET'),
+    // No defaults: these are single-order-form flags, and defaulting them would
+    // make them undetectable to the guard that forbids mixing them with --order.
+    orderType: z.string().optional(),
     price: z.coerce.number().positive().optional(),
     triggerPrice: z.coerce.number().positive().optional(),
-    product: z.string().default('CNC'),
-    validity: z.string().default('DAY'),
+    product: z.string().optional(),
+    validity: z.string().optional(),
 });
 async function createAlert(ctx, rawOpts, command) {
     ctx.requireSession();
@@ -244,7 +257,8 @@ async function createAlert(ctx, rawOpts, command) {
         // ATO creation IS order placement: it needs the kill switch, the value cap,
         // and the full escalating confirmation, exactly like `orders place`.
         assertTradingEnabled(ctx);
-        const { basket, notionalValue, orderDetails } = await buildAtoBasket(ctx, opts, lhs);
+        const legs = resolveAtoLegs(opts, lhs);
+        const { basket, notionalValue, orderDetails } = await buildAtoBasket(ctx, legs);
         params.basket = basket;
         await confirmAction(ctx, {
             action: `Create ATO alert on ${lhsKey}`,
@@ -276,24 +290,40 @@ async function createAlert(ctx, rawOpts, command) {
     }
 }
 /**
- * Build the single-order basket for an ATO alert from the order flags, and
- * price it for the value cap.
- *
- * Returns the notional as UNDEFINED when it cannot be priced, so the safety
- * layer fails closed (escalates to a typed challenge) rather than treating an
- * unknown value as small.
+ * Resolve the ATO basket's legs from the parsed options. The `--order` form
+ * (one leg per flag, each on its own instrument) and the single-order flag form
+ * are mutually exclusive: mixing them is a hard error rather than a silent
+ * precedence rule, because the two describe different orders and a guessed
+ * winner would place the wrong one.
  */
-async function buildAtoBasket(ctx, opts, lhs) {
+function resolveAtoLegs(opts, lhs) {
+    if (opts.order.length > 0) {
+        const usedSingleFlags = opts.side !== undefined ||
+            opts.quantity !== undefined ||
+            opts.price !== undefined ||
+            opts.triggerPrice !== undefined ||
+            opts.orderType !== undefined ||
+            opts.product !== undefined ||
+            opts.validity !== undefined;
+        if (usedSingleFlags) {
+            throw new UsageError('Use either --order (repeatable) or the single-order flags (--side/--quantity/--price/...), not both.');
+        }
+        return opts.order.map(parseOrderSpec);
+    }
+    return [legFromFlags(opts, lhs)];
+}
+/** Build a single leg on the *watched* instrument from the shorthand flags. */
+function legFromFlags(opts, lhs) {
     if (!opts.side)
-        throw new UsageError('--side (BUY or SELL) is required for an ATO alert.');
+        throw new UsageError('--side (BUY or SELL) is required for an ATO alert (or use --order).');
     if (opts.quantity === undefined)
-        throw new UsageError('--quantity is required for an ATO alert.');
+        throw new UsageError('--quantity is required for an ATO alert (or use --order).');
     const side = opts.side.toUpperCase();
     if (side !== 'BUY' && side !== 'SELL')
         throw new UsageError('--side must be BUY or SELL.');
-    const orderType = normalise(opts.orderType, ORDER_TYPES, 'order type');
-    const product = normalise(opts.product, PRODUCTS, 'product');
-    const validity = normalise(opts.validity, VALIDITIES, 'validity');
+    const orderType = normalise(opts.orderType ?? 'MARKET', ORDER_TYPES, 'order type');
+    const product = normalise(opts.product ?? 'CNC', PRODUCTS, 'product');
+    const validity = normalise(opts.validity ?? 'DAY', VALIDITIES, 'validity');
     if ((orderType === 'LIMIT' || orderType === 'SL') && opts.price === undefined) {
         throw new UsageError(`--price is required for a ${orderType} order.`);
     }
@@ -303,64 +333,200 @@ async function buildAtoBasket(ctx, opts, lhs) {
     if (orderType === 'MARKET' && opts.price !== undefined) {
         throw new UsageError('--price cannot be used with a MARKET order.');
     }
-    // The ATO order trades the LHS (watched) instrument.
-    const instrumentKey = formatInstrumentKey(lhs.exchange, lhs.tradingsymbol);
-    // Price for the value cap. An explicit limit price is authoritative; otherwise
-    // fall back to the last traded price, leaving it undefined if that fails.
-    let referencePrice = opts.price;
-    if (referencePrice === undefined) {
-        try {
-            const ltp = await ctx.api.getLtp([instrumentKey], ctx.signal);
-            referencePrice = ltp[instrumentKey]?.last_price;
+    return {
+        exchange: lhs.exchange,
+        tradingsymbol: lhs.tradingsymbol,
+        side: side,
+        quantity: opts.quantity,
+        orderType,
+        price: opts.price,
+        triggerPrice: opts.triggerPrice,
+        product,
+        validity,
+    };
+}
+/**
+ * Parse one `--order` spec into a leg.
+ *
+ * Grammar: `EXCHANGE:SYMBOL:SIDE:QTY` followed by any number of optional
+ * attribute tokens. Each attribute is either a bare vocabulary word (an order
+ * type, a product, a validity, or a number read as the price) or an explicit
+ * `key=value` (type, product, validity, price, trigger).
+ *
+ * Fails closed (invariant #1): every trailing token must be classified exactly
+ * once. An unrecognised token, a duplicated field, or an empty field rejects the
+ * whole spec — a silently mis-parsed leg is a real order with the wrong
+ * parameters. A trigger price is only ever set explicitly (`trigger=<n>`), never
+ * positionally, so an SL order can't be misread from two bare numbers.
+ */
+export function parseOrderSpec(spec) {
+    const raw = spec.trim();
+    const tokens = raw.split(':').map((t) => t.trim());
+    if (tokens.length < 4) {
+        throw new UsageError(`Malformed --order "${spec}".`, 'Expected at least EXCHANGE:SYMBOL:SIDE:QTY, e.g. NFO:INDIGO25AUGFUT:BUY:150:MARKET:NRML.');
+    }
+    // Guaranteed present by the length check above.
+    const [exchangeTok, symbolTok, sideTok, qtyTok, ...rest] = tokens;
+    const { exchange, tradingsymbol } = parseInstrumentKey(`${exchangeTok}:${symbolTok}`);
+    const side = sideTok.toUpperCase();
+    if (side !== 'BUY' && side !== 'SELL') {
+        throw new UsageError(`--order side must be BUY or SELL, got "${sideTok}" in "${spec}".`);
+    }
+    const quantity = Number(qtyTok);
+    if (!Number.isInteger(quantity) || quantity <= 0) {
+        throw new UsageError(`--order quantity must be a positive integer, got "${qtyTok}" in "${spec}".`);
+    }
+    let orderType;
+    let price;
+    let triggerPrice;
+    let product;
+    let validity;
+    const setOnce = (current, next, label) => {
+        if (current !== undefined)
+            throw new UsageError(`--order "${spec}" sets ${label} more than once.`);
+        return next;
+    };
+    for (const tok of rest) {
+        if (tok === '') {
+            throw new UsageError(`--order "${spec}" has an empty field. Remove the stray ":".`);
         }
-        catch {
-            // Quote bucket is 1/sec; a 429 here is routine. Leave undefined.
+        const eq = tok.indexOf('=');
+        if (eq !== -1) {
+            const key = tok.slice(0, eq).trim().toLowerCase();
+            const value = tok.slice(eq + 1).trim();
+            switch (key) {
+                case 'type':
+                    orderType = setOnce(orderType, normalise(value, ORDER_TYPES, 'order type'), 'the order type');
+                    break;
+                case 'product':
+                    product = setOnce(product, normalise(value, PRODUCTS, 'product'), 'the product');
+                    break;
+                case 'validity':
+                    validity = setOnce(validity, normalise(value, VALIDITIES, 'validity'), 'the validity');
+                    break;
+                case 'price':
+                    price = setOnce(price, parsePositive(value, 'price', spec), 'the price');
+                    break;
+                case 'trigger':
+                    triggerPrice = setOnce(triggerPrice, parsePositive(value, 'trigger', spec), 'the trigger price');
+                    break;
+                default:
+                    throw new UsageError(`--order "${spec}" has an unknown field "${key}".`, 'Valid keys: type, price, trigger, product, validity.');
+            }
+            continue;
+        }
+        const upper = tok.toUpperCase();
+        if (ORDER_TYPES.includes(upper)) {
+            orderType = setOnce(orderType, upper, 'the order type');
+        }
+        else if (PRODUCTS.includes(upper)) {
+            product = setOnce(product, upper, 'the product');
+        }
+        else if (VALIDITIES.includes(upper)) {
+            validity = setOnce(validity, upper, 'the validity');
+        }
+        else if (isNumeric(tok)) {
+            // A bare number is always the price. A trigger must be given explicitly.
+            price = setOnce(price, parsePositive(tok, 'price', spec), 'the price');
+        }
+        else {
+            throw new UsageError(`--order "${spec}" has an unrecognised field "${tok}".`, 'Fields after QTY are an order type, product, validity, a price, or trigger=<n>.');
         }
     }
-    if (referencePrice === undefined) {
-        ctx.io.warn(`Could not fetch a price for ${instrumentKey}; this alert's order value cannot be estimated.`);
+    const type = orderType ?? 'MARKET';
+    if ((type === 'LIMIT' || type === 'SL') && price === undefined) {
+        throw new UsageError(`--order "${spec}" is a ${type} order and needs a price.`);
     }
-    const notionalValue = referencePrice !== undefined ? referencePrice * opts.quantity : undefined;
-    const basket = {
-        name: 'kite-cli-alert',
-        type: 'alert',
-        tags: [],
-        items: [
-            {
-                type: 'insert',
-                tradingsymbol: lhs.tradingsymbol,
-                exchange: lhs.exchange,
-                // Documented baskets use 10000 (a full-allocation weight) for a single
-                // item; we follow the docs rather than invent a value.
-                weight: 10000,
-                params: {
-                    transaction_type: side,
-                    order_type: orderType,
-                    product,
-                    validity,
-                    quantity: opts.quantity,
-                    price: opts.price ?? 0,
-                    trigger_price: opts.triggerPrice ?? 0,
-                    variety: 'regular',
-                },
-            },
-        ],
+    if ((type === 'SL' || type === 'SL-M') && triggerPrice === undefined) {
+        throw new UsageError(`--order "${spec}" is a ${type} order and needs trigger=<price>.`);
+    }
+    if (type === 'MARKET' && price !== undefined) {
+        throw new UsageError(`--order "${spec}" is a MARKET order and cannot set a price.`);
+    }
+    return {
+        exchange,
+        tradingsymbol,
+        side: side,
+        quantity,
+        orderType: type,
+        price,
+        triggerPrice,
+        product: product ?? 'CNC',
+        validity: validity ?? 'DAY',
     };
-    const orderDetails = [
-        {
-            label: 'Order',
-            value: `${side === 'BUY' ? ctx.io.green(side) : ctx.io.red(side)} ${quantity(opts.quantity)} ${lhs.tradingsymbol}`,
-        },
-        { label: 'Order type', value: orderType },
-        ...(opts.price !== undefined ? [{ label: 'Price', value: rupees(opts.price) }] : []),
-        ...(opts.triggerPrice !== undefined ? [{ label: 'Trigger', value: rupees(opts.triggerPrice) }] : []),
-        { label: 'Product', value: product },
-        { label: 'Validity', value: validity },
-        {
-            label: 'Est. order value',
-            value: notionalValue !== undefined ? rupees(notionalValue) : ctx.io.dim('unknown (no quote available)'),
-        },
+}
+/**
+ * Price every leg and assemble the basket for the value cap and confirmation.
+ *
+ * Returns the notional as UNDEFINED when *any* leg cannot be priced, so the
+ * safety layer fails closed (escalates to a typed challenge) rather than
+ * treating an unknown total as small. Legs without an explicit limit price are
+ * quoted in a single batched LTP call.
+ */
+async function buildAtoBasket(ctx, legs) {
+    // Quote every leg that has no explicit price, in one call (the quote bucket
+    // is 1/sec, so N separate lookups would rate-limit).
+    const needQuote = [
+        ...new Set(legs.filter((l) => l.price === undefined).map((l) => formatInstrumentKey(l.exchange, l.tradingsymbol))),
     ];
+    let ltp = {};
+    if (needQuote.length > 0) {
+        try {
+            ltp = await ctx.api.getLtp(needQuote, ctx.signal);
+        }
+        catch {
+            // A 429 here is routine; leave legs unpriced so the cap fails closed.
+        }
+    }
+    let notionalValue = 0;
+    const items = [];
+    const orderDetails = [];
+    legs.forEach((leg, i) => {
+        const key = formatInstrumentKey(leg.exchange, leg.tradingsymbol);
+        const referencePrice = leg.price ?? ltp[key]?.last_price;
+        if (referencePrice === undefined) {
+            // One unpriceable leg voids the whole total — never sum around a gap.
+            notionalValue = undefined;
+            ctx.io.warn(`Could not fetch a price for ${key}; this alert's order value cannot be estimated.`);
+        }
+        else if (notionalValue !== undefined) {
+            notionalValue += referencePrice * leg.quantity;
+        }
+        items.push({
+            type: 'insert',
+            tradingsymbol: leg.tradingsymbol,
+            exchange: leg.exchange,
+            // Documented single-item baskets use 10000 (a full-allocation weight). The
+            // multi-item weighting is undocumented; params drive the actual order, so
+            // we keep 10000 per leg rather than invent a split.
+            weight: 10000,
+            params: {
+                transaction_type: leg.side,
+                order_type: leg.orderType,
+                product: leg.product,
+                validity: leg.validity,
+                quantity: leg.quantity,
+                price: leg.price ?? 0,
+                trigger_price: leg.triggerPrice ?? 0,
+                variety: 'regular',
+            },
+        });
+        const sideText = leg.side === 'BUY' ? ctx.io.green(leg.side) : ctx.io.red(leg.side);
+        const bits = [`${leg.orderType}`, leg.product];
+        if (leg.price !== undefined)
+            bits.push(`@ ${rupees(leg.price)}`);
+        if (leg.triggerPrice !== undefined)
+            bits.push(`trigger ${rupees(leg.triggerPrice)}`);
+        orderDetails.push({
+            label: legs.length === 1 ? 'Order' : `Order ${i + 1}`,
+            value: `${sideText} ${quantity(leg.quantity)} ${key} (${bits.join(', ')})`,
+        });
+    });
+    orderDetails.push({
+        label: legs.length === 1 ? 'Est. order value' : 'Est. total value',
+        value: notionalValue !== undefined ? rupees(notionalValue) : ctx.io.dim('unknown (no quote available)'),
+    });
+    const basket = { name: 'kite-cli-alert', type: 'alert', tags: [], items };
     return { basket, notionalValue, orderDetails };
 }
 // ---------------------------------------------------------------------------
@@ -522,6 +688,21 @@ function normalise(value, allowed, label) {
         return candidate;
     throw new UsageError(`Unknown ${label} "${value}".`, `Valid values: ${allowed.join(', ')}.`);
 }
+/** Commander reducer for a repeatable option: accumulate values into an array. */
+function collect(value, previous) {
+    return [...previous, value];
+}
+/** A finite number literal — rejects '', 'NaN', '1e', '2900abc', etc. */
+function isNumeric(value) {
+    return value !== '' && Number.isFinite(Number(value));
+}
+function parsePositive(value, label, spec) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new UsageError(`--order "${spec}" has an invalid ${label} "${value}"; expected a positive number.`);
+    }
+    return n;
+}
 function renderTableFor(ctx, rows, columns) {
     return renderTable(ctx.io, rows, columns, {
         compact: ctx.config.output.compact,

package/dist/commands/margins.d.ts

@@ -0,0 +1,34 @@
+import { type OrderType, type Product, type TransactionType, type Variety } from '../core/api.js';
+import type { CommandFactory } from './types.js';
+/**
+ * Margin and charge calculators — read-only.
+ *
+ * These POST a hypothetical set of orders to Kite and return what they would
+ * cost: `order` gives the per-order required margin (no netting), `basket` the
+ * net margin for the set (with spread/hedge benefit), and `charges` the
+ * itemised brokerage/tax breakdown (a "virtual contract note"). Nothing is
+ * placed, so none of the trading safety layer applies.
+ */
+export declare const marginCommands: CommandFactory;
+/** A hypothetical order, resolved from a spec, ready to serialise per endpoint. */
+export interface OrderSpec {
+    exchange: string;
+    tradingsymbol: string;
+    transactionType: TransactionType;
+    quantity: number;
+    orderType: OrderType;
+    product: Product;
+    variety: Variety;
+    price: number | undefined;
+    triggerPrice: number | undefined;
+}
+/**
+ * Parse one `EXCHANGE:SYMBOL:SIDE:QTY[:attrs...]` spec.
+ *
+ * Attributes after QTY are classified by content — an order type, a product, a
+ * variety, a bare number (the price), or `trigger=<n>`. Fails closed: an
+ * unrecognised token, a duplicated field, or an empty field rejects the whole
+ * spec rather than silently defaulting, since a mis-parsed order yields a
+ * silently wrong margin or charge.
+ */
+export declare function parseOrderSpec(spec: string): OrderSpec;

package/dist/commands/margins.js

@@ -0,0 +1,258 @@
+import { ORDER_TYPES, PRODUCTS, VARIETIES, } from '../core/api.js';
+import { UsageError } from '../core/errors.js';
+import { formatInstrumentKey, parseInstrumentKey } from '../core/instruments.js';
+import { money, rupees } from '../output/format.js';
+import { heading, printTable, renderKeyValue } from '../output/table.js';
+/**
+ * Margin and charge calculators — read-only.
+ *
+ * These POST a hypothetical set of orders to Kite and return what they would
+ * cost: `order` gives the per-order required margin (no netting), `basket` the
+ * net margin for the set (with spread/hedge benefit), and `charges` the
+ * itemised brokerage/tax breakdown (a "virtual contract note"). Nothing is
+ * placed, so none of the trading safety layer applies.
+ */
+export const marginCommands = (program, run) => {
+    const margins = program.command('margins').description('Calculate order margins and charges (nothing is placed)');
+    const orderExample = 'Each order is EXCHANGE:SYMBOL:SIDE:QTY[:TYPE][:PRODUCT][:VARIETY][:PRICE][:trigger=<n>], ' +
+        "e.g. 'NFO:NIFTY25AUGFUT:BUY:75:MARKET:NRML'. Product defaults to CNC, variety to regular.";
+    margins
+        .command('order')
+        .description('Required margin for each order on its own')
+        .argument('<orders...>', orderExample)
+        .action(run(orderMargins));
+    margins
+        .command('basket')
+        .description('Net margin for a basket of orders, with spread/hedge benefit')
+        .argument('<orders...>', orderExample)
+        .option('--no-consider-positions', 'Ignore existing positions when netting')
+        .action(run(basketMargins));
+    margins
+        .command('charges')
+        .description('Itemised charges for a set of executed orders (virtual contract note)')
+        .argument('<orders...>', `${orderExample} A non-zero price (the execution price) is required.`)
+        .action(run(orderCharges));
+};
+/**
+ * Parse one `EXCHANGE:SYMBOL:SIDE:QTY[:attrs...]` spec.
+ *
+ * Attributes after QTY are classified by content — an order type, a product, a
+ * variety, a bare number (the price), or `trigger=<n>`. Fails closed: an
+ * unrecognised token, a duplicated field, or an empty field rejects the whole
+ * spec rather than silently defaulting, since a mis-parsed order yields a
+ * silently wrong margin or charge.
+ */
+export function parseOrderSpec(spec) {
+    const tokens = spec
+        .trim()
+        .split(':')
+        .map((t) => t.trim());
+    if (tokens.length < 4) {
+        throw new UsageError(`Malformed order "${spec}".`, "Expected at least EXCHANGE:SYMBOL:SIDE:QTY, e.g. 'NFO:NIFTY25AUGFUT:BUY:75:NRML'.");
+    }
+    const [exchangeTok, symbolTok, sideTok, qtyTok, ...rest] = tokens;
+    const { exchange, tradingsymbol } = parseInstrumentKey(`${exchangeTok}:${symbolTok}`);
+    const side = sideTok.toUpperCase();
+    if (side !== 'BUY' && side !== 'SELL') {
+        throw new UsageError(`Order side must be BUY or SELL, got "${sideTok}" in "${spec}".`);
+    }
+    const quantity = Number(qtyTok);
+    if (!Number.isInteger(quantity) || quantity <= 0) {
+        throw new UsageError(`Order quantity must be a positive integer, got "${qtyTok}" in "${spec}".`);
+    }
+    let orderType;
+    let product;
+    let variety;
+    let price;
+    let triggerPrice;
+    const setOnce = (current, next, label) => {
+        if (current !== undefined)
+            throw new UsageError(`Order "${spec}" sets ${label} more than once.`);
+        return next;
+    };
+    for (const tok of rest) {
+        if (tok === '')
+            throw new UsageError(`Order "${spec}" has an empty field. Remove the stray ":".`);
+        const eq = tok.indexOf('=');
+        if (eq !== -1) {
+            const key = tok.slice(0, eq).trim().toLowerCase();
+            const value = tok.slice(eq + 1).trim();
+            if (key === 'price')
+                price = setOnce(price, parsePositive(value, 'price', spec), 'the price');
+            else if (key === 'trigger')
+                triggerPrice = setOnce(triggerPrice, parsePositive(value, 'trigger', spec), 'the trigger price');
+            else if (key === 'type')
+                orderType = setOnce(orderType, normalise(value, ORDER_TYPES, 'order type'), 'the order type');
+            else if (key === 'product')
+                product = setOnce(product, normalise(value, PRODUCTS, 'product'), 'the product');
+            else if (key === 'variety')
+                variety = setOnce(variety, normalise(value, VARIETIES, 'variety'), 'the variety');
+            else
+                throw new UsageError(`Order "${spec}" has an unknown field "${key}".`, 'Valid keys: type, product, variety, price, trigger.');
+            continue;
+        }
+        const upper = tok.toUpperCase();
+        const lower = tok.toLowerCase();
+        if (ORDER_TYPES.includes(upper)) {
+            orderType = setOnce(orderType, upper, 'the order type');
+        }
+        else if (PRODUCTS.includes(upper)) {
+            product = setOnce(product, upper, 'the product');
+        }
+        else if (VARIETIES.includes(lower)) {
+            variety = setOnce(variety, lower, 'the variety');
+        }
+        else if (isNumeric(tok)) {
+            // A bare number is the price. A trigger must be given explicitly.
+            price = setOnce(price, parsePositive(tok, 'price', spec), 'the price');
+        }
+        else {
+            throw new UsageError(`Order "${spec}" has an unrecognised field "${tok}".`, 'Fields after QTY are an order type, product, variety, a price, or trigger=<n>.');
+        }
+    }
+    return {
+        exchange,
+        tradingsymbol,
+        transactionType: side,
+        quantity,
+        orderType: orderType ?? 'MARKET',
+        product: product ?? 'CNC',
+        variety: variety ?? 'regular',
+        price,
+        triggerPrice,
+    };
+}
+function parseSpecs(args) {
+    if (args.length === 0)
+        throw new UsageError('At least one order is required.');
+    return args.map(parseOrderSpec);
+}
+/** Serialise for /margins/orders and /margins/basket (price + trigger_price). */
+function toMarginOrder(o) {
+    return {
+        exchange: o.exchange,
+        tradingsymbol: o.tradingsymbol,
+        transaction_type: o.transactionType,
+        variety: o.variety,
+        product: o.product,
+        order_type: o.orderType,
+        quantity: o.quantity,
+        price: o.price ?? 0,
+        trigger_price: o.triggerPrice ?? 0,
+    };
+}
+/**
+ * Serialise for /charges/orders (average_price + order_id, no price/trigger).
+ * Charges are a percentage of quantity × average_price, so a zero price yields
+ * a plausible-looking ≈₹0 that is silently wrong — require a real price.
+ */
+function toChargesOrder(o, index) {
+    if (o.price === undefined || o.price <= 0) {
+        throw new UsageError(`Order "${formatInstrumentKey(o.exchange, o.tradingsymbol)}" needs a non-zero price for charges.`, 'Charges are computed from quantity × execution price; add a price, e.g. :1500 or price=1500.');
+    }
+    return {
+        // A virtual contract note needs an order_id per leg; the index is fine.
+        order_id: String(index + 1),
+        exchange: o.exchange,
+        tradingsymbol: o.tradingsymbol,
+        transaction_type: o.transactionType,
+        variety: o.variety,
+        product: o.product,
+        order_type: o.orderType,
+        quantity: o.quantity,
+        average_price: o.price,
+    };
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function orderMargins(ctx, _opts, command) {
+    ctx.requireSession();
+    const specs = parseSpecs(command.args);
+    const margins = await ctx.api.orderMargins(specs.map(toMarginOrder), ctx.signal);
+    const columns = marginColumns();
+    printTable(ctx.io, margins, columns, margins, { compact: ctx.config.output.compact, empty: 'No margins returned.' });
+    if (ctx.io.json)
+        return;
+    const total = margins.reduce((sum, m) => sum + (m.total ?? 0), 0);
+    ctx.io.line('');
+    ctx.io.line(`  Total margin required ${rupees(total)}`);
+}
+async function basketMargins(ctx, opts, command) {
+    ctx.requireSession();
+    const specs = parseSpecs(command.args);
+    const basket = await ctx.api.basketMargins(specs.map(toMarginOrder), opts.considerPositions !== false, ctx.signal);
+    if (ctx.io.json) {
+        ctx.io.writeJson(basket);
+        return;
+    }
+    const { io } = ctx;
+    io.line(heading(io, 'Per order'));
+    printTable(io, basket.orders, marginColumns(), basket.orders, {
+        compact: ctx.config.output.compact,
+        empty: 'No orders.',
+    });
+    // `final` is the margin actually blocked after spread/hedge benefit; `initial`
+    // is the gross figure before it. The difference is the benefit itself.
+    const finalTotal = basket.final?.total ?? 0;
+    const initialTotal = basket.initial?.total ?? 0;
+    io.line('');
+    io.line(renderKeyValue(io, [
+        ['Margin before benefit', rupees(initialTotal)],
+        ['Spread/hedge benefit', rupees(Math.max(0, initialTotal - finalTotal))],
+        ['Net margin required', io.bold(rupees(finalTotal))],
+    ]));
+}
+async function orderCharges(ctx, _opts, command) {
+    ctx.requireSession();
+    const specs = parseSpecs(command.args);
+    const charges = await ctx.api.orderCharges(specs.map((o, i) => toChargesOrder(o, i)), ctx.signal);
+    const columns = [
+        { header: 'Symbol', value: (m, io) => io.bold(`${m.exchange ?? '?'}:${m.tradingsymbol ?? '?'}`) },
+        { header: 'Brokerage', value: (m) => money(m.charges?.brokerage), align: 'right' },
+        { header: 'STT/CTT', value: (m) => money(m.charges?.transaction_tax), align: 'right' },
+        { header: 'Txn', value: (m) => money(m.charges?.exchange_turnover_charge), align: 'right' },
+        { header: 'GST', value: (m) => money(m.charges?.gst?.total), align: 'right' },
+        { header: 'Stamp', value: (m) => money(m.charges?.stamp_duty), align: 'right' },
+        { header: 'SEBI', value: (m) => money(m.charges?.sebi_turnover_charge), align: 'right' },
+        { header: 'Total', value: (m, io) => io.bold(money(m.charges?.total)), align: 'right' },
+    ];
+    printTable(ctx.io, charges, columns, charges, {
+        compact: ctx.config.output.compact,
+        empty: 'No charges returned.',
+    });
+    if (ctx.io.json)
+        return;
+    const total = charges.reduce((sum, m) => sum + (m.charges?.total ?? 0), 0);
+    ctx.io.line('');
+    ctx.io.line(`  Total charges ${rupees(total)}`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function marginColumns() {
+    return [
+        { header: 'Symbol', value: (m, io) => io.bold(`${m.exchange ?? '?'}:${m.tradingsymbol ?? '?'}`) },
+        { header: 'SPAN', value: (m) => money(m.span), align: 'right' },
+        { header: 'Exposure', value: (m) => money(m.exposure), align: 'right' },
+        { header: 'Premium', value: (m) => money(m.option_premium), align: 'right' },
+        { header: 'Var', value: (m) => money(m.var), align: 'right' },
+        { header: 'Total', value: (m, io) => io.bold(money(m.total)), align: 'right' },
+    ];
+}
+function normalise(value, allowed, label) {
+    const candidate = label === 'variety' ? value.toLowerCase() : value.toUpperCase();
+    if (allowed.includes(candidate))
+        return candidate;
+    throw new UsageError(`Unknown ${label} "${value}".`, `Valid values: ${allowed.join(', ')}.`);
+}
+function isNumeric(value) {
+    return value !== '' && Number.isFinite(Number(value));
+}
+function parsePositive(value, label, spec) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new UsageError(`Order "${spec}" has an invalid ${label} "${value}"; expected a positive number.`);
+    }
+    return n;
+}

package/dist/commands/mf.d.ts

@@ -0,0 +1,10 @@
+import type { CommandFactory } from './types.js';
+/**
+ * Mutual funds — read only.
+ *
+ * Kite Connect does not offer MF order placement or SIP management over the
+ * API (an MF purchase needs a bank debit the API can't authorise), so this is
+ * holdings, recent orders, and SIPs — the three read endpoints — and nothing
+ * that moves money. No kill switch, value cap, or confirmation applies.
+ */
+export declare const mfCommands: CommandFactory;

package/dist/commands/mf.js

@@ -0,0 +1,85 @@
+import { dateTime, money, quantity, rupees, signedRupees } from '../output/format.js';
+import { printTable } from '../output/table.js';
+/**
+ * Mutual funds — read only.
+ *
+ * Kite Connect does not offer MF order placement or SIP management over the
+ * API (an MF purchase needs a bank debit the API can't authorise), so this is
+ * holdings, recent orders, and SIPs — the three read endpoints — and nothing
+ * that moves money. No kill switch, value cap, or confirmation applies.
+ */
+export const mfCommands = (program, run) => {
+    const mf = program.command('mf').description('View mutual fund holdings, orders and SIPs');
+    mf.command('holdings', { isDefault: true }).description('Show your mutual fund holdings').action(run(mfHoldings));
+    mf.command('orders').description('Show mutual fund orders from the last 7 days').action(run(mfOrders));
+    mf.command('sips').description('Show your mutual fund SIPs').action(run(mfSips));
+};
+async function mfHoldings(ctx) {
+    ctx.requireSession();
+    const rows = await ctx.api.getMfHoldings(ctx.signal);
+    const columns = [
+        { header: 'Fund', value: (h, io) => io.bold(h.fund ?? h.tradingsymbol) },
+        { header: 'Folio', value: (h) => h.folio ?? '—' },
+        { header: 'Units', value: (h) => quantity(h.quantity), align: 'right' },
+        { header: 'Avg', value: (h) => money(h.average_price), align: 'right' },
+        { header: 'NAV', value: (h) => money(h.last_price), align: 'right' },
+        { header: 'Value', value: (h) => money(h.last_price * h.quantity), align: 'right' },
+        { header: 'P&L', value: (h, io) => io.signed(h.pnl, signedRupees(h.pnl)), align: 'right' },
+    ];
+    printTable(ctx.io, rows, columns, rows, {
+        compact: ctx.config.output.compact,
+        empty: 'No mutual fund holdings.',
+    });
+    if (ctx.io.json)
+        return;
+    const totalValue = rows.reduce((sum, h) => sum + h.last_price * h.quantity, 0);
+    const totalPnl = rows.reduce((sum, h) => sum + h.pnl, 0);
+    if (rows.length > 0) {
+        const { io } = ctx;
+        io.line('');
+        io.line(`  Current value ${rupees(totalValue)}   P&L ${io.signed(totalPnl, signedRupees(totalPnl))}`);
+    }
+}
+async function mfOrders(ctx) {
+    ctx.requireSession();
+    const rows = await ctx.api.getMfOrders(ctx.signal);
+    const columns = [
+        { header: 'Order ID', value: (o, io) => io.dim(o.order_id) },
+        { header: 'Fund', value: (o, io) => io.bold(o.fund ?? o.tradingsymbol ?? '—') },
+        {
+            header: 'Side',
+            value: (o, io) => o.transaction_type === 'BUY'
+                ? io.green('BUY')
+                : o.transaction_type === 'SELL'
+                    ? io.red('SELL')
+                    : (o.transaction_type ?? '—'),
+        },
+        { header: 'Status', value: (o) => o.status ?? '—' },
+        { header: 'Units', value: (o) => quantity(o.quantity ?? undefined), align: 'right' },
+        { header: 'Amount', value: (o) => money(o.amount ?? undefined), align: 'right' },
+        { header: 'When', value: (o) => dateTime(o.order_timestamp ?? undefined) },
+    ];
+    printTable(ctx.io, rows, columns, rows, {
+        compact: ctx.config.output.compact,
+        // An empty list can just mean nothing was placed recently, not that you have
+        // no MF history — the endpoint only reaches back 7 days.
+        empty: 'No mutual fund orders in the last 7 days.',
+    });
+}
+async function mfSips(ctx) {
+    ctx.requireSession();
+    const rows = await ctx.api.getMfSips(ctx.signal);
+    const columns = [
+        { header: 'SIP ID', value: (s, io) => io.dim(s.sip_id) },
+        { header: 'Fund', value: (s, io) => io.bold(s.fund ?? s.tradingsymbol ?? '—') },
+        { header: 'Status', value: (s) => s.status ?? '—' },
+        { header: 'Instalment', value: (s) => money(s.instalment_amount), align: 'right' },
+        { header: 'Done', value: (s) => quantity(s.instalments), align: 'right' },
+        { header: 'Frequency', value: (s) => s.frequency ?? '—' },
+        { header: 'Next', value: (s) => dateTime(s.next_instalment ?? undefined) },
+    ];
+    printTable(ctx.io, rows, columns, rows, {
+        compact: ctx.config.output.compact,
+        empty: 'No mutual fund SIPs.',
+    });
+}

package/dist/core/schemas.d.ts

@@ -683,6 +683,7 @@ export declare const BasketMarginSchema: z.ZodObject<{
     }, z.core.$loose>>>;
     charges: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$loose>;
+export type BasketMargin = z.infer<typeof BasketMarginSchema>;
 export declare const MfHoldingSchema: z.ZodObject<{
     folio: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     fund: z.ZodOptional<z.ZodString>;
@@ -707,6 +708,7 @@ export declare const MfOrderSchema: z.ZodObject<{
     amount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     average_price: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$loose>;
+export type MfOrder = z.infer<typeof MfOrderSchema>;
 export declare const MfSipSchema: z.ZodObject<{
     sip_id: z.ZodString;
     tradingsymbol: z.ZodOptional<z.ZodString>;
@@ -717,6 +719,7 @@ export declare const MfSipSchema: z.ZodObject<{
     frequency: z.ZodOptional<z.ZodString>;
     next_instalment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$loose>;
+export type MfSip = z.infer<typeof MfSipSchema>;
 export declare const InstrumentSchema: z.ZodObject<{
     instrument_token: z.ZodNumber;
     exchange_token: z.ZodOptional<z.ZodNumber>;

package/dist/run.js

@@ -77,6 +77,8 @@ export async function run(opts = {}) {
     const { orderCommands } = await import('./commands/orders.js');
     const { gttCommands } = await import('./commands/gtt.js');
     const { alertCommands } = await import('./commands/alerts.js');
+    const { marginCommands } = await import('./commands/margins.js');
+    const { mfCommands } = await import('./commands/mf.js');
     const { watchCommands } = await import('./commands/watch.js');
     const { configCommands } = await import('./commands/config.js');
     // commandsGroup applies to every command registered after it, so the group
@@ -87,12 +89,15 @@ export async function run(opts = {}) {
     profileCommands(program, withContext);
     program.commandsGroup('Portfolio:');
     portfolioCommands(program, withContext);
+    program.commandsGroup('Mutual funds:');
+    mfCommands(program, withContext);
     program.commandsGroup('Market data:');
     marketCommands(program, withContext);
     program.commandsGroup('Trading:');
     orderCommands(program, withContext);
     gttCommands(program, withContext);
     alertCommands(program, withContext);
+    marginCommands(program, withContext);
     program.commandsGroup('Streaming:');
     watchCommands(program, withContext);
     program.commandsGroup('Settings:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pungoyal/kite-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Unofficial command-line interface for the Zerodha Kite Connect API — not affiliated with or endorsed by Zerodha",
   "keywords": [
     "zerodha",
@@ -18,7 +18,7 @@
     "type": "git",
     "url": "git+https://github.com/pungoyal/kite-cli.git"
   },
-  "homepage": "https://github.com/pungoyal/kite-cli#readme",
+  "homepage": "https://pungoyal.github.io/kite-cli",
   "bugs": {
     "url": "https://github.com/pungoyal/kite-cli/issues"
   },