@pungoyal/kite-cli 0.2.1 → 0.4.0

package/README.md

@@ -50,7 +50,7 @@ Then:
 kite login
 ```
 
-This opens your browser, you log in to Zerodha normally (including your TOTP), and the CLI captures the callback on loopback. Your API secret goes into your OS keyring; the daily access token is stored alongside it.
+This opens your browser, you log in to Zerodha normally (including your TOTP), and the CLI captures the callback on loopback. The login URL is also printed to the terminal — press `c` while it's waiting to copy it to your clipboard (handy if the browser didn't open, or you want to log in on another device). Your API secret goes into your OS keyring; the daily access token is stored alongside it.
 
 **Want to try it without a subscription or real money?** Zerodha runs a public sandbox:
 
@@ -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/auth.d.ts

@@ -1,2 +1,11 @@
+import type { Context } from '../context.js';
 import type { CommandFactory } from './types.js';
 export declare const authCommands: CommandFactory;
+/**
+ * While waiting for the browser callback, listen for a `c` keypress to copy the
+ * login URL, and for Ctrl-C to abort. Entering raw mode makes us responsible for
+ * both restoring the terminal and re-handling Ctrl-C (raw mode no longer raises
+ * SIGINT). Returns a no-op when stdin is not a TTY, and an idempotent cleanup
+ * that both the caller and the Ctrl-C path can safely call.
+ */
+export declare function listenForKeys(ctx: Context, loginUrl: string, onInterrupt: () => void): () => void;

package/dist/commands/auth.js

@@ -1,5 +1,5 @@
 import { isCancel, note, password, text } from '@clack/prompts';
-import { buildLoginUrl, computeChecksum, generateState, openBrowser, redirectUrlFor, waitForCallback, } from '../core/auth.js';
+import { buildLoginUrl, computeChecksum, copyToClipboard, generateState, openBrowser, redirectUrlFor, waitForCallback, } from '../core/auth.js';
 import { loadConfig, SANDBOX_CREDENTIALS, saveConfig } from '../core/config.js';
 import { deleteAllSecrets, getSecret, keyringAvailable, setSecret } from '../core/credentials.js';
 import { AbortedError, ExitCode, KiteCliError } from '../core/errors.js';
@@ -145,23 +145,92 @@ async function callbackFlow(ctx, loginUrl) {
     io.info(`Your Kite app's redirect URL must be exactly: ${io.bold(redirectUrl)}`);
     io.info('Set it at https://developers.kite.trade if login fails.');
     io.note('');
+    // Show the URL unconditionally: the browser may not have opened, may have
+    // landed in the wrong profile, or the user may want to log in on another
+    // device. The URL carries only the api_key and CSRF state — no token.
+    io.info('Login URL:');
+    io.note(`  ${loginUrl}`);
+    io.note('');
     const opened = await openBrowser(loginUrl);
     if (opened) {
         io.info('Opened your browser to complete login…');
     }
     else {
-        io.warn('Could not open a browser automatically. Open this URL manually:');
-        io.note(`  ${loginUrl}`);
+        io.warn('Could not open a browser automatically. Open the URL above manually.');
     }
-    io.info('Waiting for the callback (Ctrl-C to abort)…');
+    // Let the user grab the URL without selecting it in the terminal. Copy-on-`c`
+    // and Ctrl-C both funnel through `interrupted`, which loses the race against a
+    // successful callback. A single Ctrl-C aborts the wait — raw mode swallows the
+    // SIGINT, and the loopback promise never observes ctx.signal on its own.
+    let interrupt = () => { };
+    const interrupted = new Promise((_, reject) => {
+        interrupt = () => reject(new AbortedError('Interrupted.'));
+    });
+    const onAbort = () => interrupt();
+    if (ctx.signal.aborted)
+        onAbort();
+    else
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+    const stopKeys = listenForKeys(ctx, loginUrl, interrupt);
+    io.info(`Waiting for the callback (press ${io.bold('c')} to copy the login URL, Ctrl-C to abort)…`);
     try {
-        const result = await server.promise;
+        const result = await Promise.race([server.promise, interrupted]);
         return result.requestToken;
     }
     finally {
+        // Always restore the terminal and detach listeners, even on abort — the
+        // loopback promise may never settle, so this cannot hang off it.
+        stopKeys();
+        ctx.signal.removeEventListener('abort', onAbort);
         server.close();
     }
 }
+/**
+ * While waiting for the browser callback, listen for a `c` keypress to copy the
+ * login URL, and for Ctrl-C to abort. Entering raw mode makes us responsible for
+ * both restoring the terminal and re-handling Ctrl-C (raw mode no longer raises
+ * SIGINT). Returns a no-op when stdin is not a TTY, and an idempotent cleanup
+ * that both the caller and the Ctrl-C path can safely call.
+ */
+// Exported for tests: the raw-mode lifecycle (enter, restore, detach) and the
+// Ctrl-C byte path are the risky parts, and a real TTY can't be driven in CI.
+export function listenForKeys(ctx, loginUrl, onInterrupt) {
+    const { io } = ctx;
+    const stdin = process.stdin;
+    if (!stdin.isTTY)
+        return () => { };
+    const wasRaw = stdin.isRaw;
+    let stopped = false;
+    const cleanup = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stdin.off('data', onData);
+        stdin.setRawMode(wasRaw);
+        stdin.pause();
+    };
+    const onData = (chunk) => {
+        // 0x03 is Ctrl-C, which raw mode delivers as a byte instead of a SIGINT.
+        if (chunk.length === 1 && chunk[0] === 0x03) {
+            cleanup();
+            onInterrupt();
+            return;
+        }
+        const key = chunk.toString('utf8');
+        if (key === 'c' || key === 'C') {
+            void copyToClipboard(loginUrl).then((ok) => {
+                if (ok)
+                    io.success('Login URL copied to clipboard.');
+                else
+                    io.warn('Could not copy to the clipboard (no clipboard tool found).');
+            });
+        }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', onData);
+    return cleanup;
+}
 /** Fallback for remote shells, where no browser can reach 127.0.0.1. */
 async function manualFlow(ctx, loginUrl) {
     const { io } = ctx;

package/dist/commands/completion.d.ts

@@ -0,0 +1,35 @@
+import type { CommandFactory } from './types.js';
+/**
+ * Shell completion scripts, generated from the live command tree.
+ *
+ * Rather than hand-maintain a completion file per shell — the exact docs-rot
+ * trap a CLI that places real orders cannot afford — this walks the same
+ * registration path run() uses (with a no-op runner) and emits command names,
+ * subcommand names, and long flags straight from it. A new command or flag is
+ * completable as soon as it is added; the only user step is to regenerate after
+ * upgrading, the same contract gh, rustup, and kubectl ship.
+ *
+ * Depth is intentionally capped at command → subcommand + flags, which covers
+ * every path this CLI has (`config set`, `margins order`, `orders place`).
+ */
+declare const SHELLS: readonly ['bash', 'zsh', 'fish'];
+type Shell = (typeof SHELLS)[number];
+export declare const completionCommands: CommandFactory;
+export interface CompletionModel {
+    /** Top-level command names (excluding commander's built-in `help`). */
+    commands: string[];
+    /** Subcommand names keyed by their parent command name. */
+    subcommands: Record<string, string[]>;
+    /** Long flags valid on every command. */
+    globalFlags: string[];
+    /** Human descriptions for the shells that render them (zsh, fish). */
+    descriptions: Record<string, string>;
+}
+/**
+ * Build the completion model by registering the real command tree onto a
+ * throwaway program. The runner is a no-op: completion needs each command's
+ * name, options, and subcommands, never its behaviour.
+ */
+export declare function buildModel(): Promise<CompletionModel>;
+export declare function renderScript(shell: Shell, model: CompletionModel): string;
+export {};