Terminal agent guide

This page consolidates the operating rules that apply when another terminal agent drives either the Kite CLI or the Dhan CLI in a shared transcript. The rules are intentionally conservative — they trade speed for safety.

Operating rules

Treat all credentials, request tokens, access tokens, and Authorization headers as secrets. Never write them to a file.
Prefer --json --no-color for all agent-driven calls. Never parse the human table output — its format is not stabilised.
Avoid --verbose in shared logs. It can include low-level SDK details and raw broker error payloads.
Do not retry rapidly on broker API errors or rate-limit messages. Stop, report the error and exit code, and wait for operator direction. This is doubly important for Dhan static-IP / authorization errors — Dhan refuses to authorise repeated retried requests from a non-whitelisted IP.
The CLIs can place, modify, and cancel orders, GTT triggers, and alerts. Run these commands only from explicit operator-provided intent and payload files. Do not invent trades. Do not silently change quantities, prices, products, or symbols.
Mutual fund order placement is intentionally absent from Kite (the Connect v3 docs state mutual-fund order placement via API is unavailable due to payment requirements). Don’t work around this — never submit a mutual-fund order through raw or any other command.

Installation check

kite --help
kite auth status --json --no-color
kite update --json --no-color

dhan --help
dhan auth status --json --no-color
dhan update --json --no-color

Expected unauthenticated auth status shape (Kite):

{
  "apiKeyStored": false,
  "apiSecretStored": false,
  "accessTokenStored": false,
  "authenticated": false
}

Authentication

One-time app-credential setup:

# Kite
kite auth configure --api-key <api_key> --api-secret <api_secret> --json --no-color

# Dhan
dhan auth configure --client-id <dhan-client-id> --access-token <access-token> --json --no-color

Daily / refreshed session (Kite):

kite auth login --json --no-color          # opens browser, waits for callback on 127.0.0.1:17890
kite auth login --no-open --json --no-color # prints URL only — use only when the callback can reach this machine

Dhan token alternative flows (browser consent, TOTP, partner, renewal):

dhan auth login --client-id C --app-id A --app-secret S --no-open --json --no-color
dhan auth totp   --client-id C --pin 1234 --totp 567890 --json --no-color
dhan auth renew                                       --json --no-color

Check session state:

kite auth status --json --no-color
dhan auth status --json --no-color

Remove only the access token (keep credentials for the next login):

kite auth logout --json --no-color
dhan auth logout --json --no-color

Remove app credentials and the access token (fully wipe a profile):

kite auth logout --forget-app --json --no-color
dhan auth logout --forget-client-id --json --no-color

Read-only checks

# Kite
kite user profile --json --no-color
kite portfolio holdings --json --no-color
kite portfolio positions --json --no-color
kite orders list --json --no-color
kite trades list --json --no-color

# Dhan
dhan account profile --json --no-color
dhan account funds --json --no-color
dhan portfolio holdings --json --no-color
dhan portfolio positions --json --no-color
dhan orders list --json --no-color
dhan trades list --json --no-color

Live trading guardrails

For Dhan, every live-account-changing command requires --yes. Prefer a dry run first:

dhan orders place --file order.json --dry-run --json --no-color
dhan orders place --file order.json --yes --json --no-color

For Kite, every mutating command reads from an operator-supplied JSON file:

kite orders place --file .\order.json --json --no-color
kite orders modify regular <order-id> --file .\order-modify.json --json --no-color
kite orders cancel regular <order-id> --json --no-color

Before placement, inspect the local payload file and confirm that the relevant fields match operator intent. Stop and report if anything is unclear.

Common agent workflows

Workflow	Commands
Check whether work can proceed	`auth status --json --no-color` (proceed only when `authenticated` is `true`)
Resolve a trading symbol for historical data	`instruments download --exchange NSE --json --no-color` → `instruments search INFY --exchange NSE --json --no-color` → use the returned `instrument_token` with `historical`
Inspect today’s trading activity	`orders list`, `trades list`, `portfolio positions`
Quote a small basket	`kite quote ltp NSE:INFY NSE:RELIANCE --json --no-color` (keep batches modest)

Note the per-broker instrument rig: Kite uses exchange-prefixed symbols (NSE:INFY) for quotes and numeric instrument tokens for historical candles. Dhan uses numeric security IDs + --segment NSE_EQ for everything.

Recovery guide (Kite)

Symptom	Action
`Not authenticated` or exit code `2`	Run `kite auth status`; ask operator to `kite auth login` if no session.
`Kite session expired or is invalid`	Ask operator to refresh with `kite auth login`.
`Instrument cache is missing`	Run `kite instruments download`, optionally `--exchange`.
Invalid JSON or missing file for `--file`	Fix the local input and rerun once.
Kite API / permission / network / rate-limit error	Stop and report stderr + exit code. Do not loop retries.
Order / GTT / alert rejected by Kite	Stop and report. Do not auto-adjust parameters or retry with changed values.

Recovery guide (Dhan)

Symptom	Action
`Not authenticated` (exit code `3`)	Run `dhan auth status`; ask operator to `dhan auth configure` or use a login flow.
Authorization / static-IP error on live trading command	Stop. Do not retry. Tell the operator the static IP needs whitelisting on the Dhan side.
`Instrument cache is missing`	Run `dhan instruments download --segment NSE_EQ`.
Invalid JSON or missing file for `--file`	Fix the local input and rerun once.
Any non-2xx Dhan response (exit code `4`)	Stop and report stderr + exit code. Do not loop retries.

Transcript hygiene

Safe to share:

Commands without secrets.
JSON outputs from market / account calls when the operator permits account data in the transcript.
Exit code and stderr after redacting sensitive values.

Do not share:

--api-key, --api-secret, --request-token, --access-token, --client-id, or the Authorization header.
Raw --verbose SDK traces from authenticated commands.
Full local Credential Manager / Keychain / secret-tool dumps.

When in doubt, redact with placeholders such as <api_key>, <api_secret>, <request_token>, <access_token>, <client_id>.