Merge pull request #4 from BitMEX-private/docs/agent-discoverability

docs: agent discoverability + fix install script

Author: byshing

README.md

@@ -22,7 +22,7 @@ Paste this into your AI agent to get set up:
 Set up bitmex-cli for my BitMEX trading account.
 
 ## Install
-Run: curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh | sh
+Run: tmpfile="$(mktemp)" && curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh -o "$tmpfile" && sh "$tmpfile"
 
 ## Account Setup
 If I don't have a BitMEX account yet, walk me through:
@@ -33,8 +33,9 @@ If I don't have a BitMEX account yet, walk me through:
 ## API Key
 Guide me to https://www.bitmex.com/app/apiKeys to create an API key with
 "Order" and "Account" permissions (add "Withdraw" only if I need withdrawals).
-Ask me for the key and secret, then run:
-bitmex auth set --api-key <KEY> --api-secret <SECRET>
+Ask me to choose:
+- Share my key and secret with you, and run: bitmex auth set --api-key <KEY> --api-secret <SECRET>
+- Or keep keys private: ask me to open a terminal and run `bitmex auth add` myself (do NOT run this for me — it requires an interactive terminal)
 
 ## Verify
 Run: bitmex account me -o json
@@ -67,10 +68,10 @@ And suggest starting with --testnet to practice safely before using real funds.
 ### Install script (recommended)
 
 ```bash
-curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh | sh
+tmpfile="$(mktemp)" && curl -sSfL https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/install.sh -o "$tmpfile" && sh "$tmpfile"
 ```
 
-Downloads a pre-built binary for your platform (macOS/Linux, x86_64/arm64), verifies the SHA256 checksum, and installs to `/usr/local/bin`. No Rust or build tools needed. Requires `curl`, `tar`, and `sha256sum` (or `shasum`). May prompt for `sudo` if `/usr/local/bin` is not writable.
+Downloads a pre-built binary for your platform (macOS/Linux, x86_64/arm64), verifies the SHA256 checksum, and installs to `~/.local/bin`. No Rust or build tools needed. No `sudo` required. Requires `curl`, `tar`, and `sha256sum` (or `shasum`). Override the install location with `BITMEX_INSTALL_DIR`.
 
 ### GitHub Releases
 

install.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
 set -e
 
-REPO_URL="https://github.com/BitMEX/bitmex-cli"
+REPO="BitMEX-private/bitmex-cli"  # TEMP: pre-launch, revert to BitMEX/bitmex-cli
 BINARY="bitmex"
-INSTALL_DIR="/usr/local/bin"
+INSTALL_DIR="${BITMEX_INSTALL_DIR:-$HOME/.local/bin}"
 
 get_target() {
   os=$(uname -s)
@@ -27,37 +27,101 @@ get_target() {
     *)
       echo "Unsupported OS: $os" >&2
       echo "For Windows, download the binary manually from:" >&2
-      echo "  ${REPO_URL}/releases" >&2
+      echo "  https://github.com/${REPO}/releases" >&2
       exit 1
       ;;
   esac
 }
 
+on_path() {
+  case ":$PATH:" in
+    *":$1:"*) return 0 ;;
+    *)        return 1 ;;
+  esac
+}
+
+install_skills() {
+  src_tarball="$1"
+  skills_tmpdir=$(mktemp -d)
+  trap 'rm -rf "$skills_tmpdir"' EXIT
+
+  # Extract skills/ from source tarball (top-level dir varies, strip it)
+  tar xzf "$src_tarball" -C "$skills_tmpdir" --strip-components=1 2>/dev/null || return 1
+  skills_src="$skills_tmpdir/skills"
+  [ -d "$skills_src" ] || return 1
+
+  installed=""
+
+  # OpenClaw
+  if [ -d "$HOME/.openclaw" ]; then
+    mkdir -p "$HOME/.openclaw/skills"
+    for skill in "$skills_src"/bitmex-*/; do
+      cp -r "$skill" "$HOME/.openclaw/skills/"
+    done
+    installed="${installed} OpenClaw"
+  fi
+
+  # Claude Code
+  if [ -d "$HOME/.claude" ]; then
+    mkdir -p "$HOME/.claude/commands"
+    for skill in "$skills_src"/bitmex-*/; do
+      name=$(basename "$skill")
+      cp "$skill/SKILL.md" "$HOME/.claude/commands/${name}.md"
+    done
+    installed="${installed} Claude"
+  fi
+
+  # Hermes
+  if [ -d "$HOME/.hermes" ]; then
+    mkdir -p "$HOME/.hermes/skills"
+    for skill in "$skills_src"/bitmex-*/; do
+      cp -r "$skill" "$HOME/.hermes/skills/"
+    done
+    installed="${installed} Hermes"
+  fi
+
+  echo ""
+  if [ -n "$installed" ]; then
+    echo "Installed bitmex skills for:${installed}"
+    echo "Start a new conversation in your AI tool for skills to be recognized."
+  else
+    echo "No AI agents detected. To install skills manually:"
+    echo "  OpenClaw : cp -r skills/bitmex-* ~/.openclaw/skills/"
+    echo "  Claude   : for s in skills/bitmex-*; do cp \"\$s/SKILL.md\" ~/.claude/commands/\$(basename \$s).md; done"
+    echo "  Hermes   : cp -r skills/bitmex-* ~/.hermes/skills/"
+  fi
+}
+
 main() {
   target=$(get_target)
 
-  tag=$(curl -sSf "https://raw.githubusercontent.com/BitMEX/bitmex-cli/master/Cargo.toml" | grep '^version' | head -1 | cut -d'"' -f2)
+  # TEMP: pre-launch, repo is private — use `gh` for auth.
+  # Revert this block to the curl version (see git history) once public.
+  if ! command -v gh >/dev/null 2>&1; then
+    echo "Error: 'gh' CLI required for pre-launch install (repo is private)" >&2
+    exit 1
+  fi
+  tag=$(gh release view --repo "$REPO" --json tagName --jq .tagName)
   if [ -z "$tag" ]; then
-    echo "Error: could not determine latest version" >&2
+    echo "Error: could not determine latest release" >&2
     exit 1
   fi
-  version="v${tag}"
-  tag="cli-${version}"
 
-  tarball="bitmex-${version}-${target}.tar.gz"
-  url="${REPO_URL}/releases/download/${tag}/${tarball}"
-  checksums_url="${REPO_URL}/releases/download/${tag}/checksums.txt"
+  tarball="bitmex-cli-${target}.tar.gz"
+  checksums="sha256.sum"
 
-  echo "Installing ${BINARY} ${version} (${target})..."
+  echo "Installing ${BINARY} ${tag} (${target}) to ${INSTALL_DIR}..."
   echo ""
 
   tmpdir=$(mktemp -d)
   trap 'rm -rf "$tmpdir"' EXIT
 
-  curl -sSfL "$url" -o "$tmpdir/$tarball"
-  curl -sSfL "$checksums_url" -o "$tmpdir/checksums.txt"
+  # TEMP: pre-launch, use `gh release download` instead of curl.
+  gh release download "$tag" --repo "$REPO" \
+    --pattern "$tarball" --pattern "$checksums" \
+    --dir "$tmpdir" >/dev/null
 
-  expected_hash=$(grep "$tarball" "$tmpdir/checksums.txt" | awk '{print $1}')
+  expected_hash=$(grep "$tarball" "$tmpdir/$checksums" | awk '{print $1}')
   if [ -z "$expected_hash" ]; then
     echo "Error: no checksum found for $tarball" >&2
     exit 1
@@ -82,16 +146,43 @@ main() {
   echo "Checksum verified."
   tar xzf "$tmpdir/$tarball" -C "$tmpdir"
 
-  if [ -w "$INSTALL_DIR" ]; then
-    mv "$tmpdir/$BINARY" "$INSTALL_DIR/$BINARY"
-    chmod +x "$INSTALL_DIR/$BINARY"
-  else
-    sudo mv "$tmpdir/$BINARY" "$INSTALL_DIR/$BINARY"
-    sudo chmod +x "$INSTALL_DIR/$BINARY"
+  # cargo-dist nests the binary inside <name>-<target>/
+  src="$tmpdir/bitmex-cli-${target}/$BINARY"
+  if [ ! -f "$src" ]; then
+    echo "Error: binary not found at $src" >&2
+    exit 1
   fi
 
+  mkdir -p "$INSTALL_DIR"
+  mv "$src" "$INSTALL_DIR/$BINARY"
+  chmod +x "$INSTALL_DIR/$BINARY"
+
   echo ""
   echo "Installed ${BINARY} to ${INSTALL_DIR}/${BINARY}"
+
+  if ! on_path "$INSTALL_DIR"; then
+    echo ""
+    echo "Note: ${INSTALL_DIR} is not on your PATH. Add it with:"
+    case "${SHELL##*/}" in
+      zsh)  echo "  echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.zshrc && source ~/.zshrc" ;;
+      bash) echo "  echo 'export PATH=\"${INSTALL_DIR}:\$PATH\"' >> ~/.bashrc && source ~/.bashrc" ;;
+      fish) echo "  fish_add_path ${INSTALL_DIR}" ;;
+      *)    echo "  export PATH=\"${INSTALL_DIR}:\$PATH\"" ;;
+    esac
+  fi
+
+  # Install skills (non-fatal if it fails)
+  src_tarball="$tmpdir/source.tar.gz"
+  # TEMP: use gh api for private repo. When public, replace with:
+  #   curl -sSfL "https://github.com/${REPO}/archive/refs/tags/${tag}.tar.gz" -o "$src_tarball"
+  if gh api "repos/${REPO}/tarball/${tag}" > "$src_tarball" 2>/dev/null; then
+    install_skills "$src_tarball" || echo "Warning: skill installation failed (skipping)"
+  else
+    echo ""
+    echo "Warning: could not download skills — skipping skill installation."
+  fi
+
+  echo ""
   echo "Run 'bitmex --help' to get started."
 }
 

skills/INDEX.md

@@ -88,43 +88,43 @@ Multi-step workflows combining multiple skills.
 
 | Skill | Description |
 |-------|-------------|
-| [recipe-start-dca-bot](./recipe-start-dca-bot/SKILL.md) | Set up and run a DCA bot from testnet validation to live. |
-| [recipe-launch-grid-bot](./recipe-launch-grid-bot/SKILL.md) | Deploy a grid trading bot with testnet validation. |
-| [recipe-trailing-stop-runner](./recipe-trailing-stop-runner/SKILL.md) | Ride a trend with a trailing stop that locks in profits on reversal. |
-| [recipe-basis-trade-entry](./recipe-basis-trade-entry/SKILL.md) | Enter a perp-futures basis trade when premium exceeds threshold. |
-| [recipe-futures-hedge-spot](./recipe-futures-hedge-spot/SKILL.md) | Hedge a long position with a short perpetual. |
-| [recipe-funding-rate-scan](./recipe-funding-rate-scan/SKILL.md) | Scan perpetual contracts for funding rate carry opportunities. |
-| [recipe-testnet-strategy-backtest](./recipe-testnet-strategy-backtest/SKILL.md) | Validate a strategy across multiple testnet sessions before going live. |
+| [bitmex-recipe-start-dca-bot](./bitmex-recipe-start-dca-bot/SKILL.md) | Set up and run a DCA bot from testnet validation to live. |
+| [bitmex-recipe-launch-grid-bot](./bitmex-recipe-launch-grid-bot/SKILL.md) | Deploy a grid trading bot with testnet validation. |
+| [bitmex-recipe-trailing-stop-runner](./bitmex-recipe-trailing-stop-runner/SKILL.md) | Ride a trend with a trailing stop that locks in profits on reversal. |
+| [bitmex-recipe-basis-trade-entry](./bitmex-recipe-basis-trade-entry/SKILL.md) | Enter a perp-futures basis trade when premium exceeds threshold. |
+| [bitmex-recipe-futures-hedge-spot](./bitmex-recipe-futures-hedge-spot/SKILL.md) | Hedge a long position with a short perpetual. |
+| [bitmex-recipe-funding-rate-scan](./bitmex-recipe-funding-rate-scan/SKILL.md) | Scan perpetual contracts for funding rate carry opportunities. |
+| [bitmex-recipe-testnet-strategy-backtest](./bitmex-recipe-testnet-strategy-backtest/SKILL.md) | Validate a strategy across multiple testnet sessions before going live. |
 
 ### Portfolio Recipes
 
 | Skill | Description |
 |-------|-------------|
-| [recipe-weekly-rebalance](./recipe-weekly-rebalance/SKILL.md) | Weekly rebalance to maintain target position allocations. |
-| [recipe-daily-pnl-report](./recipe-daily-pnl-report/SKILL.md) | Daily realised P&L summary from trades and wallet history. |
-| [recipe-portfolio-snapshot-csv](./recipe-portfolio-snapshot-csv/SKILL.md) | Export portfolio snapshot with balances and positions to CSV. |
-| [recipe-subaccount-capital-rotation](./recipe-subaccount-capital-rotation/SKILL.md) | Rotate capital between subaccounts based on strategy performance. |
-| [recipe-fee-tier-progress](./recipe-fee-tier-progress/SKILL.md) | Track trading volume and commission rates. |
+| [bitmex-recipe-weekly-rebalance](./bitmex-recipe-weekly-rebalance/SKILL.md) | Weekly rebalance to maintain target position allocations. |
+| [bitmex-recipe-daily-pnl-report](./bitmex-recipe-daily-pnl-report/SKILL.md) | Daily realised P&L summary from trades and wallet history. |
+| [bitmex-recipe-portfolio-snapshot-csv](./bitmex-recipe-portfolio-snapshot-csv/SKILL.md) | Export portfolio snapshot with balances and positions to CSV. |
+| [bitmex-recipe-subaccount-capital-rotation](./bitmex-recipe-subaccount-capital-rotation/SKILL.md) | Rotate capital between subaccounts based on strategy performance. |
+| [bitmex-recipe-fee-tier-progress](./bitmex-recipe-fee-tier-progress/SKILL.md) | Track trading volume and commission rates. |
 
 ### Market Data Recipes
 
 | Skill | Description |
 |-------|-------------|
-| [recipe-morning-market-brief](./recipe-morning-market-brief/SKILL.md) | Morning summary: prices, funding, positions, and wallet. |
-| [recipe-multi-pair-breakout-watch](./recipe-multi-pair-breakout-watch/SKILL.md) | Monitor multiple symbols for price breakouts. |
-| [recipe-track-orderbook-depth](./recipe-track-orderbook-depth/SKILL.md) | Monitor order book depth and bid-ask imbalance for liquidity signals. |
-| [recipe-price-level-alerts](./recipe-price-level-alerts/SKILL.md) | Set up price level alerts for key levels. |
+| [bitmex-recipe-morning-market-brief](./bitmex-recipe-morning-market-brief/SKILL.md) | Morning summary: prices, funding, positions, and wallet. |
+| [bitmex-recipe-multi-pair-breakout-watch](./bitmex-recipe-multi-pair-breakout-watch/SKILL.md) | Monitor multiple symbols for price breakouts. |
+| [bitmex-recipe-track-orderbook-depth](./bitmex-recipe-track-orderbook-depth/SKILL.md) | Monitor order book depth and bid-ask imbalance for liquidity signals. |
+| [bitmex-recipe-price-level-alerts](./bitmex-recipe-price-level-alerts/SKILL.md) | Set up price level alerts for key levels. |
 
 ### Risk Recipes
 
 | Skill | Description |
 |-------|-------------|
-| [recipe-emergency-flatten](./recipe-emergency-flatten/SKILL.md) | Cancel all orders and close all positions immediately. |
-| [recipe-drawdown-circuit-breaker](./recipe-drawdown-circuit-breaker/SKILL.md) | Halt trading when portfolio drawdown exceeds threshold. |
+| [bitmex-recipe-emergency-flatten](./bitmex-recipe-emergency-flatten/SKILL.md) | Cancel all orders and close all positions immediately. |
+| [bitmex-recipe-drawdown-circuit-breaker](./bitmex-recipe-drawdown-circuit-breaker/SKILL.md) | Halt trading when portfolio drawdown exceeds threshold. |
 
 ### Funding Recipes
 
 | Skill | Description |
 |-------|-------------|
-| [recipe-withdrawal-to-cold-storage](./recipe-withdrawal-to-cold-storage/SKILL.md) | Safely withdraw funds to a pre-approved cold storage address. |
-| [recipe-staking-yield-compare](./recipe-staking-yield-compare/SKILL.md) | Compare staking yields across instruments to find the best rate. |
+| [bitmex-recipe-withdrawal-to-cold-storage](./bitmex-recipe-withdrawal-to-cold-storage/SKILL.md) | Safely withdraw funds to a pre-approved cold storage address. |
+| [bitmex-recipe-staking-yield-compare](./bitmex-recipe-staking-yield-compare/SKILL.md) | Compare staking yields across instruments to find the best rate. |

skills/bitmex-basis-trading/SKILL.md

@@ -27,11 +27,11 @@ A positive basis (futures above perp) typically reflects cost-of-carry. The stra
 ```bash
 # Perpetual
 PERP=$(bitmex market instrument --symbol XBTUSD -o json 2>/dev/null | \
-  jq -r '.lastPrice')
+  jq -r '.[0].lastPrice')
 
 # Nearest quarterly future (example: XBTM25)
 FUT=$(bitmex market instrument --symbol XBTM25 -o json 2>/dev/null | \
-  jq -r '.lastPrice')
+  jq -r '.[0].lastPrice')
 
 echo "Perp: $PERP | Future: $FUT"
 ```
@@ -44,7 +44,7 @@ echo "Basis: ${BASIS}%"
 
 # Days to expiry for annualized estimate
 SETTLE=$(bitmex market instrument --symbol XBTM25 -o json 2>/dev/null | \
-  jq -r '.settle')
+  jq -r '.[0].settle')
 echo "Settlement: $SETTLE"
 ```
 
@@ -86,8 +86,8 @@ bitmex order sell XBTM25 $QTY --price "$FUT" \
 
 ```bash
 # Check current basis
-PERP_NOW=$(bitmex market instrument --symbol XBTUSD -o json 2>/dev/null | jq -r '.lastPrice')
-FUT_NOW=$(bitmex market instrument --symbol XBTM25 -o json 2>/dev/null | jq -r '.lastPrice')
+PERP_NOW=$(bitmex market instrument --symbol XBTUSD -o json 2>/dev/null | jq -r '.[0].lastPrice')
+FUT_NOW=$(bitmex market instrument --symbol XBTM25 -o json 2>/dev/null | jq -r '.[0].lastPrice')
 BASIS_NOW=$(echo "scale=6; ($FUT_NOW - $PERP_NOW) / $PERP_NOW * 100" | bc -l)
 echo "Current basis: ${BASIS_NOW}%"
 

skills/bitmex-dca-strategy/SKILL.md

@@ -35,7 +35,7 @@ export BITMEX_API_SECRET="testnet-secret"
 # Run 3 testnet cycles to verify logic
 for i in 1 2 3; do
   PRICE=$(bitmex --testnet market orderbook XBTUSD --depth 1 -o json 2>/dev/null | \
-    jq '.bids[0][0]')
+    jq '[.[] | select(.side == "Buy")] | .[0].price')
   bitmex --testnet order buy XBTUSD 100 --price "$PRICE" \
     --order-type Limit --exec-inst ParticipateDoNotInitiate \
     -o json 2>/dev/null | jq '{orderID, price, ordStatus}'
@@ -72,7 +72,7 @@ while true; do
 
   # 3. Place limit order at best bid
   BID=$(bitmex market orderbook $SYMBOL --depth 1 -o json 2>/dev/null | \
-    jq '.bids[0][0]')
+    jq '[.[] | select(.side == "Buy")] | .[0].price')
   echo "DCA buy $QTY $SYMBOL @ $BID"
   bitmex order buy $SYMBOL $QTY \
     --price "$BID" \

skills/bitmex-fee-optimization/SKILL.md

@@ -21,11 +21,15 @@ BitMEX charges taker fees and pays maker rebates. The difference is meaningful a
 | Maker | Rebate | You earn (negative fee) |
 | Taker | Fee | You pay |
 
-Check your current fee schedule:
+Check your current fee schedule (returns a map of symbol → fees):
 
 ```bash
+# All symbols
+bitmex account commission -o json 2>/dev/null
+
+# Single symbol
 bitmex account commission -o json 2>/dev/null | \
-  jq '{makerFee, takerFee, settlementFee}'
+  jq '.XBTUSD | {makerFee, takerFee, settlementFee}'
 ```
 
 ## Default: Post-Only Limit Orders
@@ -60,7 +64,7 @@ Market orders always pay taker fees. Use limit orders at aggressive prices (insi
 
 ```bash
 # Instead of market buy, use aggressive limit:
-ASK=$(bitmex market orderbook XBTUSD --depth 1 -o json 2>/dev/null | jq '.asks[0][0]')
+ASK=$(bitmex market orderbook XBTUSD --depth 1 -o json 2>/dev/null | jq '[.[] | select(.side=="Sell") | .price][0]')
 bitmex order buy XBTUSD 100 \
   --price "$ASK" \
   --order-type Limit \
@@ -85,12 +89,12 @@ bitmex order buy XBTUSD 100 \
 Higher 30-day trading volume unlocks lower fees:
 
 ```bash
-# Check your 30-day volume
+# Check your 30-day volume (returns array; first element has the totals)
 bitmex account volume -o json 2>/dev/null | \
-  jq '{advUsd, advXBt}'
+  jq '.[0] | {advUsd, advUsdContract, advUsdSpot}'
 
-# Cross-reference with commission tiers
-bitmex account commission -o json 2>/dev/null
+# Cross-reference with commission tiers (returns map of symbol → fees)
+bitmex account commission -o json 2>/dev/null | jq '.XBTUSD'
 ```
 
 ## Fee Audit from Trade History

skills/bitmex-funding-carry/SKILL.md

@@ -44,7 +44,7 @@ Only enter if the annualized yield exceeds transaction costs and risk premium. A
 
 ```bash
 # Annualized carry threshold check (e.g., > 10% annualized)
-RATE=$(bitmex market funding --symbol XBTUSD -o json 2>/dev/null | \
+RATE=$(bitmex market funding --symbol XBTUSD --count 1 --reverse -o json 2>/dev/null | \
   jq -r '.[0].fundingRate // 0')
 ANNUALIZED=$(echo "$RATE * 3 * 365 * 100" | bc -l)
 echo "Annualized funding yield: ${ANNUALIZED}%"
@@ -101,7 +101,7 @@ bitmex position list --symbol XBTUSD -o json 2>/dev/null | \
 
 ```bash
 # Check if rate has converged toward zero
-RATE=$(bitmex market funding --symbol XBTUSD -o json 2>/dev/null | \
+RATE=$(bitmex market funding --symbol XBTUSD --count 1 --reverse -o json 2>/dev/null | \
   jq -r '.[0].fundingRate // 0')
 EXIT_THRESHOLD=0.0001  # < 0.01% per 8h no longer worth holding