kitecli 0.1.0b6

Kite Connect CLI — Multi-account Zerodha trading positions viewer

Kite Connect CLI (kitecli)

A multi-account Zerodha Kite Connect trading positions viewer with a beautiful interactive terminal user interface (TUI).

  ╦╔═╔═╗╦  ╦
  ╠╩╗║  ║  ║
  ╩ ╩╚═╝╩═╝╩
  Kite Connect CLI

---

Key Features

• 🔒 Local-Only Architecture: No server layer, no database, no cloud deployment. Your Zerodha API credentials and session tokens stay strictly on your local machine.
• 👥 Multi-Account: View and manage open positions and order books from multiple Zerodha accounts in a single consolidated screen.
• ⚡ Parallelized Requests: All network calls (positions, orders, initialization) are executed concurrently in a thread pool, keeping updates extremely fast and fluid.
• 🔑 Auto-Login: Session tokens are cached securely in ~/.kcli/sessions.json. Using your credentials (user_id, password, totp_secret), kcli automatically handles authentication and daily OTP generation in the background.
• 🌐 Proxy Routing: Map different HTTP/HTTPS proxies to each account individually to comply with Zerodha API connection requirements.
• 📊 Interactive TUI Dashboard: Launch the live dashboard to view:
  • Consolidated active positions with soft-color styling.
  • Live indices panel (NIFTY 50, SENSEX, and INDIA VIX).
  • Info Pane to view Pending Orders, Executed Orders, or Option Chains (F1, F2, F3).
  • Active logs with color-coded alerts and focus highlights for simple navigation.
• 📡 Live WebSocket Streaming: Position LTPs/P&L, the market indices panel, and the option chain all update in real time over the Kite WebSocket (KiteTicker) — no manual refresh needed. Order fills push an instant positions/orders re-sync.
• 🎯 Primary Streaming Account: Market data (indices, option chain, and position prices) is streamed through a single designated primary account instead of redundantly subscribing on every account. Mark one account with primary: true in the config, or let kcli auto-select the first streaming-capable account. Per-account positions, orders, and P&L remain fully independent.
• 🩺 Streaming Diagnostics: On startup, kcli probes each account's WebSocket authentication. Accounts whose api_key lacks an active streaming subscription (REST works but the ticker is rejected with 403) are reported clearly and skipped, preventing reconnect-error storms.

---

Installation

Install the package via pip:

pip install kitecli

(For local development or installing from source):

git clone https://github.com/chandu389/kitecli.git
cd kitecli
pip install -e .

---

Quick Start

1. Initialize Configuration

Create a default configuration template:

kcli config --init

This generates a config file at ~/.kcli/config.yaml.

2. Configure Accounts

Open ~/.kcli/config.yaml in your text editor and add your accounts. Include your login credentials and TOTP secrets to enable auto-login:

accounts:
  - name: "Account 1"
    api_key: "your_api_key_1"
    api_secret: "your_api_secret_1"
    user_id: "your_zerodha_user_id_1"
    password: "your_zerodha_password_1"
    totp_secret: "your_totp_secret_1"
    proxy: "http://username:password@ip:port"  # Optional per-account proxy
    primary: true                              # Optional: use this account for streaming

  - name: "Account 2"
    api_key: "your_api_key_2"
    api_secret: "your_api_secret_2"
    user_id: "your_zerodha_user_id_2"
    password: "your_zerodha_password_2"
    totp_secret: "your_totp_secret_2"
    proxy: "http://username:password@ip:port"

The primary flag (optional) designates which account streams the shared market data — the indices panel, option chain, and position prices. Because an instrument's price is the same regardless of which account holds it, streaming it once through a single primary account avoids redundant duplicate subscriptions. If primary is omitted (or the flagged account can't stream), kcli automatically falls back to the first streaming-capable account.

Note on streaming: Live WebSocket streaming requires that the account's Kite Connect app has an active streaming subscription. An account can read positions over REST yet still be rejected by the WebSocket (403) if its app lacks streaming access. kcli detects this on startup and reports it in the Status Logs.

3. Log In & Authenticate

Authenticate and start your sessions (auto-login will run in the background for accounts with complete credentials):

kcli init

4. Run commands

• Interactive Dashboard:

  kcli live
  

• Positions Snapshot:

  kcli positions
  

• Status Check:

  kcli status
  

---

CLI Command Reference

Command	Description
kcli live	Launch the interactive live TUI dashboard
kcli init	Initialize and authenticate account sessions
kcli positions	Print a quick snapshot of active positions
kcli status	Check authentication status of configured accounts
kcli config --init	Generate a default configuration file
kcli config --show	Display current configuration (secrets masked)
kcli config --path	Print the configuration file path

---

License

MIT