# Zerodha Kite CLI Router

> Route natural-language trading/account queries to the correct `zerodha` CLI command with exact flags, validation constraints, and synonym mapping. Use when a user asks to view prices, place/modify/cancel orders, manage auth/profile/config, work with holdings/positions/margins/GTT/MF flows, or asks "which zerodha command should I run?"

- Skill: `modbender/zerodha-kite-cli-router` (Agent Skill)
- Install (CLI): `npx skillmds add modbender/zerodha-kite-cli-router`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/zerodha-kite-cli-router/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/zerodha-kite-cli-router

---


# Purpose

Translate a user query in plain English into one exact `zerodha` CLI command.

Do not invent commands or flags. Use only commands defined here.

# Bootstrap: CLI Installation

If the user asks to install/setup the CLI, or reports `zerodha: command not found`, route to an installer command first.

This is the only exception to "commands must start with `zerodha`".

Install commands:

- Linux/macOS (`curl`): `curl -fsSL https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.sh | sh`
- Linux/macOS (`wget`): `wget -qO- https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.sh | sh`
- Windows PowerShell: `irm https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.ps1 | iex`
- Windows CMD: `powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.ps1 | iex"`

Post-install verification command:

- `zerodha version`

# Global Rules

1. Always start commands with `zerodha` (except install/bootstrap commands in "Bootstrap: CLI Installation").
2. Prefer `--json` when the user asks for machine-readable output.
3. Respect global flags when provided:
   - `--profile <name>`
   - `--config <path>`
   - `--json`
   - `--debug`
4. Profile selection:
   - Most commands require an active profile (or explicit `--profile`).
   - If no profile is selected, use:
     `zerodha config profile use <name>`
5. Auth/session:
   - API data/order commands require an access token.
   - If missing, run `zerodha auth login ...`.
   - CLI auto-refreshes access token when refresh token exists.
6. Never guess missing required fields for write actions; ask for the missing values.
7. If OS is required for installation routing and missing, ask for only the OS (`linux`, `macos`, or `windows`).

# Login Flow (Multi-Message)

Use this flow when the user wants to authenticate and provides `api_key`, `api_secret`, and token across one or more messages.

Collected auth fields (can arrive in any order):

- `profile_name` (default to `default` if user does not specify)
- `api_key`
- `api_secret`
- one login mode:
  - `request_token_or_redirect_url`, or
  - `callback` (optional `callback_port`)

Rules:

1. Persist auth fields provided in earlier user messages during the same login task.
2. Ask only for missing required auth inputs for the next step.
3. Do not emit `zerodha auth login ...` until profile credentials are configured.
4. If `api_key` + `api_secret` are available and profile setup is needed, emit:
   `zerodha config profile add <profile_name> --api-key <key> --api-secret <secret> --set-active`
5. If user explicitly wants to update only one credential on an existing profile, emit:
   - `zerodha config profile set-api-key <profile_name> --api-key <key>`
   - `zerodha config profile set-api-secret <profile_name> --api-secret <secret>`
6. For token mode, emit:
   `zerodha auth login --request-token <token_or_redirect_url>`
7. For callback mode, emit:
   `zerodha auth login --callback [--callback-port <1-65535>]`
8. If multiple commands are needed, output only the next runnable command.

# Command Catalog

## Root utilities

- `zerodha version`
- `zerodha help [command]`
- `zerodha completion <shell>`

## Config profile

- `zerodha config profile add <name> --api-key <key> --api-secret <secret> [--set-active]`
  - Constraints: `<name>` required; `--api-key` and `--api-secret` required.
- `zerodha config profile set-api-key <name> --api-key <key>`
  - Constraints: `<name>`, `--api-key` required.
- `zerodha config profile set-api-secret <name> --api-secret <secret>`
  - Constraints: `<name>`, `--api-secret` required.
- `zerodha config profile list`
- `zerodha config profile use <name>`
  - Constraints: `<name>` must exist.
- `zerodha config profile remove <name>`
  - Constraints: `<name>` must exist.

## Auth

- `zerodha auth login --request-token <token_or_redirect_url>`
- `zerodha auth login --callback [--callback-port <1-65535>]`
  - Constraints:
    - Exactly one mode is required: `--request-token` OR `--callback`.
    - `--request-token` cannot be combined with `--callback`.
    - `--callback-port` allowed only with `--callback`.
    - `--callback-port` range: `1..65535`.
- `zerodha auth renew`
  - Constraints: refresh token must exist in profile.
- `zerodha auth logout`
- `zerodha auth revoke-refresh [--refresh-token <token>]`
  - If omitted, uses stored refresh token.

## Profile

- `zerodha profile show`
- `zerodha profile full`

## Quotes

- `zerodha quote get <EXCHANGE:SYMBOL> [EXCHANGE:SYMBOL...]`
  - Constraints: at least 1 instrument.
- `zerodha quote ltp <EXCHANGE:SYMBOL> [EXCHANGE:SYMBOL...]`
  - Constraints: at least 1 instrument.
- `zerodha quote ohlc <EXCHANGE:SYMBOL> [EXCHANGE:SYMBOL...]`
  - Constraints: at least 1 instrument.
- `zerodha quote historical --instrument-token <int> --interval <value> --from <time> --to <time> [--continuous] [--oi]`
  - Constraints:
    - `--instrument-token > 0`
    - `--interval` required
    - `--from` and `--to` required
    - time format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` or RFC3339
    - `--from <= --to`

## Instruments

- `zerodha instruments list [--exchange <EXCHANGE> | --all]`
  - Default (no flags): summary by exchange/type.
  - Constraints: `--exchange` and `--all` are mutually exclusive.
- `zerodha instruments mf`

## Orders (single order operations)

- `zerodha order place --exchange <EX> --symbol <SYM> --txn <BUY|SELL> --type <MARKET|LIMIT|SL|SL-M> --product <CNC|MIS|NRML|MTF> --qty <n> [--price <p>] [--trigger-price <p>] [--validity <DAY|IOC|TTL>] [--validity-ttl <min>] [--variety <v>] [--tag <t>]`
  - Constraints:
    - required: `--exchange --symbol --txn --type --product --qty`
    - `--qty > 0`
    - LIMIT requires `--price > 0`
    - SL requires both `--price > 0` and `--trigger-price > 0`
    - SL-M requires `--trigger-price > 0`
    - TTL validity requires `--validity-ttl > 0`
- `zerodha order modify --order-id <id> [fields...]`
  - Constraints:
    - `--order-id` required
    - At least one modifiable field required.
    - If provided, `--txn` must be BUY/SELL; `--type` must be MARKET/LIMIT/SL/SL-M; `--validity` must be DAY/IOC/TTL.
- `zerodha order cancel --order-id <id> [--variety <v>] [--parent-order-id <id>]`
  - Constraints: `--order-id` required.
- `zerodha order exit --order-id <id> [--variety <v>] [--parent-order-id <id>]`
  - Constraints: `--order-id` required.

## Orders (orderbook/trades)

- `zerodha orders list`
- `zerodha orders show --order-id <id>`
  - Constraints: `--order-id` required.
- `zerodha orders trades [--order-id <id>]`

## Positions

- `zerodha positions`
- `zerodha positions convert --exchange <EX> --symbol <SYM> --old-product <CNC|MIS|NRML|MTF> --new-product <CNC|MIS|NRML|MTF> --position-type <day|overnight> --txn <BUY|SELL> --qty <n>`
  - Constraints:
    - all flags above required
    - `--qty > 0`

## Holdings

- `zerodha holdings`
- `zerodha holdings auctions`
- `zerodha holdings auth-initiate [--type <equity|mf>] [--transfer-type <pre|post|off|gift>] [--exec-date YYYY-MM-DD] [--isin <isin> ...] [--qty <float> ...]`
  - Constraints:
    - if `--type` set, must be `equity|mf`
    - if `--transfer-type` set, must be `pre|post|off|gift`
    - if `--exec-date` set, format must be `YYYY-MM-DD`
    - `--isin` and `--qty` must have matching counts
    - each `--qty` must be `> 0`

## Margins

- `zerodha margins [--segment <all|equity|commodity>]`
- `zerodha margins order --exchange <EX> --symbol <SYM> --txn <BUY|SELL> --type <MARKET|LIMIT|SL|SL-M> --product <CNC|MIS|NRML|MTF> --qty <n> [--price <p>] [--trigger-price <p>] [--variety <v>] [--compact]`
- `zerodha margins basket --exchange <EX> --symbol <SYM> --txn <BUY|SELL> --type <MARKET|LIMIT|SL|SL-M> --product <CNC|MIS|NRML|MTF> --qty <n> [--price <p>] [--trigger-price <p>] [--variety <v>] [--compact] [--consider-positions]`
- `zerodha margins charges --exchange <EX> --symbol <SYM> --txn <BUY|SELL> --type <MARKET|LIMIT|SL|SL-M> --product <CNC|MIS|NRML|MTF> --qty <n> --avg-price <p> [--price <p>] [--trigger-price <p>] [--variety <v>] [--order-id <id>]`
  - Shared constraints for order/basket/charges:
    - required: `--exchange --symbol --txn --type --product --qty`
    - `--qty > 0`
    - LIMIT requires `--price > 0`
    - SL requires both `--price > 0` and `--trigger-price > 0`
    - SL-M requires `--trigger-price > 0`
  - Additional charges constraint:
    - `--avg-price > 0`

## GTT

- `zerodha gtt place [gtt flags]`
- `zerodha gtt modify --trigger-id <id> [gtt flags]`
- `zerodha gtt list`
- `zerodha gtt show --trigger-id <id>`
- `zerodha gtt delete --trigger-id <id>`

GTT common flags:
- `--exchange <EX> --symbol <SYM> --last-price <p> --txn <BUY|SELL> [--product <CNC|MIS|NRML|MTF>] [--type <single|two-leg>]`
- For `single` type:
  - `--trigger <p> --limit-price <p> --qty <q>`
- For `two-leg` type:
  - `--lower-trigger <p> --lower-limit-price <p> --lower-qty <q>`
  - `--upper-trigger <p> --upper-limit-price <p> --upper-qty <q>`

GTT constraints:
- `--exchange --symbol --txn` required
- `--last-price > 0`
- `--txn` in `BUY|SELL`
- `--product` in `CNC|MIS|NRML|MTF`
- `--trigger-id > 0` for show/modify/delete

## Mutual Funds

### MF Orders

- `zerodha mf orders place --symbol <SYM> --txn <BUY|SELL> [--qty <q>] [--amount <amt>] [--tag <t>]`
  - Constraints:
    - `--symbol` and `--txn` required
    - at least one of `--qty` or `--amount` must be `> 0`
    - `--qty` and `--amount` cannot be negative
- `zerodha mf orders list [--from YYYY-MM-DD --to YYYY-MM-DD]`
  - Constraints:
    - `--from` and `--to` must be provided together
    - date format: `YYYY-MM-DD`
- `zerodha mf orders show --order-id <id>`
  - Constraints: `--order-id` required
- `zerodha mf orders cancel --order-id <id>`
  - Constraints: `--order-id` required

### MF SIPs

- `zerodha mf sips place --symbol <SYM> --amount <amt> --instalments <n> --frequency <f> [--instalment-day <1..31>] [--initial-amount <amt>] [--trigger-price <p>] [--step-up <v>] [--sip-type <v>] [--tag <t>]`
  - Constraints:
    - required: `--symbol --amount --instalments --frequency`
    - `--amount > 0`, `--instalments > 0`
    - `--instalment-day` if provided must be in `1..31` (0 means not set)
    - `--initial-amount` and `--trigger-price` cannot be negative
- `zerodha mf sips modify --sip-id <id> [--amount <amt>] [--frequency <f>] [--instalment-day <1..31>] [--instalments <n>] [--step-up <v>] [--status <v>]`
  - Constraints:
    - `--sip-id` required
    - at least one modifiable field required
    - numeric fields cannot be negative
- `zerodha mf sips cancel --sip-id <id>`
  - Constraints: `--sip-id` required
- `zerodha mf sips list`
- `zerodha mf sips show --sip-id <id>`
  - Constraints: `--sip-id` required

### MF Holdings

- `zerodha mf holdings`
- `zerodha mf holdings show --isin <isin>`
  - Constraints: `--isin` required
- `zerodha mf holdings isins`

# Synonym Map

Use these mappings during intent parsing.

## Market data

- `quote` synonyms: `price`, `live price`, `current price`, `quote`, `snapshot`
- `ltp` synonyms: `ltp`, `last traded price`, `last price`, `tick`
- `ohlc` synonyms: `open high low close`, `ohlc`, `candle snapshot`
- `historical` synonyms: `history`, `candles`, `chart data`, `time series`

## Account and auth

- `profile` synonyms: `account details`, `user profile`, `my account`
- `login` synonyms: `authenticate`, `sign in`, `connect kite`
- `renew` synonyms: `refresh access token`, `renew token`
- `logout` synonyms: `sign out`, `clear session`

## Bootstrap

- `install cli` synonyms: `install zerodha cli`, `setup zerodha cli`, `command not found`, `zerodha not installed`

## Orders and tradebook

- `order place` synonyms: `buy`, `sell`, `place order`, `new order`, `execute trade`
- `order modify` synonyms: `edit order`, `change order`, `update order`
- `order cancel` synonyms: `cancel order`, `delete order`
- `order exit` synonyms: `square off order`, `exit order`
- `orders list` synonyms: `orderbook`, `all orders`
- `orders trades` synonyms: `tradebook`, `fills`, `executed trades`

## Portfolio

- `positions` synonyms: `open positions`, `net positions`
- `positions convert` synonyms: `convert position`, `change product type`
- `holdings` synonyms: `portfolio holdings`, `stocks held`, `demat holdings`
- `holdings auctions` synonyms: `auction holdings`, `auction eligible`

## Risk/margins

- `margins` synonyms: `available margin`, `used margin`, `funds`
- `margins order` synonyms: `margin required`, `order margin estimate`
- `margins basket` synonyms: `basket margin`, `combined margin`
- `margins charges` synonyms: `brokerage estimate`, `charges`, `fees`

## GTT

- `gtt` synonyms: `good till trigger`, `trigger order`, `price alert order`
- `gtt two-leg` synonyms: `oco`, `one cancels other`, `bracket trigger`

## Mutual funds

- `mf orders` synonyms: `mutual fund order`, `fund buy/sell`
- `mf sips` synonyms: `sip`, `systematic investment plan`
- `mf holdings` synonyms: `mutual fund portfolio`, `fund holdings`

# Routing Procedure

1. Detect whether this is an install/bootstrap request, login/auth bootstrap request, or a normal `zerodha` command request.
2. For install/bootstrap: pick the OS-specific installer command.
3. For login/auth bootstrap: follow "Login Flow (Multi-Message)" and emit only the next runnable command.
4. Otherwise detect intent domain using synonyms.
5. Pick the narrowest command path.
6. Extract required entities/flags.
7. Validate against constraints above.
8. If fields are missing, ask for only missing required inputs.
9. Output one runnable command string.

# Intent to Command Defaults

- If user asks generic "install zerodha cli":
  - Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.sh | sh`
  - Windows: `irm https://raw.githubusercontent.com/jatinbansal1998/zerodha-kite-cli/main/scripts/install.ps1 | iex`
- If user asks generic "login" and no auth fields are provided:
  - ask for `api_key` and `api_secret` first (profile defaults to `default` unless specified)
- If user provides `api_key` + `api_secret` but no token/mode:
  - emit profile setup command first, then ask for token mode (`--request-token` or `--callback`)
- If user asks generic "show my profile": use `zerodha profile show`.
- If user asks generic "show orders": use `zerodha orders list`.
- If user asks generic "show trades": use `zerodha orders trades`.
- If user asks generic "show positions": use `zerodha positions`.
- If user asks generic "show holdings": use `zerodha holdings`.
- If user asks generic "show margins": use `zerodha margins --segment all`.
- If user asks "list instruments" without exchange: use `zerodha instruments list`.

# Output Contract For Downstream Agents

When responding with a routed command, return:

1. `command`: exact runnable command (installer command for bootstrap, otherwise `zerodha ...`)
2. `why`: one-line reason
3. `missing`: required fields still missing (empty if none)