Zerodha

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?"

Jatin Bansal@jatinbansal1998

Install

openclaw skills install @jatinbansal1998/zerodha-kite

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

Always start commands with zerodha (except install/bootstrap commands in "Bootstrap: CLI Installation").
Prefer --json when the user asks for machine-readable output.
Respect global flags when provided:
- --profile <name>
- --config <path>
- --json
- --debug
Profile selection:
- Most commands require an active profile (or explicit --profile).
- If no profile is selected, use: zerodha config profile use <name>
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.
Never guess missing required fields for write actions; ask for the missing values.
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:

Persist auth fields provided in earlier user messages during the same login task.
Ask only for missing required auth inputs for the next step.
Do not emit zerodha auth login ... until profile credentials are configured.
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
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>
For token mode, emit: zerodha auth login --request-token <token_or_redirect_url>
For callback mode, emit: zerodha auth login --callback [--callback-port <1-65535>]
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 ] [--trigger-price ] [--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 ] [--trigger-price ] [--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 ] [--trigger-price ] [--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 [--price ] [--trigger-price ] [--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 --txn <BUY|SELL> [--product <CNC|MIS|NRML|MTF>] [--type <single|two-leg>]
For single type:
- --trigger --limit-price --qty <q>
For two-leg type:
- --lower-trigger --lower-limit-price --lower-qty <q>
- --upper-trigger --upper-limit-price --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 ] [--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

Detect whether this is an install/bootstrap request, login/auth bootstrap request, or a normal zerodha command request.
For install/bootstrap: pick the OS-specific installer command.
For login/auth bootstrap: follow "Login Flow (Multi-Message)" and emit only the next runnable command.
Otherwise detect intent domain using synonyms.
Pick the narrowest command path.
Extract required entities/flags.
Validate against constraints above.
If fields are missing, ask for only missing required inputs.
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:

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