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
• --config
• --json
• --debug
• Profile selection:
• Most commands require an active profile (or explicit --profile).
• If no profile is selected, use:

zerodha config profile use

• 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 --api-key --api-secret --set-active

• If user explicitly wants to update only one credential on an existing profile, emit:
• zerodha config profile set-api-key --api-key
• zerodha config profile set-api-secret --api-secret
• For token mode, emit:

zerodha auth login --request-token

• 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

Config profile

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

Auth

• zerodha auth login --request-token
• 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 ]
• If omitted, uses stored refresh token.

Profile

• zerodha profile show
• zerodha profile full

Quotes

• zerodha quote get [EXCHANGE:SYMBOL...]
• Constraints: at least 1 instrument.
• zerodha quote ltp [EXCHANGE:SYMBOL...]
• Constraints: at least 1 instrument.
• zerodha quote ohlc [EXCHANGE:SYMBOL...]
• Constraints: at least 1 instrument.
• zerodha quote historical --instrument-token --interval --from --to [--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 | --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 --symbol --txn --type --product --qty [--price

  ] [--trigger-price

  ] [--validity ] [--validity-ttl ] [--variety ] [--tag ]

• 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 [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 [--variety ] [--parent-order-id ]
• Constraints: --order-id required.
• zerodha order exit --order-id [--variety ] [--parent-order-id ]
• Constraints: --order-id required.

Orders (orderbook/trades)

• zerodha orders list
• zerodha orders show --order-id
• Constraints: --order-id required.
• zerodha orders trades [--order-id ]

Positions

• zerodha positions
• zerodha positions convert --exchange --symbol --old-product --new-product --position-type --txn --qty
• Constraints:
• all flags above required
• --qty > 0

Holdings

• zerodha holdings
• zerodha holdings auctions
• zerodha holdings auth-initiate [--type ] [--transfer-type ] [--exec-date YYYY-MM-DD] [--isin ...] [--qty ...]
• 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 ]
• zerodha margins order --exchange --symbol --txn --type --product --qty [--price

  ] [--trigger-price

  ] [--variety ] [--compact]

• zerodha margins basket --exchange --symbol --txn --type --product --qty [--price

  ] [--trigger-price

  ] [--variety ] [--compact] [--consider-positions]

• zerodha margins charges --exchange --symbol --txn --type --product --qty --avg-price

  [--price

  ] [--trigger-price

  ] [--variety ] [--order-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 [gtt flags]
• zerodha gtt list
• zerodha gtt show --trigger-id
• zerodha gtt delete --trigger-id

GTT common flags:

• --exchange --symbol --last-price

  --txn [--product ] [--type ]

• For single type:
• --trigger

  --limit-price

  --qty

• For two-leg type:
• --lower-trigger

  --lower-limit-price

  --lower-qty

• --upper-trigger

  --upper-limit-price

  --upper-qty

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 --txn [--qty ] [--amount ] [--tag ]
• 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
• Constraints: --order-id required
• zerodha mf orders cancel --order-id
• Constraints: --order-id required

MF SIPs

• zerodha mf sips place --symbol --amount --instalments --frequency [--instalment-day <1..31>] [--initial-amount ] [--trigger-price

  ] [--step-up ] [--sip-type ] [--tag ]

• 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 [--amount ] [--frequency ] [--instalment-day <1..31>] [--instalments ] [--step-up ] [--status ]
• Constraints:
• --sip-id required
• at least one modifiable field required
• numeric fields cannot be negative
• zerodha mf sips cancel --sip-id
• Constraints: --sip-id required
• zerodha mf sips list
• zerodha mf sips show --sip-id
• Constraints: --sip-id required

MF Holdings

• zerodha mf holdings
• zerodha mf holdings show --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)