@cryptocom/cdcx-cli 1.2.2

package/README.md

@@ -0,0 +1,394 @@
+# cdcx
+
+A CLI, MCP server, and terminal dashboard for the [Crypto.com Exchange API](https://exchange-docs.crypto.com/exchange/v1/rest-ws/index.html). Single binary, zero runtime dependencies.
+
+86 REST endpoints across 10 API groups, dynamically generated from the Crypto.com Exchange OpenAPI spec. Real-time WebSocket streaming. Full-screen TUI dashboard. Paper trading. Works as a standalone CLI, an MCP tool server for AI agents, or an interactive terminal.
+
+> **Caution:** This software interacts with the live Crypto.com Exchange and can execute real financial transactions. Test with `cdcx paper` before using real funds.
+
+## Install
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/crypto-com/cdcx-cli/main/install.sh | sh
+```
+
+**From source:**
+
+```bash
+cargo install --git https://github.com/crypto-com/cdcx-cli.git --bin cdcx
+```
+
+---
+
+## Why cdcx?
+
+### For AI Agents
+
+Every response is structured JSON. 86 MCP tools with typed parameters, enum validation, safety enforcement, and schema discovery — all generated from the OpenAPI spec at runtime. Your LLM can trade, analyze markets, and manage positions without custom tooling.
+
+```bash
+cdcx mcp --services market,account,trade
+```
+
+```json
+{
+  "mcpServers": {
+    "cdcx": {
+      "command": "npx",
+      "args": ["-y", "@cryptocom/cdcx-cli@latest", "mcp", "--services", "market,account,trade"]
+    }
+  }
+}
+```
+
+Compatible with Claude Code, Cursor, Claude Desktop, Codex, Github Copilot, Gemini CLI, and other MCP clients. Includes 13 agent skill files in `skills/` for guided workflows.
+
+Things you can ask your AI agent:
+
+> *"What's the current BTC price and 24h volume?"*
+
+> *"Paper trade BTC for a few rounds and show me the P&L"*
+
+> *"Place an OTOCO bracket on BTC_USDT: entry at 70000, stop-loss at 65000, take-profit at 75000"*
+
+### For the Command Line
+
+Every endpoint is a command. `--help` on everything. `--dry-run` to preview. `--output json` for scripting. Tab completion. Profiles for multi-account.
+
+```bash
+cdcx market ticker BTC_USDT -o table
+cdcx trade order BUY BTC_USDT 0.001 --dry-run
+cdcx stream ticker BTC_USDT ETH_USDT
+cdcx paper buy BTC_USDT --quantity 0.01
+```
+
+### For the Dashboard
+
+Full-screen terminal trading interface. 6 tabs, real-time streaming, candlestick charts, heatmap mode, split screen, order workflows. Zero flicker.
+
+```bash
+cdcx tui
+```
+
+Press `p` to toggle paper mode. Press `O` for OTOCO bracket orders. Press `?` for all shortcuts.
+
+---
+
+## Quick Start
+
+Public market data works without credentials:
+
+```bash
+cdcx market ticker BTC_USDT -o table
+cdcx market book BTC_USDT --depth 10 -o table
+cdcx market candlestick BTC_USDT --timeframe 1h -o table
+```
+
+Paper trading works without credentials:
+
+```bash
+cdcx paper init --balance 50000
+cdcx paper buy BTC_USDT --quantity 0.01
+cdcx paper positions
+cdcx paper balance
+```
+
+For trading, set credentials:
+
+```bash
+export CDCX_API_KEY="your-key"
+export CDCX_API_SECRET="your-secret"
+cdcx account summary
+```
+
+---
+
+## MCP Server
+
+Expose the Exchange API as MCP tools for AI agents:
+
+```bash
+cdcx mcp --services market,account,trade
+cdcx mcp --services all --allow-dangerous
+```
+
+Service groups (MCP): `market`, `account`, `trade`, `advanced`, `margin`, `staking`, `funding`, `fiat`, `otc`, `stream`, `all`
+
+> **Note:** `account` also exposes historical endpoints (orders, trades, transactions). `funding` covers wallet deposit/withdrawal endpoints. Paper trading is a CLI-only feature and has no MCP tools.
+
+### Safety Model
+
+| Tier | Behavior | Examples |
+|------|----------|---------|
+| **read** | No confirmation | `market ticker`, `market book` |
+| **sensitive_read** | No confirmation | `account summary`, `trade open-orders` |
+| **mutate** | Requires `acknowledged: true` | `trade order`, `trade cancel` |
+| **dangerous** | Requires `--allow-dangerous` | `trade cancel-all`, `wallet withdraw` |
+
+### Agent Skills
+
+13 skill files in `skills/` covering:
+
+| Skill | Purpose |
+|-------|---------|
+| `cdcx-market-intel` | Market analysis and price discovery |
+| `cdcx-portfolio-intel` | Portfolio analysis and risk assessment |
+| `cdcx-execution` | Order placement with safety checks |
+| `cdcx-advanced` | OCO, OTO, OTOCO contingency orders |
+| `cdcx-paper-strategy` | Paper trading strategy testing |
+| `cdcx-wallet-ops` | Deposits, withdrawals, network management |
+| `cdcx-auth-setup` | Credential configuration |
+| `cdcx-autonomy-levels` | Safety tier configuration |
+| `cdcx-check-balance` | Balance and credential verification |
+| `cdcx-place-limit-order` | Limit order workflow with preflight checks |
+| `cdcx-isolated-margin` | Isolated margin trading (equity/RWA perpetuals) |
+| `recipe-morning-brief` | Daily market briefing workflow |
+| `recipe-emergency-flatten` | Emergency position flattening |
+
+### Plugin Installation
+
+Install cdcx as a one-click plugin from your AI coding tool's marketplace.
+
+**Claude Code:**
+
+```bash
+claude plugin marketplace add crypto-com/cdcx-cli
+claude plugin install cdcx-cli@cdcx-cli
+```
+
+**Codex CLI:**
+
+```bash
+codex plugin marketplace add crypto-com/cdcx-cli
+```
+
+**Other:** Open Settings > MCP Servers, add:
+
+```json
+{
+  "cdcx": {
+    "command": "npx",
+    "args": ["-y", "@cryptocom/cdcx-cli@latest", "mcp", "--services", "market"]
+  }
+}
+```
+
+To expand services beyond market data, update the `--services` flag:
+
+```
+market,trade,account          # Trading agent
+market,trade,account,advanced # With OCO/OTOCO
+all --allow-dangerous         # Full access (withdrawals enabled)
+```
+
+---
+
+## CLI Reference
+
+### Market Data (public)
+
+```bash
+cdcx market ticker                     # All tickers
+cdcx market ticker BTC_USDT            # Single instrument
+cdcx market book BTC_USDT --depth 20   # Order book
+cdcx market trades BTC_USDT            # Recent trades
+cdcx market candlestick BTC_USDT --timeframe 1h
+cdcx market instruments                # All instruments
+```
+
+### Trading (requires auth)
+
+```bash
+cdcx trade order BUY BTC_USDT 0.001 --type LIMIT --price 50000
+cdcx trade open-orders
+cdcx trade cancel --order-id ORDER_ID
+cdcx trade cancel-all
+```
+
+### Advanced Orders
+
+```bash
+cdcx advanced create-oto --instrument-name BTC_USDT ...
+cdcx advanced create-otoco --instrument-name BTC_USDT ...
+cdcx advanced open-orders
+```
+
+### Paper Trading
+
+Local paper trading engine with live market prices. No auth required.
+
+```bash
+cdcx paper init --balance 50000        # Create account
+cdcx paper buy BTC_USDT --quantity 0.01   # Market buy
+cdcx paper sell BTC_USDT --quantity 0.01  # Market sell
+cdcx paper buy BTC_USDT --quantity 0.01 --price 65000  # Limit buy
+cdcx paper positions                   # Portfolio + P&L
+cdcx paper history                     # Trade history
+cdcx paper balance                     # Account balance
+cdcx paper reset --balance 100000      # Reset account
+```
+
+### Streaming (WebSocket)
+
+```bash
+cdcx stream ticker BTC_USDT ETH_USDT  # Real-time tickers
+cdcx stream book BTC_USDT             # Order book updates
+cdcx stream trades BTC_USDT           # Trade executions
+cdcx stream orders                    # Your order updates (auth)
+cdcx stream positions                 # Position changes (auth)
+```
+
+### Account
+
+```bash
+cdcx account summary                   # Balances
+cdcx account positions                 # Open positions
+cdcx trade fee-rate                    # Fee rates
+```
+
+### History / Wallet / Staking / Fiat / Margin
+
+```bash
+cdcx history orders                    cdcx wallet deposit-address --currency BTC
+cdcx history trades                    cdcx wallet deposit-history
+cdcx history transactions              cdcx wallet withdrawal-history
+cdcx staking instruments               cdcx fiat accounts
+cdcx staking positions                 cdcx margin transfer --dry-run
+```
+
+---
+
+## Interactive Dashboard
+
+```bash
+cdcx tui                               # Launch
+cdcx tui --theme amber                 # With theme
+cdcx tui --setup                       # Setup wizard
+```
+
+### Features
+
+- **6 tabs:** Market, Portfolio, Orders, History, Watchlist, Positions
+- **Real-time streaming:** WebSocket ticker, order book, candlestick, trade channels
+- **Sparklines:** 24h Braille-dot price charts inline per instrument
+- **Heatmap mode:** rows glow red/green by 24h performance
+- **Candlestick charts:** volume bars, 9 timeframes, streaming updates, time axis
+- **Multi-chart compare:** up to 4 instruments side by side
+- **Split screen:** table + chart, auto-updates on selection
+- **Order book detail:** cumulative depth bars, buy/sell pressure bar
+- **Order workflows:** place order, OCO, OTOCO, cancel
+- **Live portfolio P&L:** session P&L in status bar, cash vs position breakdown in Portfolio tab
+- **Paper mode:** toggle `p` to trade against local paper engine with unrealized/realized P&L
+- **Instrument picker:** search-as-you-type overlay
+- **Price alerts:** set thresholds with terminal bell notification
+- **Ticker tape:** scrolling top movers banner
+- **6 themes:** terminal-pro, cyber-midnight, monochrome, neon, micky-d, amber + custom TOML
+- **Mouse support:** click to select, scroll, double-click to detail
+- **Export:** `y` copies table as CSV to clipboard
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `1`-`6` / `Tab` | Switch tabs |
+| `Enter` | Instrument detail (book + trades) |
+| `k` | Candlestick chart |
+| `m` | Compare charts (up to 4) |
+| `h` | Toggle heatmap |
+| `i` | Instrument spotlight |
+| `\` | Split screen (table + chart) |
+| `[ / ]` | Cycle chart timeframe |
+| `s / S` | Sort / reverse sort |
+| `/` | Search instruments |
+| `t` | Place order |
+| `o` | OCO order (stop-loss + take-profit) |
+| `O` | OTOCO order (entry + SL + TP) |
+| `c` | Cancel orders |
+| `p` | Toggle LIVE / PAPER mode |
+| `!` | Set price alert |
+| `y` | Copy to clipboard (CSV) |
+| `?` | Help overlay |
+| `q` | Quit |
+
+---
+
+## Configuration
+
+### Credentials
+
+Resolved in order: flags > `CDCX_API_KEY`/`CDCX_API_SECRET` env > `CDC_API_KEY`/`CDC_API_SECRET` env > `~/.config/cdcx/config.toml` profile.
+
+```bash
+cdcx setup                             # Interactive credential setup
+cdcx --profile uat account summary     # Use named profile
+```
+
+### TUI Config
+
+`~/.config/cdcx/tui.toml`:
+
+```toml
+theme = "terminal-pro"
+tick_rate_ms = 250
+watchlist = ["BTC_USDT", "ETH_USDT", "SOL_USDT", "CRO_USDT"]
+
+[themes.my-theme]
+bg = "#1a1a2e"
+accent = "#00d4ff"
+positive = "#00ff88"
+negative = "#ff4444"
+```
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Output format: `json` (default), `table`, `ndjson` |
+| `--dry-run` | Preview request without executing |
+| `--env` | Environment: `production` (default), `uat` |
+| `--profile` | Config profile name |
+| `--yes` | Skip confirmation prompts |
+| `-v, --verbose` | Verbose output |
+
+---
+
+## Architecture
+
+```
+crates/cdcx-core/       # API client, auth, signing, schema, OpenAPI parser, paper engine
+crates/cdcx-cli/        # CLI binary, dispatch, MCP server, setup
+crates/cdcx-tui/        # Terminal dashboard (ratatui + crossterm)
+schemas/                # CLI overlay files (command aliases, positional args, defaults)
+skills/                 # Agent skill files for guided workflows
+site/                   # Marketing site (single HTML file)
+```
+
+- **OpenAPI sole source:** All API commands and MCP tools are generated from the exchange's OpenAPI spec at runtime (24h cache). Thin TOML overlay files in `schemas/` add CLI-only metadata (positional args, defaults, command aliases). No hand-maintained endpoint definitions.
+- **Single binary:** ~11MB, no runtime dependencies
+- **Zero flicker:** ratatui double-buffer character-level diffing
+
+## Development
+
+```bash
+cargo test                             # Run all tests
+cargo build --release                  # Build release binary
+cargo run -- market ticker BTC_USDT    # Run from source
+cargo run -- tui                       # TUI from source
+```
+
+### Git hooks
+
+Install once per clone to catch CI failures locally:
+
+```bash
+./hooks/install.sh
+```
+
+- `pre-commit` runs `cargo fmt --check` + `cargo clippy -- -D warnings`
+- `pre-push` runs the full test suite (skipped for doc-only pushes)
+
+The toolchain is pinned to `stable` via `rust-toolchain.toml`; run `rustup update stable` if your local clippy is older than CI's.
+
+## License
+
+Dual-licensed under [MIT](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE).

package/install.sh

@@ -0,0 +1,251 @@
+#!/bin/sh
+# cdcx installer — detects platform, downloads latest release, verifies checksum, installs.
+#
+# Usage:
+#   curl -sSfL https://raw.githubusercontent.com/crypto-com/cdcx-cli/main/install.sh | sh
+#
+# Or from source:
+#   cargo install --git https://github.com/crypto-com/cdcx-cli.git --bin cdcx
+
+set -eu
+
+REPO="crypto-com/cdcx-cli"
+BINARY="cdcx"
+# INSTALL_DIR is resolved after the banner:
+#   1. honour an explicit INSTALL_DIR env var if set
+#   2. otherwise prefer /usr/local/bin when writable
+#   3. otherwise fall back to ~/.local/bin (no sudo required)
+DEFAULT_SYSTEM_DIR="/usr/local/bin"
+DEFAULT_USER_DIR="${HOME}/.local/bin"
+SKIP_VERIFICATION=false
+
+# ── Colors ──────────────────────────────────────────────────────────────────────
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+info()  { printf "${CYAN}${BOLD}==>${NC} %s\n" "$1"; }
+ok()    { printf "${GREEN}${BOLD} ✓${NC} %s\n" "$1"; }
+warn()  { printf "${YELLOW}${BOLD} !${NC} %s\n" "$1"; }
+error() { printf "${RED}${BOLD}Error:${NC} %s\n" "$1" >&2; exit 1; }
+
+# Parse command-line flags (must be after function definitions)
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --skip-verification)
+            SKIP_VERIFICATION=true
+            shift
+            ;;
+        *)
+            error "Unknown option: $1"
+            ;;
+    esac
+done
+
+# ── Banner ──────────────────────────────────────────────────────────────────────
+
+printf "${CYAN}${BOLD}"
+cat << 'BANNER'
+
+   ██████╗██████╗  ██████╗██╗  ██╗
+  ██╔════╝██╔══██╗██╔════╝╚██╗██╔╝
+  ██║     ██║  ██║██║      ╚███╔╝
+  ██║     ██║  ██║██║      ██╔██╗
+  ╚██████╗██████╔╝╚██████╗██╔╝██╗
+   ╚═════╝╚═════╝  ╚═════╝╚═╝ ╚═╝
+
+  Crypto.com Exchange CLI
+
+BANNER
+printf "${NC}"
+
+# ── Platform detection ──────────────────────────────────────────────────────────
+
+detect_os() {
+    case "$(uname -s)" in
+        Linux*)  echo "linux" ;;
+        Darwin*) echo "darwin" ;;
+        MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
+        *) error "Unsupported operating system: $(uname -s)" ;;
+    esac
+}
+
+detect_arch() {
+    case "$(uname -m)" in
+        x86_64|amd64)  echo "x86_64" ;;
+        arm64|aarch64) echo "aarch64" ;;
+        *) error "Unsupported architecture: $(uname -m)" ;;
+    esac
+}
+
+OS="$(detect_os)"
+ARCH="$(detect_arch)"
+
+info "Detected platform: ${OS}-${ARCH}"
+
+# ── Fetch latest release ────────────────────────────────────────────────────────
+
+info "Fetching latest release..."
+
+RELEASE_JSON="$(curl -sSfL "https://api.github.com/repos/${REPO}/releases/latest" 2>/dev/null)" || error "Failed to fetch release info from GitHub."
+
+# Extract version tag
+VERSION="$(echo "$RELEASE_JSON" | grep '"tag_name"' | head -1 | sed 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')"
+if [ -z "$VERSION" ]; then
+    error "Could not determine latest release version."
+fi
+
+# Validate VERSION against semantic versioning pattern to prevent code injection
+if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then
+    error "Invalid version format: ${VERSION}. Expected semantic version (e.g., v1.0.0)."
+fi
+
+ok "Latest version: ${VERSION}"
+
+# ── Construct download URL ──────────────────────────────────────────────────────
+
+# Release assets are named with the bare version (no leading "v"),
+# matching the release.yml workflow which strips the "v" prefix.
+VERSION_BARE="${VERSION#v}"
+
+# Archive naming: cdcx-{version}-{arch}-{os}.tar.gz (or .zip for windows)
+# Linux binaries ship as musl (statically linked, glibc-free) for portability.
+PLATFORM="${OS}"
+if [ "$OS" = "darwin" ]; then
+    PLATFORM="apple-darwin"
+elif [ "$OS" = "linux" ]; then
+    PLATFORM="unknown-linux-musl"
+fi
+
+if [ "$OS" = "windows" ]; then
+    ARCHIVE="${BINARY}-${VERSION_BARE}-${ARCH}-pc-windows-msvc.zip"
+else
+    ARCHIVE="${BINARY}-${VERSION_BARE}-${ARCH}-${PLATFORM}.tar.gz"
+fi
+
+DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${VERSION}/${ARCHIVE}"
+CHECKSUM_URL="https://github.com/${REPO}/releases/download/${VERSION}/checksums.txt"
+
+info "Downloading ${ARCHIVE}..."
+
+# ── Download and verify ─────────────────────────────────────────────────────────
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+# Download archive
+curl -sSfL -o "${TMPDIR}/${ARCHIVE}" "$DOWNLOAD_URL" || \
+    error "Download failed. This platform (${ARCH}-${PLATFORM}) may not have a pre-built binary.\n  Try: cargo install --git https://github.com/${REPO}.git --bin cdcx"
+
+ok "Downloaded ${ARCHIVE}"
+
+# Download and verify checksum (if available)
+CHECKSUM_DOWNLOADED=false
+if curl -sSfL -o "${TMPDIR}/checksums.txt" "$CHECKSUM_URL" 2>/dev/null; then
+    CHECKSUM_DOWNLOADED=true
+fi
+
+if [ "$SKIP_VERIFICATION" = true ]; then
+    warn "Checksum verification skipped — this is insecure. Only skip if you trust the download source."
+    warn "For security, verification is enabled by default. Re-run without --skip-verification for secure installs."
+else
+    if [ "$CHECKSUM_DOWNLOADED" = false ]; then
+        error "Checksums not available for this release. Cannot verify binary integrity.\n  To bypass verification (not recommended), re-run with --skip-verification"
+    fi
+
+    EXPECTED="$(awk -v f="$ARCHIVE" '$2 == f { print $1 }' "${TMPDIR}/checksums.txt")"
+    if [ -z "$EXPECTED" ]; then
+        error "Checksum entry not found for ${ARCHIVE}. Binary file name mismatch or corrupted checksums.txt.\n  To bypass verification (not recommended), re-run with --skip-verification"
+    fi
+
+    if command -v sha256sum > /dev/null 2>&1; then
+        ACTUAL="$(sha256sum "${TMPDIR}/${ARCHIVE}" | awk '{print $1}')"
+    elif command -v shasum > /dev/null 2>&1; then
+        ACTUAL="$(shasum -a 256 "${TMPDIR}/${ARCHIVE}" | awk '{print $1}')"
+    else
+        error "No SHA256 tool found (neither sha256sum nor shasum available). Cannot verify checksum.\n  Install sha256sum or shasum, or re-run with --skip-verification (not recommended)"
+    fi
+
+    if [ "$ACTUAL" != "$EXPECTED" ]; then
+        error "Checksum verification failed!\n  Expected: ${EXPECTED}\n  Got:      ${ACTUAL}\n  The downloaded file may be corrupted. Please try again."
+    fi
+    ok "Checksum verified"
+fi
+
+# ── Extract ─────────────────────────────────────────────────────────────────────
+
+info "Extracting..."
+
+if [ "$OS" = "windows" ]; then
+    unzip -qo "${TMPDIR}/${ARCHIVE}" -d "${TMPDIR}" || error "Failed to extract archive."
+else
+    tar -xzf "${TMPDIR}/${ARCHIVE}" -C "${TMPDIR}" || error "Failed to extract archive."
+fi
+
+# Find the binary (may be in a subdirectory)
+EXTRACTED_BIN="$(find "${TMPDIR}" -name "${BINARY}" -type f | head -1)"
+if [ -z "$EXTRACTED_BIN" ]; then
+    # Try with .exe for Windows
+    EXTRACTED_BIN="$(find "${TMPDIR}" -name "${BINARY}.exe" -type f | head -1)"
+fi
+if [ -z "$EXTRACTED_BIN" ]; then
+    error "Could not find ${BINARY} binary in extracted archive."
+fi
+
+chmod +x "$EXTRACTED_BIN"
+ok "Extracted ${BINARY}"
+
+# ── Install ─────────────────────────────────────────────────────────────────────
+
+# Resolve install location. Honour an explicit INSTALL_DIR; otherwise prefer the
+# system dir when writable, fall back to ~/.local/bin when not. Never prompt for
+# sudo automatically — scripts piped to `sh` can't read a TTY, and many
+# environments (CI, corporate laptops, rootless containers) lack sudo entirely.
+if [ -n "${INSTALL_DIR:-}" ]; then
+    :  # user supplied INSTALL_DIR; respect it verbatim
+elif [ -w "$DEFAULT_SYSTEM_DIR" ] 2>/dev/null; then
+    INSTALL_DIR="$DEFAULT_SYSTEM_DIR"
+else
+    INSTALL_DIR="$DEFAULT_USER_DIR"
+    info "${DEFAULT_SYSTEM_DIR} is not writable — installing to ${INSTALL_DIR} (no sudo needed)"
+fi
+
+mkdir -p "$INSTALL_DIR" || error "Could not create ${INSTALL_DIR}"
+
+info "Installing to ${INSTALL_DIR}/${BINARY}..."
+
+if [ -w "$INSTALL_DIR" ]; then
+    mv "$EXTRACTED_BIN" "${INSTALL_DIR}/${BINARY}" || \
+        error "Failed to move binary into ${INSTALL_DIR}. Set INSTALL_DIR to a writable directory and re-run."
+else
+    error "${INSTALL_DIR} is not writable. Set INSTALL_DIR=\$HOME/.local/bin (or another writable path) and re-run."
+fi
+
+ok "Installed ${BINARY} to ${INSTALL_DIR}/${BINARY}"
+
+# ── Verify ──────────────────────────────────────────────────────────────────────
+
+if command -v "$BINARY" > /dev/null 2>&1; then
+    INSTALLED_VERSION="$("$BINARY" --version 2>/dev/null || echo "cdcx")"
+    printf "\n"
+    printf "${GREEN}${BOLD} ✓ ${INSTALLED_VERSION} installed successfully!${NC}\n"
+    printf "\n"
+    info "Binary:  ${INSTALL_DIR}/${BINARY}"
+    printf "\n"
+    printf "  ${CYAN}Get started:${NC}\n"
+    printf "    ${BOLD}cdcx market ticker BTC_USDT${NC}   # Live ticker\n"
+    printf "    ${BOLD}cdcx tui${NC}                      # Interactive dashboard\n"
+    printf "    ${BOLD}cdcx setup${NC}                    # Configure API keys\n"
+    printf "    ${BOLD}cdcx --help${NC}                   # All commands\n"
+    printf "\n"
+else
+    warn "${BINARY} was installed but is not in your PATH."
+    printf "  Add this line to ${BOLD}~/.zshrc${NC} or ${BOLD}~/.bashrc${NC}:\n"
+    printf "    ${BOLD}export PATH=\"${INSTALL_DIR}:\$PATH\"${NC}\n"
+    printf "  Then reload: ${BOLD}source ~/.zshrc${NC} (or open a new shell).\n"
+    printf "  Or run directly without modifying PATH: ${BOLD}${INSTALL_DIR}/${BINARY}${NC}\n"
+fi

package/npm/bin.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { findBinary, install, ROOT_DIR, LOCAL_BIN } from "./lib.mjs";
+
+let bin = findBinary();
+if (!bin) {
+  try {
+    install();
+  } catch {
+    // global install failed — fall through to local attempt
+  }
+  bin = findBinary();
+  if (!bin) {
+    try {
+      install(ROOT_DIR);
+    } catch {
+      process.stderr.write("cdcx installation failed.\n");
+      process.exit(1);
+    }
+    if (!existsSync(LOCAL_BIN)) {
+      process.stderr.write("cdcx installation failed — binary not found.\n");
+      process.exit(1);
+    }
+    bin = LOCAL_BIN;
+  }
+}
+
+try {
+  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/npm/lib.mjs

@@ -0,0 +1,52 @@
+import { execFileSync, execSync } from "child_process";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const BINARY = "cdcx";
+export const ROOT_DIR = join(__dirname, "..");
+export const LOCAL_BIN = join(ROOT_DIR, BINARY);
+const INSTALL_SCRIPT = join(ROOT_DIR, "install.sh");
+
+export function findBinary() {
+  if (existsSync(LOCAL_BIN)) {
+    try {
+      execFileSync(LOCAL_BIN, ["--version"], { stdio: "pipe" });
+      return LOCAL_BIN;
+    } catch {
+      // exists but not functional — fall through
+    }
+  }
+  try {
+    const bin = execSync(`command -v ${BINARY}`, { encoding: "utf8" }).trim();
+    execFileSync(bin, ["--version"], { stdio: "pipe" });
+    return bin;
+  } catch {
+    return null;
+  }
+}
+
+export function installedVersion(bin) {
+  try {
+    const out = execFileSync(bin, ["--version"], { encoding: "utf8" }).trim();
+    const match = out.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export function install(dir) {
+  if (!existsSync(INSTALL_SCRIPT)) {
+    process.stderr.write(
+      `${BINARY} not found. Install it: curl -sSfL https://raw.githubusercontent.com/crypto-com/cdcx-cli/main/install.sh | sh\n`
+    );
+    process.exit(1);
+  }
+  const env = dir ? { ...process.env, INSTALL_DIR: dir } : process.env;
+  execFileSync("sh", [INSTALL_SCRIPT], {
+    stdio: ["pipe", process.stderr, process.stderr],
+    env,
+  });
+}

package/npm/post-install.mjs

@@ -0,0 +1,58 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import {
+  findBinary,
+  install,
+  installedVersion,
+  ROOT_DIR,
+} from "./lib.mjs";
+
+function isUpdateDisabled() {
+  try {
+    const configPath = join(homedir(), ".config", "cdcx", "config.toml");
+    if (!existsSync(configPath)) return false;
+    const content = readFileSync(configPath, "utf8");
+    return /^\s*disable_update_check\s*=\s*"?true"?\s*$/m.test(content);
+  } catch {
+    return false;
+  }
+}
+
+const bin = findBinary();
+
+if (!bin) {
+  // No binary at all — must install regardless of update preference
+  try {
+    install();
+  } catch {
+    try {
+      install(ROOT_DIR);
+    } catch {
+      process.stderr.write("cdcx installation failed.\n");
+      process.exit(1);
+    }
+  }
+} else if (!isUpdateDisabled()) {
+  const expected = JSON.parse(
+    readFileSync(join(ROOT_DIR, "package.json"), "utf8")
+  ).version;
+  const current = installedVersion(bin);
+
+  if (current !== expected) {
+    try {
+      install();
+    } catch {
+      // global failed — try local
+    }
+    const updated = findBinary();
+    if (!updated || installedVersion(updated) !== expected) {
+      try {
+        install(ROOT_DIR);
+      } catch {
+        process.stderr.write("cdcx installation failed.\n");
+        process.exit(1);
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cryptocom/cdcx-cli",
+  "version": "1.2.2",
+  "description": "MCP server for crypto.com exchange CLI",
+  "author": "Crypto.com",
+  "homepage": "https://github.com/crypto-com/cdcx-cli",
+  "license": "MIT OR Apache-2.0",
+  "keywords": [
+    "crypto.com",
+    "crypto",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "url": "git+https://github.com/crypto-com/cdcx-cli.git",
+    "type": "git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "README.md",
+    "install.sh",
+    "npm/bin.mjs",
+    "npm/lib.mjs",
+    "npm/post-install.mjs"
+  ],
+  "bin": {
+    "cdcx-cli": "npm/bin.mjs"
+  },
+  "scripts": {
+    "bump": "./scripts/version-bump.sh",
+    "postinstall": "node ./npm/post-install.mjs"
+  }
+}