@pungoyal/kite-cli 0.3.0 → 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:
 

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;

package/dist/commands/doctor.js

@@ -0,0 +1,190 @@
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { getSecret, keyringAvailable } from '../core/credentials.js';
+import { ExitCode } from '../core/errors.js';
+import { configFile } from '../core/paths.js';
+import { isExpired, timeUntilExpiry } from '../core/session.js';
+import { renderKeyValue } from '../output/table.js';
+export const doctorCommands = (program, run) => {
+    program
+        .command('doctor')
+        .description('Run offline health checks on your configuration, credentials, and session')
+        .action(run(doctor));
+};
+async function doctor(ctx) {
+    const checks = [
+        checkNode(),
+        await checkConfigFile(),
+        await checkKeyring(),
+        await checkCredentials(ctx),
+        checkSession(ctx),
+        await checkCallbackPort(ctx),
+    ];
+    const worst = checks.some((c) => c.status === 'fail')
+        ? 'fail'
+        : checks.some((c) => c.status === 'warn')
+            ? 'warn'
+            : 'ok';
+    if (ctx.io.json) {
+        ctx.io.writeJson({
+            ok: worst !== 'fail',
+            profile: ctx.profile.name,
+            env: ctx.env,
+            checks: checks.map((c) => ({
+                name: c.name,
+                status: c.status,
+                detail: c.detail,
+                ...(c.hint ? { hint: c.hint } : {}),
+            })),
+        });
+        if (worst === 'fail')
+            process.exitCode = ExitCode.Failure;
+        return;
+    }
+    const { io } = ctx;
+    const rows = [];
+    for (const check of checks) {
+        rows.push([`${icon(io, check.status)} ${check.name}`, check.detail]);
+        if (check.hint)
+            rows.push(['', io.dim(check.hint)]);
+    }
+    io.line(renderKeyValue(io, rows));
+    io.note('');
+    if (worst === 'fail') {
+        io.error('Some checks failed. See the hints above.');
+        process.exitCode = ExitCode.Failure;
+    }
+    else if (worst === 'warn') {
+        io.warn('All essential checks passed, with warnings.');
+        io.info('Run `kite whoami` to confirm the session is live on Kite (doctor is offline).');
+    }
+    else {
+        io.success('Everything looks healthy.');
+        io.info('Run `kite whoami` to confirm the session against Kite (doctor is offline).');
+    }
+}
+// --- individual checks -----------------------------------------------------
+/** Node must meet the floor declared in package.json `engines`. */
+function checkNode() {
+    const current = process.versions.node;
+    const floor = '22.12.0';
+    return meetsFloor(current, floor)
+        ? { name: 'Node runtime', status: 'ok', detail: `v${current}` }
+        : {
+            name: 'Node runtime',
+            status: 'fail',
+            detail: `v${current} is below the required v${floor}`,
+            hint: `Upgrade to Node ${floor} or newer.`,
+        };
+}
+async function checkConfigFile() {
+    const path = configFile();
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // No file is fine — defaults apply until the first `config set`.
+            return { name: 'Config file', status: 'ok', detail: 'none yet (using built-in defaults)' };
+        }
+        return { name: 'Config file', status: 'fail', detail: `cannot read ${path}`, hint: err.message };
+    }
+    // Windows models permissions through ACLs, not the POSIX mode bits, so the
+    // 0600 assertion only makes sense off Windows.
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        const mode = (info.mode & 0o777).toString(8).padStart(3, '0');
+        return {
+            name: 'Config file',
+            status: 'warn',
+            detail: `${path} is mode ${mode} (world- or group-readable)`,
+            hint: `Tighten it: chmod 600 ${path}`,
+        };
+    }
+    return { name: 'Config file', status: 'ok', detail: path };
+}
+async function checkKeyring() {
+    return (await keyringAvailable())
+        ? { name: 'Credential store', status: 'ok', detail: 'OS keyring available' }
+        : {
+            name: 'Credential store',
+            status: 'warn',
+            detail: 'no OS keyring — falling back to an encrypted file',
+            hint: 'Set KITE_CREDENTIALS_PASSPHRASE to enable the encrypted file store on this machine.',
+        };
+}
+async function checkCredentials(ctx) {
+    if (ctx.env === 'sandbox') {
+        return { name: 'API secret', status: 'ok', detail: 'using the public sandbox credentials' };
+    }
+    const secret = await getSecret('api_secret', { scope: ctx.credentialScope });
+    return secret
+        ? { name: 'API secret', status: 'ok', detail: `stored (${secret.backend})` }
+        : {
+            name: 'API secret',
+            status: 'warn',
+            detail: 'not stored',
+            hint: 'Run `kite login` (or set KITE_API_SECRET) so re-login and signing work.',
+        };
+}
+/** Cached session metadata only — liveness against Kite is `kite whoami`'s job. */
+function checkSession(ctx) {
+    const loginHint = ctx.profile.name === 'default' ? 'Run `kite login`.' : `Run \`kite --profile ${ctx.profile.name} login\`.`;
+    if (!ctx.session) {
+        return { name: 'Session', status: 'warn', detail: 'not logged in', hint: loginHint };
+    }
+    if (isExpired(ctx.session)) {
+        return {
+            name: 'Session',
+            status: 'warn',
+            detail: 'expired (Kite invalidates tokens at 06:00 IST daily)',
+            hint: loginHint,
+        };
+    }
+    const who = ctx.session.userName ?? ctx.session.userId;
+    return { name: 'Session', status: 'ok', detail: `${who}, expires in ${timeUntilExpiry(ctx.session)}` };
+}
+async function checkCallbackPort(ctx) {
+    const port = ctx.config.redirectPort;
+    const free = await portIsFree(port);
+    return free
+        ? { name: 'Login callback port', status: 'ok', detail: `127.0.0.1:${port} is free` }
+        : {
+            name: 'Login callback port',
+            status: 'warn',
+            detail: `127.0.0.1:${port} is in use`,
+            hint: 'Another process holds the callback port; `kite login` may fail until it frees, or change redirectPort.',
+        };
+}
+// --- helpers ---------------------------------------------------------------
+function icon(io, status) {
+    switch (status) {
+        case 'ok':
+            return io.green('✓');
+        case 'warn':
+            return io.yellow('!');
+        case 'fail':
+            return io.red('✗');
+    }
+}
+/** True when `current` is >= `floor`, comparing major.minor.patch numerically. */
+export function meetsFloor(current, floor) {
+    const c = current.split('.').map((n) => Number.parseInt(n, 10));
+    const f = floor.split('.').map((n) => Number.parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const a = c[i] ?? 0;
+        const b = f[i] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/** Bind-and-release probe: can `kite login` open its loopback callback server? */
+function portIsFree(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}

package/dist/commands/register.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { Runner } from './types.js';
+/**
+ * Command wiring, factored out of run.ts so there is a single source of truth
+ * for the command tree.
+ *
+ * run() consumes this to build the live program; `kite completion` consumes it
+ * with a no-op runner to introspect command and flag names for shell
+ * completions. Keeping both on the same registration path means a new command
+ * or flag is completable the moment it is added, with nothing to keep in sync.
+ */
+/**
+ * Attach the global options every command inherits. Split from the name /
+ * version / output wiring in run.ts, which is invocation-specific, so an
+ * introspection-only program can still enumerate the same global flags.
+ */
+export declare function applyGlobalOptions(program: Command): Command;
+/**
+ * Register every command group on `program`, grouped for a readable `--help`.
+ *
+ * The `run` runner wraps each handler with context construction and error
+ * reporting in the real CLI; completion passes a no-op that only needs the
+ * command definitions, not their behaviour.
+ */
+export declare function registerCommands(program: Command, run: Runner): Promise<void>;

package/dist/commands/register.js

@@ -0,0 +1,75 @@
+/**
+ * Command wiring, factored out of run.ts so there is a single source of truth
+ * for the command tree.
+ *
+ * run() consumes this to build the live program; `kite completion` consumes it
+ * with a no-op runner to introspect command and flag names for shell
+ * completions. Keeping both on the same registration path means a new command
+ * or flag is completable the moment it is added, with nothing to keep in sync.
+ */
+/**
+ * Attach the global options every command inherits. Split from the name /
+ * version / output wiring in run.ts, which is invocation-specific, so an
+ * introspection-only program can still enumerate the same global flags.
+ */
+export function applyGlobalOptions(program) {
+    return (program
+        .option('--json', 'Emit JSON instead of formatted tables')
+        .option('--color <when>', 'Colour output: auto, always, or never')
+        // Deliberately no `-q` short form: it would shadow `-q, --quantity` on the
+        // order and GTT subcommands, which is typed far more often than --quiet.
+        .option('--quiet', 'Suppress informational messages')
+        .option('--debug', 'Print redacted request diagnostics to stderr')
+        .option('--env <env>', 'Environment: production or sandbox')
+        .option('--profile <name>', 'Account profile to use (see `kite profiles`)')
+        .option('-y, --yes', 'Skip confirmation prompts (use with care)')
+        .option('--dry-run', 'Show what would happen without sending anything to Kite'));
+}
+/**
+ * Register every command group on `program`, grouped for a readable `--help`.
+ *
+ * The `run` runner wraps each handler with context construction and error
+ * reporting in the real CLI; completion passes a no-op that only needs the
+ * command definitions, not their behaviour.
+ */
+export async function registerCommands(program, run) {
+    // Imported here rather than at module top so a single invocation only pays for
+    // parsing the command modules once run() (or completion) actually asks for
+    // them, not on every `import` of this file.
+    const { authCommands } = await import('./auth.js');
+    const { profileCommands } = await import('./profiles.js');
+    const { portfolioCommands } = await import('./portfolio.js');
+    const { marketCommands } = await import('./market.js');
+    const { orderCommands } = await import('./orders.js');
+    const { gttCommands } = await import('./gtt.js');
+    const { alertCommands } = await import('./alerts.js');
+    const { marginCommands } = await import('./margins.js');
+    const { mfCommands } = await import('./mf.js');
+    const { watchCommands } = await import('./watch.js');
+    const { configCommands } = await import('./config.js');
+    const { doctorCommands } = await import('./doctor.js');
+    const { completionCommands } = await import('./completion.js');
+    // commandsGroup applies to every command registered after it, so the group
+    // is set immediately before each block. With ~25 commands this is the
+    // difference between a readable --help and a wall of text.
+    program.commandsGroup('Account:');
+    authCommands(program, run);
+    profileCommands(program, run);
+    program.commandsGroup('Portfolio:');
+    portfolioCommands(program, run);
+    program.commandsGroup('Mutual funds:');
+    mfCommands(program, run);
+    program.commandsGroup('Market data:');
+    marketCommands(program, run);
+    program.commandsGroup('Trading:');
+    orderCommands(program, run);
+    gttCommands(program, run);
+    alertCommands(program, run);
+    marginCommands(program, run);
+    program.commandsGroup('Streaming:');
+    watchCommands(program, run);
+    program.commandsGroup('Settings:');
+    configCommands(program, run);
+    doctorCommands(program, run);
+    completionCommands(program, run);
+}

package/dist/core/auth.d.ts

@@ -59,6 +59,15 @@ export declare function waitForCallback(opts: CallbackServerOptions): {
     close: () => void;
 };
 export declare function redirectUrlFor(port: number, path: string): string;
+/**
+ * Copy text to the OS clipboard, returning whether it succeeded.
+ *
+ * Like {@link openBrowser}, the text is piped to a fixed binary's stdin — never
+ * through a shell and never as an argv element — so a URL's `&`/`=` cannot
+ * become word-splitting or command injection. On Linux there is no single
+ * clipboard tool, so we try the common ones in turn (Wayland first, then X11).
+ */
+export declare function copyToClipboard(text: string): Promise<boolean>;
 /**
  * Open a URL in the user's default browser.
  *

package/dist/core/auth.js

@@ -175,6 +175,45 @@ function escapeHtml(value) {
 export function redirectUrlFor(port, path) {
     return `http://127.0.0.1:${port}${path}`;
 }
+/**
+ * Copy text to the OS clipboard, returning whether it succeeded.
+ *
+ * Like {@link openBrowser}, the text is piped to a fixed binary's stdin — never
+ * through a shell and never as an argv element — so a URL's `&`/`=` cannot
+ * become word-splitting or command injection. On Linux there is no single
+ * clipboard tool, so we try the common ones in turn (Wayland first, then X11).
+ */
+export async function copyToClipboard(text) {
+    const candidates = process.platform === 'darwin'
+        ? [['pbcopy', []]]
+        : process.platform === 'win32'
+            ? [['clip', []]]
+            : [
+                ['wl-copy', []],
+                ['xclip', ['-selection', 'clipboard']],
+                ['xsel', ['--clipboard', '--input']],
+            ];
+    for (const [command, args] of candidates) {
+        if (await pipeToCommand(command, args, text))
+            return true;
+    }
+    return false;
+}
+/** Spawn `command`, write `text` to its stdin, resolve true on a clean exit. */
+function pipeToCommand(command, args, text) {
+    return import('node:child_process').then(({ spawn }) => new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'], shell: false });
+            child.on('error', () => resolve(false));
+            child.on('close', (code) => resolve(code === 0));
+            child.stdin.on('error', () => resolve(false));
+            child.stdin.end(text);
+        }
+        catch {
+            resolve(false);
+        }
+    }));
+}
 /**
  * Open a URL in the user's default browser.
  *

package/dist/core/client.js

@@ -177,7 +177,14 @@ export class KiteClient {
             return new KiteCliError('Cancelled.', ExitCode.Aborted);
         }
         const message = err instanceof Error ? err.message : String(err);
-        return new NetworkError(`Could not reach Kite: ${redactString(message)}`, 'Check your network connection.');
+        // undici's fetch wraps the actual failure (ECONNRESET, ENOTFOUND, a TLS
+        // error, ...) in `cause` and sets `message` to the unhelpful constant
+        // "fetch failed" — surface the cause too, or every transient network
+        // problem looks identical and undebuggable.
+        const cause = err instanceof Error ? err.cause : undefined;
+        const causeMessage = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : undefined;
+        const detail = causeMessage && causeMessage !== message ? `${message}: ${causeMessage}` : message;
+        return new NetworkError(`Could not reach Kite: ${redactString(detail)}`, 'Check your network connection.');
     }
     handleResponse(response, text, schema, url) {
         let payload;

package/dist/run.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { Command, CommanderError } from 'commander';
+import { applyGlobalOptions, registerCommands } from './commands/register.js';
 import { createContext } from './context.js';
 import { AbortedError, ExitCode, KiteCliError } from './core/errors.js';
 import { redactString } from './core/redact.js';
@@ -36,16 +37,6 @@ export async function run(opts = {}) {
         .name('kite')
         .description('Unofficial command-line interface for the Zerodha Kite Connect API (not affiliated with Zerodha)')
         .version(VERSION, '-v, --version')
-        .option('--json', 'Emit JSON instead of formatted tables')
-        .option('--color <when>', 'Colour output: auto, always, or never')
-        // Deliberately no `-q` short form: it would shadow `-q, --quantity` on the
-        // order and GTT subcommands, which is typed far more often than --quiet.
-        .option('--quiet', 'Suppress informational messages')
-        .option('--debug', 'Print redacted request diagnostics to stderr')
-        .option('--env <env>', 'Environment: production or sandbox')
-        .option('--profile <name>', 'Account profile to use (see `kite profiles`)')
-        .option('-y, --yes', 'Skip confirmation prompts (use with care)')
-        .option('--dry-run', 'Show what would happen without sending anything to Kite')
         .showHelpAfterError('(run `kite --help` for usage)')
         .configureOutput({
         writeOut: (str) => (opts.streams?.stdout ?? process.stdout).write(str),
@@ -54,6 +45,7 @@ export async function run(opts = {}) {
         // Throw instead of calling process.exit, so `run()` stays testable and
         // always returns its exit code.
         .exitOverride();
+    applyGlobalOptions(program);
     /** Wraps a handler with context construction and error reporting. */
     const withContext = (handler) => async (...args) => {
         // Commander passes (…arguments, options, command).
@@ -68,40 +60,11 @@ export async function run(opts = {}) {
             exitCode = reportError(err, ctx.io);
         }
     };
-    // Registered lazily so a bare `kite quote` never pays to import the
-    // dashboard renderer, the ticker, or the prompt library.
-    const { authCommands } = await import('./commands/auth.js');
-    const { profileCommands } = await import('./commands/profiles.js');
-    const { portfolioCommands } = await import('./commands/portfolio.js');
-    const { marketCommands } = await import('./commands/market.js');
-    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
-    // is set immediately before each block. With ~25 commands this is the
-    // difference between a readable --help and a wall of text.
-    program.commandsGroup('Account:');
-    authCommands(program, withContext);
-    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:');
-    configCommands(program, withContext);
+    // Registered through the shared registration path (see commands/register.ts)
+    // so run() and `kite completion` build the exact same command tree. Modules
+    // are still imported lazily inside registerCommands, so a bare `kite quote`
+    // never pays to parse the dashboard renderer or the ticker up front.
+    await registerCommands(program, withContext);
     program.addHelpText('after', `
 Examples:
   $ kite login                                  Authenticate and store a session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pungoyal/kite-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Unofficial command-line interface for the Zerodha Kite Connect API — not affiliated with or endorsed by Zerodha",
   "keywords": [
     "zerodha",