@pungoyal/kite-cli 0.3.0 → 0.5.0

package/README.md

@@ -28,6 +28,52 @@ $ kite holdings
   Day's change  +₹287.40
 ```
 
+## Why you can trust it
+
+It places real orders with real money, under an unofficial banner — so the safety
+is built into the architecture, and every claim below is verifiable rather than
+aspirational:
+
+- **Try it risk-free first.** Zerodha runs a public sandbox with fake money and no
+  subscription. `kite login --env sandbox` gives you a full session to rehearse
+  every command against before you ever point it at your own account.
+- **It never silently moves money.** Every order previews the *resolved* order —
+  the actual contract, lot size and computed value, not an echo of your flags —
+  and waits for confirmation. There is deliberately no config key that turns that
+  off ([Safety](#safety)).
+- **It never blindly retries a write.** Kite has no idempotency key, so a
+  timed-out order is genuinely ambiguous. Rather than retry, the CLI tags every
+  order and reconciles against the orderbook to tell you what actually happened
+  ([Safety](#safety)).
+- **Your secrets stay put.** The API secret lives in your OS keyring (or an
+  encrypted file), is never accepted as a command-line argument, and is scrubbed
+  from every log, error and stack trace — with [tests](https://github.com/pungoyal/kite-cli/blob/main/test/redact.test.ts)
+  that prove it ([Security](#security)).
+- **Verifiable builds.** Published only from CI via [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+  (OIDC, no long-lived token). Check the provenance yourself with `npm audit signatures`.
+- **A small, auditable surface.** ~10 direct dependencies, most of them
+  zero-dependency, enforced by a dependency budget in CI.
+
+## How it compares
+
+Zerodha maintains excellent official SDKs — [`pykiteconnect`](https://github.com/zerodha/pykiteconnect)
+and [`kiteconnectjs`](https://github.com/zerodha/kiteconnectjs). If you're building an
+application, reach for those: they give you the full API, programmatically, and they're
+the foundation the whole ecosystem is built on. `kite-cli` is complementary — the same
+API as a ready-to-use tool, for when you'd rather not write code:
+
+- **Zero code for everyday use.** `kite holdings`, `kite watch --holdings`,
+  `kite orders place …` run straight from the shell — and from any language that can
+  shell out.
+- **An opinionated safety layer.** A kill switch, per-order value cap, resolved-order
+  confirmation, and unique-tag reconciliation for ambiguous writes come built in —
+  decisions the official SDKs deliberately leave open so each application can make its
+  own.
+- **Composable output.** Every command speaks `--json` on stdout, so it drops
+  straight into `jq`, cron jobs, and pipelines.
+- **A library too, when you need one.** The same client is [exported](#library-use),
+  so you can start in the shell and drop into code without switching tools.
+
 ## Install
 
 ```bash
@@ -38,7 +84,21 @@ Requires **Node 22.12 or newer**.
 
 ## Getting started
 
-You need a [Kite Connect](https://developers.kite.trade) app to get an API key and secret. Set your app's redirect URL to:
+**Kick the tyres first — no account, no subscription, no risk.** Zerodha runs a
+public sandbox with fake money, and every command behaves exactly as it does
+against a real account:
+
+```bash
+kite login --env sandbox
+kite --env sandbox holdings
+kite --env sandbox orders place NSE:INFY --side BUY --quantity 1 --dry-run
+```
+
+Learn the commands and see the confirmations there before any real money is
+involved.
+
+**Then connect your own account.** You need a [Kite Connect](https://developers.kite.trade)
+app to get an API key and secret. Set your app's redirect URL to:
 
 ```
 http://127.0.0.1:51101/callback
@@ -50,14 +110,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.
-
-**Want to try it without a subscription or real money?** Zerodha runs a public sandbox:
-
-```bash
-kite login --env sandbox
-kite --env sandbox holdings
-```
+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.
 
 **Running more than one Zerodha account?** See [Multiple accounts](#multiple-accounts).
 
@@ -147,6 +200,7 @@ kite orders list --open                # working orders only
 kite orders get 250720000123456        # full state history and fills
 kite orders modify <id> --price 1520
 kite orders cancel <id>
+kite orders reconcile <tag>            # did an order that seemed to fail actually reach Kite?
 kite trades                            # today's fills
 
 kite gtt list
@@ -245,6 +299,31 @@ kite whoami --json || kite login       # exit code 3 means "no session"
 
 `NO_COLOR` is honoured, and colour is disabled automatically when stdout is not a TTY.
 
+### Agents (MCP)
+
+`kite mcp` exposes Kite's **read-only** endpoints to an LLM agent over the
+[Model Context Protocol](https://modelcontextprotocol.io), so Claude — or any MCP
+client — can answer "how's my portfolio doing?" against live data. It can read
+your profile, holdings, positions, funds, orders, trades, quotes and instruments;
+it **cannot** place, modify or cancel anything. Trading stays at a
+human-confirmed terminal, by design.
+
+Point an MCP client at it — try the sandbox first:
+
+```json
+{
+  "mcpServers": {
+    "kite": {
+      "command": "kite",
+      "args": ["mcp", "--env", "sandbox"]
+    }
+  }
+}
+```
+
+Drop the `--env sandbox` args to run against your real account (still read-only).
+The server needs a live session, so `kite login` first.
+
 ## Multiple accounts
 
 If you run more than one Zerodha account — your own, a family member's, an HUF — each
@@ -329,6 +408,17 @@ $ kite orders place NSE:INFY -s BUY -q 10 --type LIMIT --price 1500 --yes
 · It was not placed twice. Do not re-run this command.
 ```
 
+That reconciliation happens automatically, but only while the placing process is alive. If you lose it — a killed shell, a crashed script, a slept laptop — run it again on demand:
+
+```console
+$ kite orders reconcile kcmrt88o648c1bce
+✓ Found an order for tag kcmrt88o648c1bce:
+  … COMPLETE …
+· If placing this order looked like it failed, it went through — do not place it again.
+```
+
+With no tag, `kite orders reconcile` lists the orders this CLI placed today, and `--json` carries a `placed` boolean for scripts.
+
 Automatic retries are restricted to `GET`/`HEAD` at the transport layer. `POST`, `PUT` and `DELETE` are never retried — in this API those are place, modify and cancel.
 
 ## Security
@@ -394,6 +484,8 @@ searchable site at **[pungoyal.github.io/kite-cli](https://pungoyal.github.io/ki
 
 - [Safety model](https://pungoyal.github.io/kite-cli/safety) — the full layered safety model (kill
   switch, value cap, confirmation escalation, order-tag reconciliation).
+- [MCP server](https://pungoyal.github.io/kite-cli/mcp) — the read-only Model Context Protocol
+  server for LLM agents: its tools, setup, and why it exposes no writes.
 - [Configuration](https://pungoyal.github.io/kite-cli/configuration) — every config key and
   environment variable, with precedence.
 - [Troubleshooting](https://pungoyal.github.io/kite-cli/troubleshooting) — symptom-first fixes

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 {};

package/dist/commands/completion.js

@@ -0,0 +1,240 @@
+import { Command } from 'commander';
+import { UsageError } from '../core/errors.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`).
+ */
+const SHELLS = ['bash', 'zsh', 'fish'];
+export const completionCommands = (program, run) => {
+    program
+        .command('completion')
+        .summary('Print a shell completion script')
+        .description('Print a shell completion script for bash, zsh, or fish.\n\n' +
+        'The shell is auto-detected from $SHELL when omitted. Install with, e.g.:\n' +
+        '  bash   kite completion bash >> ~/.bash_completion\n' +
+        '  zsh    kite completion zsh  > ~/.zfunc/_kite   (with ~/.zfunc on your fpath)\n' +
+        '  fish   kite completion fish > ~/.config/fish/completions/kite.fish')
+        .argument('[shell]', 'Target shell: bash, zsh, or fish')
+        .action(run(completion));
+};
+async function completion(ctx, _opts, command) {
+    const requested = (command.args[0] ?? detectShell())?.toLowerCase();
+    if (!requested) {
+        throw new UsageError('Could not detect your shell from $SHELL.', `Name it explicitly: kite completion <${SHELLS.join('|')}>.`);
+    }
+    if (!isShell(requested)) {
+        throw new UsageError(`Unsupported shell "${requested}".`, `Supported shells: ${SHELLS.join(', ')}.`);
+    }
+    const model = await buildModel();
+    // The script is data: it goes to stdout so `kite completion bash > file`
+    // captures exactly the script and nothing else.
+    ctx.io.line(renderScript(requested, model));
+}
+/**
+ * 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 async function buildModel() {
+    const { applyGlobalOptions, registerCommands } = await import('./register.js');
+    const program = new Command('kite');
+    applyGlobalOptions(program);
+    const noop = () => async () => { };
+    await registerCommands(program, noop);
+    const descriptions = {};
+    const subcommands = {};
+    const commands = [];
+    for (const cmd of realCommands(program)) {
+        commands.push(cmd.name());
+        descriptions[cmd.name()] = summaryOf(cmd);
+        const subs = realCommands(cmd);
+        if (subs.length > 0) {
+            subcommands[cmd.name()] = subs.map((s) => s.name());
+            for (const sub of subs)
+                descriptions[`${cmd.name()} ${sub.name()}`] = summaryOf(sub);
+        }
+    }
+    return { commands, subcommands, globalFlags: longFlags(program), descriptions };
+}
+/** Child commands, minus commander's auto-generated `help` command. */
+function realCommands(cmd) {
+    return cmd.commands.filter((c) => c.name() !== 'help');
+}
+function longFlags(cmd) {
+    return cmd.options.map((o) => o.long).filter((long) => Boolean(long));
+}
+function summaryOf(cmd) {
+    // summary() is the short one-liner; description() may be a multi-line block.
+    const text = cmd.summary() || cmd.description().split('\n')[0] || '';
+    return sanitize(text);
+}
+/**
+ * Strip characters that would break a quoted description in a shell script.
+ * Backslash is included: fish treats it as an escape inside single quotes, so a
+ * description ending in `\` would escape the closing quote and corrupt the line.
+ */
+function sanitize(text) {
+    return text
+        .replace(/['\\\n\r]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// --- rendering -------------------------------------------------------------
+export function renderScript(shell, model) {
+    // Sanitise at the rendering boundary, not only in buildModel(), so renderScript
+    // can never emit a script broken by a stray quote or backslash regardless of
+    // how its model was built.
+    const safe = {
+        ...model,
+        descriptions: Object.fromEntries(Object.entries(model.descriptions).map(([key, value]) => [key, sanitize(value)])),
+    };
+    switch (shell) {
+        case 'bash':
+            return renderBash(safe);
+        case 'zsh':
+            return renderZsh(safe);
+        case 'fish':
+            return renderFish(safe);
+    }
+}
+function renderBash(model) {
+    // A `case` for subcommands rather than an associative array, so this works on
+    // the bash 3.2 that macOS still ships (declare -A is bash 4+).
+    const subCases = Object.entries(model.subcommands)
+        .map(([cmd, subs]) => `    ${cmd}) echo "${subs.join(' ')}" ;;`)
+        .join('\n');
+    return `# kite bash completion. Source it, or install with:
+#   kite completion bash >> ~/.bash_completion
+_kite_subcommands() {
+  case "$1" in
+${subCases}
+  esac
+}
+
+_kite() {
+  local cur cmd sub i w
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  # First two non-flag words after "kite" are the command and its subcommand.
+  cmd=""; sub=""
+  for (( i=1; i < COMP_CWORD; i++ )); do
+    w="\${COMP_WORDS[i]}"
+    [[ "$w" == -* ]] && continue
+    if [[ -z "$cmd" ]]; then cmd="$w"; else sub="$w"; break; fi
+  done
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "${model.globalFlags.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${model.commands.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  if [[ -z "$sub" ]]; then
+    local subs
+    subs="$(_kite_subcommands "$cmd")"
+    [[ -n "$subs" ]] && COMPREPLY=( $(compgen -W "$subs" -- "$cur") )
+  fi
+}
+complete -F _kite kite
+`;
+}
+function renderZsh(model) {
+    const topDescribe = model.commands.map((name) => `    '${name}:${model.descriptions[name] ?? ''}'`).join('\n');
+    // Build the sub arrays inline per command so descriptions survive.
+    const subBlocks = Object.entries(model.subcommands)
+        .map(([cmd, subs]) => {
+        const described = subs.map((s) => `'${s}:${model.descriptions[`${cmd} ${s}`] ?? ''}'`).join(' ');
+        return `    ${cmd}) local -a subs=(${described}); _describe 'subcommand' subs ;;`;
+    })
+        .join('\n');
+    return `#compdef kite
+# kite zsh completion. Install with:
+#   kite completion zsh > "\${fpath[1]}/_kite"
+_kite() {
+  local -a commands
+  commands=(
+${topDescribe}
+  )
+
+  # Flags complete anywhere the current word starts with a dash. \`compadd --\`
+  # is required: a bare \`compadd --json\` makes zsh parse the flags as its own
+  # options instead of as candidates.
+  if [[ \${words[CURRENT]} == -* ]]; then
+    compadd -- ${model.globalFlags.join(' ')}
+    return
+  fi
+
+  # Top-level command name.
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+
+  # Subcommands only at the subcommand position; deeper positions offer nothing,
+  # which caps depth at command -> subcommand as documented.
+  if (( CURRENT == 3 )); then
+    case \${words[2]} in
+${subBlocks}
+    esac
+  fi
+}
+compdef _kite kite
+`;
+}
+function renderFish(model) {
+    const lines = [
+        '# kite fish completion. Install with:',
+        '#   kite completion fish > ~/.config/fish/completions/kite.fish',
+        '',
+        '# No file completion by default; kite takes symbols and subcommands, not paths.',
+        'complete -c kite -f',
+        '',
+        '# Top-level commands (only before a subcommand is typed).',
+    ];
+    for (const name of model.commands) {
+        lines.push(`complete -c kite -n __fish_use_subcommand -a ${name} -d '${model.descriptions[name] ?? ''}'`);
+    }
+    lines.push('', '# Subcommands (only until one is chosen, capping depth at command → subcommand).');
+    for (const [cmd, subs] of Object.entries(model.subcommands)) {
+        // __fish_seen_subcommand_from is true anywhere the token appears on the
+        // line, so without the `and not …` guard `kite config set <TAB>` would keep
+        // re-offering config's subcommands. Excluding the subcommands themselves
+        // stops that once one has been typed.
+        const guard = `__fish_seen_subcommand_from ${cmd}; and not __fish_seen_subcommand_from ${subs.join(' ')}`;
+        for (const sub of subs) {
+            const desc = model.descriptions[`${cmd} ${sub}`] ?? '';
+            lines.push(`complete -c kite -n '${guard}' -a ${sub} -d '${desc}'`);
+        }
+    }
+    lines.push('', '# Global flags.');
+    for (const flag of model.globalFlags) {
+        lines.push(`complete -c kite -l ${flag.replace(/^--/, '')}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+// --- helpers ---------------------------------------------------------------
+function isShell(value) {
+    return SHELLS.includes(value);
+}
+/** Best-effort shell detection from $SHELL, e.g. "/usr/bin/fish" -> "fish". */
+function detectShell() {
+    const shell = process.env['SHELL'];
+    if (!shell)
+        return undefined;
+    const base = shell.split('/').pop();
+    return base && isShell(base) ? base : undefined;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,4 @@
+import type { CommandFactory } from './types.js';
+export declare const doctorCommands: CommandFactory;
+/** True when `current` is >= `floor`, comparing major.minor.patch numerically. */
+export declare function meetsFloor(current: string, floor: string): boolean;