@pungoyal/kite-cli 0.1.1 → 0.2.1

package/README.md

@@ -2,8 +2,10 @@
 
 [![CI](https://github.com/pungoyal/kite-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/pungoyal/kite-cli/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@pungoyal/kite-cli.svg)](https://www.npmjs.com/package/@pungoyal/kite-cli)
+[![Release](https://img.shields.io/github/v/release/pungoyal/kite-cli?sort=semver&color=blue)](https://github.com/pungoyal/kite-cli/releases/latest)
 [![Node.js](https://img.shields.io/badge/node-%E2%89%A5%2022.12-brightgreen.svg)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/pungoyal/kite-cli/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-kite--cli-2496ed.svg)](https://pungoyal.github.io/kite-cli/)
 
 An **unofficial**, secure, scriptable command-line interface for the [Zerodha Kite Connect](https://kite.trade/docs/connect/v3/) API.
 
@@ -57,8 +59,12 @@ kite login --env sandbox
 kite --env sandbox holdings
 ```
 
+**Running more than one Zerodha account?** See [Multiple accounts](#multiple-accounts).
+
 ## Usage
 
+The highlights are below; every command's full flag list is in [the command reference](https://pungoyal.github.io/kite-cli/commands).
+
 ### Portfolio
 
 ```bash
@@ -135,8 +141,29 @@ kite gtt place NSE:INFY --side SELL --quantity 10 \
   --trigger 1400 --price 1395 \
   --trigger 1700 --price 1695          # two-leg OCO
 kite gtt delete <id>
+
+kite alerts list                       # your price alerts
+kite alerts create "INDICES:NIFTY 50" --operator above --value 27000
+kite alerts get <uuid>                 # detail, incl. any attached order
+kite alerts history <uuid>             # when it has fired
+kite alerts delete <uuid> [<uuid>...]
 ```
 
+Alerts come in two kinds. A **simple** alert just notifies you when a price
+condition is met — it moves no money, so the kill switch and value cap do not
+apply. An **ATO** (Alert-Triggers-Order) alert places a real order when it fires,
+so creating one goes through the same confirmation, value cap and kill switch as
+`orders place`:
+
+```bash
+kite alerts create NSE:INFY --operator below --value 1400 \
+  --type ato --side BUY --quantity 10 --order-type LIMIT --price 1400
+```
+
+`--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.
 
 ### Scripting
@@ -169,9 +196,64 @@ 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.
 
+## Multiple accounts
+
+If you run more than one Zerodha account — your own, a family member's, an HUF — each
+gets a named **profile** with its own Kite Connect app credentials and its own daily
+session. Several accounts can be logged in at once; you choose which one a command
+targets.
+
+```bash
+kite profiles add huf                 # register a profile (create its Kite app first)
+kite --profile huf login              # log in to it (prompts for that app's key + secret)
+kite --profile huf holdings           # run any command against it
+kite profiles list                    # see every profile and its session status
+kite profiles use huf                 # make it the default for commands without --profile
+```
+
+`profiles add` can take the account's settings up front so `login` doesn't have to
+prompt for them: `--api-key <key>`, `--env sandbox` (the profile's environment,
+default `production`), and `--max-order-value <rupees>` (a per-profile cap). The API
+secret is never a flag — `login` always prompts for it.
+
+Selection is resolved fresh every run — there is no hidden "active account" that
+persists silently between commands. The target is chosen by, in order:
+
+1. `--profile <name>` on the command line
+2. the `KITE_PROFILE` environment variable
+3. the default set with `kite profiles use`
+4. otherwise the `default` profile
+
+`default` is your original single-account setup (nothing to migrate), and `sandbox`
+is a reserved profile — `--env sandbox` is just shorthand for `--profile sandbox`.
+
+Because targeting the wrong account is the costly mistake here, every money-moving
+confirmation shows the **verified account** it will hit — the user id returned by
+Kite, not just the label you chose:
+
+```
+Place BUY order
+  Account   Priya Sharma (XY9876) · profile huf
+  Symbol    NSE:INFY
+  …
+```
+
+Safety caps are per profile, inheriting the global setting when unset (an omitted cap
+never means "no cap"):
+
+```bash
+kite --profile huf config set trading.maxOrderValue 50000
+```
+
+For scripts and CI, `KITE_API_KEY` / `KITE_API_SECRET` / `KITE_ACCESS_TOKEN` still
+supply credentials directly. As a safeguard, naming a profile explicitly while those
+are set is refused rather than silently overridden.
+
+→ Full reference, including credential storage precedence and per-profile inheritance: [the configuration reference](https://pungoyal.github.io/kite-cli/configuration).
+
 ## Safety
 
-This tool spends real money, so the defaults are conservative.
+This tool spends real money, so the defaults are conservative. → Full model, including the order-tag reconciliation flow and why cancels/converts are exempt from the value cap: [the safety model](https://pungoyal.github.io/kite-cli/safety).
 
 **Confirmation.** Order commands render the resolved order — the actual instrument token, lot size, and computed value, not an echo of your flags — and wait for confirmation. That's deliberate: a flag echo can't catch "I typed the wrong symbol and it resolved to a different contract," which is the expensive mistake.
 
@@ -210,13 +292,13 @@ Automatic retries are restricted to `GET`/`HEAD` at the transport layer. `POST`,
 
 Your API secret is never accepted as a command-line argument, because argv is visible to any local process via `ps` and lands in shell history. It's prompted for, or read from the environment.
 
-**Redaction.** Access tokens are registered with a scrubber that runs over every log line, error message, and stack trace. The two paths that carry a token — the `Authorization` header and the WebSocket URL, where it's a query parameter — are covered explicitly and [tested](test/redact.test.ts).
+**Redaction.** Access tokens are registered with a scrubber that runs over every log line, error message, and stack trace. The two paths that carry a token — the `Authorization` header and the WebSocket URL, where it's a query parameter — are covered explicitly and [tested](https://github.com/pungoyal/kite-cli/blob/main/test/redact.test.ts).
 
 **TOTP.** This CLI will never ask for or store your 2FA seed. Storing it next to your API secret would collapse both authentication factors into one, which is exactly what the SEBI 2FA mandate exists to prevent. Login happens in your browser; the CLI only sees the resulting request token.
 
 **Supply chain.** 10 direct runtime dependencies, most of them zero-dependency. Published from GitHub Actions via [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) with OIDC — no long-lived publish token exists. Provenance attestation is generated automatically; verify it with `npm audit signatures`. All CI actions are pinned to full commit SHAs, and dependency lifecycle scripts are disabled.
 
-To report a vulnerability, see [SECURITY.md](SECURITY.md).
+To report a vulnerability, see [SECURITY.md](https://github.com/pungoyal/kite-cli/blob/main/SECURITY.md).
 
 ## Configuration
 
@@ -238,6 +320,12 @@ kite config path
 
 Config lives at `~/.config/kite/config.json` (`0600`). Override the location with `KITE_CONFIG_DIR`.
 
+`trading.*`, `apiKey`, and `env` can be set per profile by adding `--profile <name>`
+(see [Multiple accounts](#multiple-accounts)); the remaining keys are global. The
+account this invocation resolves to is selected by `--profile` / `KITE_PROFILE`.
+
+→ Every key and environment variable, with precedence: [the configuration reference](https://pungoyal.github.io/kite-cli/configuration).
+
 ## Things worth knowing about Kite
 
 - **Sessions expire at 6:00 AM IST daily.** This is a regulatory requirement and there's no way around it — you log in once per trading day. Refresh tokens exist in the API but are only issued to exchange-approved platforms, not individual subscribers.
@@ -248,6 +336,25 @@ Config lives at `~/.config/kite/config.json` (`0600`). Override the location wit
 - **Instruments are cached by `exchange:tradingsymbol`, never by token.** Exchanges reuse numeric instrument tokens after expiry, so a token-keyed cache silently resolves to the wrong contract after a rollover.
 - **Mutual funds are read-only** over the API — placing MF orders requires a bank debit that has no API path.
 
+→ Hit one of these? See [the troubleshooting guide](https://pungoyal.github.io/kite-cli/troubleshooting) for the symptom-first version.
+
+## Documentation
+
+This README covers installation and everyday usage. The full reference is a
+searchable site at **[pungoyal.github.io/kite-cli](https://pungoyal.github.io/kite-cli/)**:
+
+- [Safety model](https://pungoyal.github.io/kite-cli/safety) — the full layered safety model (kill
+  switch, value cap, confirmation escalation, order-tag reconciliation).
+- [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
+  for session expiry, rate limits, login issues, and more.
+- [Command reference](https://pungoyal.github.io/kite-cli/commands) — full flag-by-flag reference for
+  every command, generated from `--help`.
+- [Library API](https://pungoyal.github.io/kite-cli/api) — the library/programmatic API surface.
+
+The same pages are browsable as Markdown in [`docs/`](https://github.com/pungoyal/kite-cli/tree/main/docs).
+
 ## Library use
 
 The client is exported if you want it without the CLI:
@@ -279,7 +386,7 @@ npm run build
 
 ## Contributing
 
-Bug reports, ideas, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and the two non-negotiables (safety defaults and secret redaction), and [CHANGELOG.md](CHANGELOG.md) for release history. Security issues go through [SECURITY.md](SECURITY.md), never a public issue.
+Bug reports, ideas, and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/pungoyal/kite-cli/blob/main/CONTRIBUTING.md) for the development workflow and the two non-negotiables (safety defaults and secret redaction), and [CHANGELOG.md](https://github.com/pungoyal/kite-cli/blob/main/CHANGELOG.md) for release history. Security issues go through [SECURITY.md](https://github.com/pungoyal/kite-cli/blob/main/SECURITY.md), never a public issue.
 
 ## Disclaimer
 
@@ -289,4 +396,4 @@ Trading involves risk of financial loss. This software is provided as-is under t
 
 ## Licence
 
-[MIT](LICENSE)
+[MIT](https://github.com/pungoyal/kite-cli/blob/main/LICENSE)

package/dist/commands/alerts.d.ts

@@ -0,0 +1,12 @@
+import type { CommandFactory } from './types.js';
+/**
+ * Price alerts.
+ *
+ * Two shapes:
+ *   simple — fires a notification when a condition (e.g. LTP >= 27000) is met.
+ *            No order, no money moves; treated like a watchlist entry.
+ *   ato    — Alert-Triggers-Order: carries a basket that is placed as a real
+ *            order when the alert fires. Creating one is order placement in
+ *            disguise, so it gets the same safety treatment as `orders place`.
+ */
+export declare const alertCommands: CommandFactory;