@gaberoo/kalshitools 1.0.0 → 1.0.2

package/.env.example

@@ -0,0 +1,12 @@
+# Kalshi API Configuration
+# Override config file settings with environment variables
+
+# Environment: demo or production
+KALSHI_ENV=demo
+
+# API Credentials
+KALSHI_API_KEY_ID=your-email@example.com
+KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
+
+# Logging
+LOG_LEVEL=info

package/.env.local.example

@@ -0,0 +1,22 @@
+# Local Development API Credentials
+# Copy this file to .env or .env.local and fill in your credentials
+# NEVER commit this file with real credentials!
+
+# Environment: demo (safe for testing) or production (real money!)
+KALSHI_ENV=demo
+
+# API Key ID (your email address from Kalshi)
+KALSHI_API_KEY_ID=your-email@example.com
+
+# Path to your private key file
+# Can be absolute path or relative to home directory (~/)
+KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
+
+# Optional: Logging level (debug, info, warn, error)
+LOG_LEVEL=info
+
+# Note: Environment variables override ~/.config/kalshitools/config.json
+# This is useful for:
+# - Testing with different credentials
+# - CI/CD environments
+# - Switching between demo and production quickly

package/README.md

@@ -17,15 +17,95 @@ A powerful CLI tool for interacting with the Kalshi prediction markets API. Buil
 
 ## Quick Start
 
+### 1. Install
+
 ```bash
-# Initialize configuration
+npm install -g @gaberoo/kalshitools
+```
+
+### 2. Get Demo API Credentials
+
+Visit the [Kalshi Demo Portal](https://demo-api.kalshi.co) to generate API credentials:
+- **API Key ID**: Your registered email address
+- **Private Key**: Download the `.pem` file
+
+### 3. Configure Credentials
+
+**Option A: Interactive Setup (Recommended)**
+
+```bash
+# Run the configuration wizard
 kalshitools config init
 
-# Verify configuration
+# Follow the prompts:
+# - Environment: demo (default)
+# - API Key ID: your-email@example.com
+# - Private Key Path: ~/.kalshitools/demo-private-key.pem (default)
+
+# Place your private key file
+mkdir -p ~/.kalshitools
+cp ~/Downloads/private-key.pem ~/.kalshitools/demo-private-key.pem
+chmod 600 ~/.kalshitools/demo-private-key.pem  # Secure permissions
+```
+
+**Option B: Environment Variables (Quick Testing)**
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env with your credentials
+nano .env
+
+# Source the environment
+source .env
+```
+
+### 4. Verify Setup
+
+```bash
+# Check configuration
 kalshitools config show
 
-# Get JSON output
-kalshitools config show --json
+# Test API connection
+kalshitools portfolio balance
+
+# List active markets
+kalshitools markets list --status active --limit 5
+```
+
+### 5. Start Trading
+
+```bash
+# View available markets
+kalshitools markets list --status active
+
+# Get market details
+kalshitools markets show TICKER-SYMBOL
+
+# View your portfolio
+kalshitools portfolio balance
+kalshitools portfolio positions
+
+# Place an order (with confirmation)
+kalshitools orders create \
+  --ticker MARKET-TICKER \
+  --action buy \
+  --side yes \
+  --quantity 10 \
+  --type market
+
+# Use --dry-run to simulate without placing order
+kalshitools orders create \
+  --ticker MARKET-TICKER \
+  --action buy \
+  --side yes \
+  --quantity 10 \
+  --type market \
+  --dry-run
+
+# View order history
+kalshitools orders list
 ```
 
 ## Configuration
@@ -39,11 +119,40 @@ export KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
 export LOG_LEVEL=info
 ```
 
+### Security Notes
+
+- Private keys are **never** committed to the repository
+- All `.pem`, `.key`, and `.env` files are in `.gitignore`
+- Demo environment is the default (safe for testing)
+- Always use `--dry-run` first to verify order parameters
+- Store private keys with restricted permissions: `chmod 600`
+
+### Configuration Precedence
+
+1. Environment variables (highest priority)
+2. `~/.config/kalshitools/config.json`
+3. Default values (demo environment)
+
 <!-- toc -->
 * [kalshitools](#kalshitools)
-* [Initialize configuration](#initialize-configuration)
-* [Verify configuration](#verify-configuration)
-* [Get JSON output](#get-json-output)
+* [Run the configuration wizard](#run-the-configuration-wizard)
+* [Follow the prompts:](#follow-the-prompts)
+* [- Environment: demo (default)](#--environment-demo-default)
+* [- API Key ID: your-email@example.com](#--api-key-id-your-emailexamplecom)
+* [- Private Key Path: ~/.kalshitools/demo-private-key.pem (default)](#--private-key-path-kalshitoolsdemo-private-keypem-default)
+* [Place your private key file](#place-your-private-key-file)
+* [Copy the example file](#copy-the-example-file)
+* [Edit .env with your credentials](#edit-env-with-your-credentials)
+* [Source the environment](#source-the-environment)
+* [Check configuration](#check-configuration)
+* [Test API connection](#test-api-connection)
+* [List active markets](#list-active-markets)
+* [View available markets](#view-available-markets)
+* [Get market details](#get-market-details)
+* [View your portfolio](#view-your-portfolio)
+* [Place an order (with confirmation)](#place-an-order-with-confirmation)
+* [Use --dry-run to simulate without placing order](#use---dry-run-to-simulate-without-placing-order)
+* [View order history](#view-order-history)
 * [Usage](#usage)
 * [Commands](#commands)
 <!-- tocstop -->
@@ -54,7 +163,7 @@ $ npm install -g @gaberoo/kalshitools
 $ kalshitools COMMAND
 running command...
 $ kalshitools (--version)
-@gaberoo/kalshitools/1.0.0 darwin-arm64 node-v22.20.0
+@gaberoo/kalshitools/1.0.2 darwin-arm64 node-v22.20.0
 $ kalshitools --help [COMMAND]
 USAGE
   $ kalshitools COMMAND
@@ -109,7 +218,7 @@ EXAMPLES
   $ kalshitools config init --env production
 ```
 
-_See code: [src/commands/config/init.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/config/init.ts)_
+_See code: [src/commands/config/init.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/config/init.ts)_
 
 ## `kalshitools config show`
 
@@ -131,7 +240,7 @@ EXAMPLES
   $ kalshitools config show --json
 ```
 
-_See code: [src/commands/config/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/config/show.ts)_
+_See code: [src/commands/config/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/config/show.ts)_
 
 ## `kalshitools help [COMMAND]`
 
@@ -178,7 +287,7 @@ EXAMPLES
   $ kalshitools markets list --json
 ```
 
-_See code: [src/commands/markets/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/markets/list.ts)_
+_See code: [src/commands/markets/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/markets/list.ts)_
 
 ## `kalshitools markets show TICKER`
 
@@ -203,7 +312,7 @@ EXAMPLES
   $ kalshitools markets show TICKER --json
 ```
 
-_See code: [src/commands/markets/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/markets/show.ts)_
+_See code: [src/commands/markets/show.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/markets/show.ts)_
 
 ## `kalshitools orders cancel ORDERID`
 
@@ -231,7 +340,7 @@ EXAMPLES
   $ kalshitools orders cancel ORDER_ID --json
 ```
 
-_See code: [src/commands/orders/cancel.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/orders/cancel.ts)_
+_See code: [src/commands/orders/cancel.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/orders/cancel.ts)_
 
 ## `kalshitools orders create`
 
@@ -269,7 +378,7 @@ EXAMPLES
   $ kalshitools orders create --ticker TICKER --action buy --side yes --quantity 100 --dry-run
 ```
 
-_See code: [src/commands/orders/create.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/orders/create.ts)_
+_See code: [src/commands/orders/create.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/orders/create.ts)_
 
 ## `kalshitools orders list`
 
@@ -300,7 +409,7 @@ EXAMPLES
   $ kalshitools orders list --json
 ```
 
-_See code: [src/commands/orders/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/orders/list.ts)_
+_See code: [src/commands/orders/list.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/orders/list.ts)_
 
 ## `kalshitools plugins`
 
@@ -612,7 +721,7 @@ EXAMPLES
   $ kalshitools portfolio balance --json
 ```
 
-_See code: [src/commands/portfolio/balance.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/portfolio/balance.ts)_
+_See code: [src/commands/portfolio/balance.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/portfolio/balance.ts)_
 
 ## `kalshitools portfolio fills`
 
@@ -640,7 +749,7 @@ EXAMPLES
   $ kalshitools portfolio fills --json
 ```
 
-_See code: [src/commands/portfolio/fills.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/portfolio/fills.ts)_
+_See code: [src/commands/portfolio/fills.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/portfolio/fills.ts)_
 
 ## `kalshitools portfolio positions`
 
@@ -662,5 +771,5 @@ EXAMPLES
   $ kalshitools portfolio positions --json
 ```
 
-_See code: [src/commands/portfolio/positions.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.0/src/commands/portfolio/positions.ts)_
+_See code: [src/commands/portfolio/positions.ts](https://github.com/kalshitools/kalshitools/blob/v1.0.2/src/commands/portfolio/positions.ts)_
 <!-- commandsstop -->

package/SETUP_DEMO_API.md

@@ -0,0 +1,251 @@
+# Quick Setup: Demo API Credentials
+
+Follow these steps to set up your demo API credentials for local testing.
+
+## ✅ Step-by-Step Checklist
+
+### Step 1: Get Your Demo API Credentials
+
+1. Visit **[Kalshi Demo Portal](https://demo-api.kalshi.co)**
+2. Sign up or log in to your demo account
+3. Navigate to **API Settings** or **Developer Settings**
+4. Click **Generate API Key** or **Create New API Key**
+5. You'll receive:
+   - **API Key ID** (your email address)
+   - **Private Key** (download the `.pem` file)
+6. Download and save the private key file
+
+### Step 2: Choose Your Configuration Method
+
+**Option A: Interactive Setup (Recommended)**
+
+```bash
+# Run the configuration wizard
+kalshitools config init
+```
+
+Follow the prompts:
+- **Environment**: `demo` (press Enter for default)
+- **API Key ID**: Enter your email address from Kalshi
+- **Private Key Path**: `~/.kalshitools/demo-private-key.pem` (press Enter for default)
+
+**Option B: Environment Variables**
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit the file with your credentials
+nano .env
+```
+
+Update these values in `.env`:
+```bash
+KALSHI_ENV=demo
+KALSHI_API_KEY_ID=your-email@example.com
+KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
+```
+
+### Step 3: Place Your Private Key File
+
+```bash
+# Create the directory
+mkdir -p ~/.kalshitools
+
+# Copy your downloaded private key
+cp ~/Downloads/demo-private-key.pem ~/.kalshitools/demo-private-key.pem
+
+# Set secure permissions (important!)
+chmod 600 ~/.kalshitools/demo-private-key.pem
+```
+
+**Verify the file is in place:**
+```bash
+ls -la ~/.kalshitools/demo-private-key.pem
+```
+
+Expected output:
+```
+-rw-------  1 you  staff  1679 Feb 17 10:00 /Users/you/.kalshitools/demo-private-key.pem
+```
+
+### Step 4: Verify Configuration
+
+```bash
+# Check configuration
+kalshitools config show
+```
+
+Expected output:
+```
+Kalshi API Configuration
+Environment: DEMO
+API Key ID: yo****@ex******.com
+Private Key Path: /Users/you/.kalshitools/demo-private-key.pem
+```
+
+### Step 5: Test API Connection
+
+```bash
+# Test authentication and connectivity
+kalshitools portfolio balance
+```
+
+Expected output:
+```
+Account Balance
+Available: $10,000.00
+Total: $10,000.00
+```
+
+### Step 6: Try Some Commands
+
+```bash
+# List active markets
+kalshitools markets list --status active --limit 5
+
+# Get specific market details
+kalshitools markets show TICKER-SYMBOL
+
+# View your positions
+kalshitools portfolio positions
+
+# Simulate an order (doesn't actually place it)
+kalshitools orders create \
+  --ticker MARKET-TICKER \
+  --action buy \
+  --side yes \
+  --quantity 1 \
+  --type market \
+  --dry-run
+```
+
+## 🔒 Security Checklist
+
+Before you start, verify these security measures are in place:
+
+- [x] `.gitignore` protects `.env` files ✓
+- [x] `.gitignore` protects `.pem` files ✓
+- [x] `.gitignore` protects `config.json` ✓
+- [ ] Private key has restricted permissions (`chmod 600`)
+- [ ] You're using the **demo** environment (not production)
+- [ ] You've verified credentials are not in any committed files
+
+**Check git status:**
+```bash
+git status
+```
+
+You should **NOT** see any of these files:
+- `.env`
+- `.env.local`
+- `*.pem`
+- `config.json`
+- `.kalshitools/`
+
+## 🆘 Troubleshooting
+
+### Problem: "Private key not found"
+
+**Solution:**
+```bash
+# Check the file exists
+ls -la ~/.kalshitools/demo-private-key.pem
+
+# Verify the path in config
+kalshitools config show
+
+# Re-run config init if needed
+kalshitools config init
+```
+
+### Problem: "Authentication failed"
+
+**Solution:**
+1. Verify your API Key ID is correct (check for typos)
+2. Ensure you downloaded the correct private key file
+3. Check the file isn't corrupted:
+   ```bash
+   head -1 ~/.kalshitools/demo-private-key.pem
+   # Should show: -----BEGIN PRIVATE KEY-----
+   ```
+4. Try regenerating credentials in the Kalshi Demo Portal
+
+### Problem: "Permission denied"
+
+**Solution:**
+```bash
+# Fix file permissions
+chmod 600 ~/.kalshitools/demo-private-key.pem
+```
+
+### Problem: "Environment variables not working"
+
+**Solution:**
+```bash
+# If using .env file, source it first
+source .env
+
+# Or export manually
+export KALSHI_ENV=demo
+export KALSHI_API_KEY_ID=your-email@example.com
+export KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
+
+# Then run commands
+kalshitools portfolio balance
+```
+
+## 📚 Next Steps
+
+Once you've verified everything works:
+
+1. **Explore the API**: Try different commands to familiarize yourself with the tool
+2. **Read the docs**: Check `docs/DEVELOPMENT.md` for detailed guides
+3. **Test safely**: Always use `--dry-run` when testing order placement
+4. **Get JSON output**: Add `--json` flag for programmatic use
+
+## 🔗 Useful Resources
+
+- **Kalshi Demo Portal**: https://demo-api.kalshi.co
+- **Kalshi API Documentation**: https://docs.kalshi.com
+- **Development Guide**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- **Main README**: [README.md](README.md)
+
+## 💡 Quick Tips
+
+1. **Always use demo environment for testing**
+   ```bash
+   echo $KALSHI_ENV  # Should be "demo"
+   ```
+
+2. **Use --dry-run first**
+   ```bash
+   kalshitools orders create ... --dry-run
+   ```
+
+3. **Get JSON for debugging**
+   ```bash
+   kalshitools markets list --json | jq
+   ```
+
+4. **Check config anytime**
+   ```bash
+   kalshitools config show
+   ```
+
+## ✅ Verification Checklist
+
+Before you start trading:
+
+- [ ] Demo API credentials obtained from Kalshi
+- [ ] Configuration completed (config init or .env)
+- [ ] Private key file placed in `~/.kalshitools/`
+- [ ] File permissions set to 600
+- [ ] `kalshitools config show` displays your email (redacted)
+- [ ] `kalshitools portfolio balance` returns successfully
+- [ ] You understand the difference between demo and production
+- [ ] You've tested with `--dry-run` flag
+
+---
+
+**Ready to go!** You're all set up for local testing with the demo API. 🚀

package/dist/commands/portfolio/balance.js

@@ -15,18 +15,23 @@ export default class PortfolioBalance extends BaseCommand {
             const client = createClientFromConfig();
             // Fetch balance
             const balance = await client.getBalance();
+            // Convert cents to dollars
+            const balanceDollars = balance.balance / 100;
+            const portfolioValueDollars = balance.portfolio_value / 100;
             if (this.formatter.isJSONMode()) {
-                this.formatter.success(balance);
+                // Return in dollars for readability
+                this.formatter.success({
+                    balance: balanceDollars,
+                    portfolio_value: portfolioValueDollars,
+                });
             }
             else {
                 this.log(chalk.cyan.bold('Account Balance'));
                 this.log();
-                this.log(`${chalk.cyan('Balance:')} ${chalk.green('$' + balance.balance.toFixed(2))}`);
-                this.log(`${chalk.cyan('Payout:')} ${chalk.yellow('$' + balance.payout.toFixed(2))}`);
-                this.log();
-                this.log(chalk.gray(`Total: $${(balance.balance + balance.payout).toFixed(2)}`));
+                this.log(`${chalk.cyan('Available:')} ${chalk.green('$' + balanceDollars.toFixed(2))}`);
+                this.log(`${chalk.cyan('Portfolio Value:')} ${chalk.yellow('$' + portfolioValueDollars.toFixed(2))}`);
             }
-            logger.info({ balance: balance.balance, payout: balance.payout }, 'Balance fetched successfully');
+            logger.info({ balance: balanceDollars, portfolio_value: portfolioValueDollars }, 'Balance fetched successfully');
         }
         catch (error) {
             // Error will be handled by BaseCommand.catch()

package/dist/lib/kalshi/client.js

@@ -42,13 +42,18 @@ export class KalshiClient {
         // Add request interceptor for authentication
         this.axios.interceptors.request.use((config) => {
             const method = (config.method || 'GET').toUpperCase();
-            const path = config.url || '/';
-            const authHeaders = this.auth.generateAuthHeaders(method, path);
+            // CRITICAL: Include baseURL pathname in signature
+            // Kalshi expects signature over full path: /trade-api/v2/portfolio/balance
+            // Not just the relative path: /portfolio/balance
+            const baseUrlPath = new URL(baseUrl).pathname;
+            const relativePath = config.url || '/';
+            const fullPath = baseUrlPath + relativePath;
+            const authHeaders = this.auth.generateAuthHeaders(method, fullPath);
             // Set auth headers
             for (const [key, value] of Object.entries(authHeaders)) {
                 config.headers.set(key, value);
             }
-            logger.debug({ method, path }, 'Making API request');
+            logger.debug({ method, path: fullPath }, 'Making API request');
             return config;
         });
         // Add response interceptor for error handling
@@ -94,7 +99,9 @@ export class KalshiClient {
                     details: response.data.error.details,
                 });
             }
-            return response.data.data;
+            // Kalshi API doesn't always wrap in a data envelope
+            // Return response.data.data if it exists, otherwise response.data
+            return (response.data.data ?? response.data);
         });
     }
     /**
@@ -109,7 +116,9 @@ export class KalshiClient {
                     details: response.data.error.details,
                 });
             }
-            return response.data.data;
+            // Kalshi API doesn't always wrap in a data envelope
+            // Return response.data.data if it exists, otherwise response.data
+            return (response.data.data ?? response.data);
         });
     }
     /**
@@ -124,7 +133,9 @@ export class KalshiClient {
                     details: response.data.error.details,
                 });
             }
-            return response.data.data;
+            // Kalshi API doesn't always wrap in a data envelope
+            // Return response.data.data if it exists, otherwise response.data
+            return (response.data.data ?? response.data);
         });
     }
     /**
@@ -139,7 +150,9 @@ export class KalshiClient {
      */
     async getPositions(params) {
         logger.info({ params }, 'Fetching portfolio positions');
-        return this.get('/portfolio/positions', { params });
+        const response = await this.get('/portfolio/positions', { params });
+        // Kalshi returns { market_positions: [...] }, not just the array
+        return response.market_positions || [];
     }
     /**
      * Get markets

package/dist/lib/kalshi/types.d.ts

@@ -17,7 +17,7 @@ export interface KalshiResponse<T> {
  */
 export interface Balance {
     balance: number;
-    payout: number;
+    portfolio_value: number;
 }
 /**
  * Market data

package/docs/DEVELOPMENT.md

@@ -0,0 +1,547 @@
+# Development Guide
+
+This guide covers setting up kalshitools for local development and testing.
+
+## Table of Contents
+
+- [Initial Setup](#initial-setup)
+- [API Credentials Setup](#api-credentials-setup)
+- [Configuration Methods](#configuration-methods)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+
+## Initial Setup
+
+### 1. Clone and Install
+
+```bash
+git clone https://github.com/yourusername/kalshitools.git
+cd kalshitools
+npm install
+```
+
+### 2. Build the Project
+
+```bash
+npm run build
+```
+
+### 3. Link for Local Development
+
+```bash
+npm link
+```
+
+Now you can use `kalshitools` command anywhere on your system.
+
+## API Credentials Setup
+
+### Obtain Demo API Credentials
+
+1. Visit [Kalshi Demo Portal](https://demo-api.kalshi.co)
+2. Sign up or log in to your demo account
+3. Navigate to API settings
+4. Generate a new API key pair:
+   - **API Key ID**: Your registered email address
+   - **Private Key**: Download the `.pem` file
+
+### Store Credentials Securely
+
+**IMPORTANT**: Never commit real credentials to the repository!
+
+The `.gitignore` file protects:
+- `*.pem`, `*.key`, `*-private-key*` (private keys)
+- `.env`, `.env.local`, `.env.*.local` (environment files)
+- `config.json`, `.kalshitools/` (config directory)
+
+## Configuration Methods
+
+### Method 1: Interactive Configuration (Recommended for Development)
+
+```bash
+# Run the configuration wizard
+kalshitools config init
+
+# Follow the prompts
+Environment: demo
+API Key ID: your-email@example.com
+Private Key Path: ~/.kalshitools/demo-private-key.pem
+```
+
+This creates `~/.config/kalshitools/config.json` with your settings.
+
+**Place your private key:**
+
+```bash
+mkdir -p ~/.kalshitools
+cp ~/Downloads/demo-private-key.pem ~/.kalshitools/demo-private-key.pem
+chmod 600 ~/.kalshitools/demo-private-key.pem
+```
+
+**Verify configuration:**
+
+```bash
+kalshitools config show
+```
+
+Expected output:
+```
+Kalshi API Configuration
+Environment: DEMO
+API Key ID: yo****@ex******.com
+Private Key Path: /Users/you/.kalshitools/demo-private-key.pem
+```
+
+### Method 2: Environment Variables (Quick Testing)
+
+Create a `.env` file in the project root:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+
+```bash
+KALSHI_ENV=demo
+KALSHI_API_KEY_ID=your-email@example.com
+KALSHI_PRIVATE_KEY_PATH=/absolute/path/to/demo-private-key.pem
+LOG_LEVEL=debug
+```
+
+**Use environment variables:**
+
+```bash
+# Source the file
+source .env
+
+# Or export manually
+export KALSHI_ENV=demo
+export KALSHI_API_KEY_ID=your-email@example.com
+export KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo-private-key.pem
+```
+
+### Method 3: Multiple Credential Sets
+
+For testing with multiple accounts:
+
+**Create separate env files:**
+
+```bash
+# Demo account 1
+cat > .env.demo1 <<EOF
+KALSHI_ENV=demo
+KALSHI_API_KEY_ID=demo1@example.com
+KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo1-private-key.pem
+EOF
+
+# Demo account 2
+cat > .env.demo2 <<EOF
+KALSHI_ENV=demo
+KALSHI_API_KEY_ID=demo2@example.com
+KALSHI_PRIVATE_KEY_PATH=~/.kalshitools/demo2-private-key.pem
+EOF
+```
+
+**Switch between accounts:**
+
+```bash
+# Use demo1
+source .env.demo1
+kalshitools portfolio balance
+
+# Use demo2
+source .env.demo2
+kalshitools portfolio balance
+```
+
+### Configuration Precedence
+
+Environment variables **override** config file values:
+
+1. **Environment Variables** (highest priority)
+   - `KALSHI_ENV`
+   - `KALSHI_API_KEY_ID`
+   - `KALSHI_PRIVATE_KEY_PATH`
+
+2. **Config File** (`~/.config/kalshitools/config.json`)
+   - Set via `kalshitools config init`
+
+3. **Default Values** (lowest priority)
+   - Environment: `demo`
+
+## Testing
+
+### Test API Connection
+
+```bash
+# Check configuration
+kalshitools config show
+
+# Test authentication and basic API call
+kalshitools portfolio balance
+```
+
+Expected output:
+```
+Account Balance
+Available: $10,000.00
+Total: $10,000.00
+```
+
+### Test Market Data
+
+```bash
+# List active markets
+kalshitools markets list --status active --limit 5
+
+# Get specific market details
+kalshitools markets show TICKER-SYMBOL
+```
+
+### Test Orders (Dry Run)
+
+**Always use `--dry-run` first:**
+
+```bash
+kalshitools orders create \
+  --ticker MARKET-TICKER \
+  --action buy \
+  --side yes \
+  --quantity 10 \
+  --type market \
+  --dry-run
+```
+
+This validates the order without actually placing it.
+
+### Test JSON Output
+
+```bash
+# JSON format for programmatic use
+kalshitools portfolio balance --json
+kalshitools markets list --json
+kalshitools orders list --json
+```
+
+### Run Unit Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- tests/commands/config/init.test.ts
+```
+
+## Troubleshooting
+
+### Issue: "Private key not found"
+
+**Symptoms:**
+```
+Error: ENOENT: no such file or directory, open '/path/to/private-key.pem'
+```
+
+**Solutions:**
+
+1. **Check the path in configuration:**
+   ```bash
+   kalshitools config show
+   ```
+
+2. **Verify file exists:**
+   ```bash
+   ls -la ~/.kalshitools/demo-private-key.pem
+   ```
+
+3. **Re-configure with correct path:**
+   ```bash
+   kalshitools config init --privateKeyPath /correct/path/to/key.pem
+   ```
+
+4. **Check tilde expansion:**
+   ```bash
+   # If using ~/ in path, ensure it's expanded
+   export KALSHI_PRIVATE_KEY_PATH="$HOME/.kalshitools/demo-private-key.pem"
+   ```
+
+### Issue: "Authentication failed"
+
+**Symptoms:**
+```
+Error: Authentication failed: Invalid credentials
+```
+
+**Solutions:**
+
+1. **Verify Key ID is correct:**
+   - Should be your email address from Kalshi
+   - Check for typos
+
+2. **Verify private key is not corrupted:**
+   ```bash
+   # Check file is readable and starts with "-----BEGIN PRIVATE KEY-----"
+   head -1 ~/.kalshitools/demo-private-key.pem
+   ```
+
+3. **Regenerate credentials:**
+   - Go to Kalshi Demo Portal
+   - Delete old API key
+   - Generate new key pair
+   - Update configuration
+
+4. **Check environment mismatch:**
+   ```bash
+   # Ensure you're using demo credentials with demo environment
+   kalshitools config show
+   # Environment should be "DEMO"
+   ```
+
+### Issue: "Permission denied reading private key"
+
+**Symptoms:**
+```
+Error: EACCES: permission denied, open '/path/to/private-key.pem'
+```
+
+**Solution:**
+
+```bash
+# Set proper permissions (read/write for owner only)
+chmod 600 ~/.kalshitools/demo-private-key.pem
+
+# Verify
+ls -la ~/.kalshitools/demo-private-key.pem
+# Should show: -rw-------
+```
+
+### Issue: "Command not found: kalshitools"
+
+**Solutions:**
+
+1. **Re-link after rebuild:**
+   ```bash
+   npm run build
+   npm link
+   ```
+
+2. **Check npm global bin path:**
+   ```bash
+   npm bin -g
+   # Ensure this directory is in your PATH
+   ```
+
+3. **Use local dev version:**
+   ```bash
+   ./bin/dev.js config show
+   ```
+
+### Issue: "Environment variables not being used"
+
+**Symptoms:**
+- Set `KALSHI_API_KEY_ID` but config shows different value
+
+**Solutions:**
+
+1. **Verify environment variables are set:**
+   ```bash
+   echo $KALSHI_API_KEY_ID
+   echo $KALSHI_PRIVATE_KEY_PATH
+   ```
+
+2. **Source the .env file:**
+   ```bash
+   source .env
+   # NOT: sh .env or bash .env
+   ```
+
+3. **Export manually:**
+   ```bash
+   export KALSHI_ENV=demo
+   export KALSHI_API_KEY_ID=your@email.com
+   ```
+
+4. **Check shell session:**
+   - Environment variables only persist in the current shell
+   - Open a new terminal? You need to source .env again
+
+### Issue: "Invalid ticker symbol"
+
+**Symptoms:**
+```
+Error: Market not found: TICKER-SYMBOL
+```
+
+**Solutions:**
+
+1. **List available markets first:**
+   ```bash
+   kalshitools markets list --status active
+   ```
+
+2. **Use exact ticker from market list:**
+   - Tickers are case-sensitive
+   - Copy-paste from `markets list` output
+
+3. **Check market status:**
+   ```bash
+   # Market might be closed or settled
+   kalshitools markets show TICKER-SYMBOL
+   ```
+
+## Best Practices
+
+### Development Workflow
+
+1. **Always use demo environment for testing:**
+   ```bash
+   export KALSHI_ENV=demo
+   ```
+
+2. **Use `--dry-run` for order testing:**
+   ```bash
+   kalshitools orders create ... --dry-run
+   ```
+
+3. **Use `--json` for debugging:**
+   ```bash
+   kalshitools markets list --json | jq
+   ```
+
+4. **Set debug logging when developing:**
+   ```bash
+   export LOG_LEVEL=debug
+   ```
+
+### Security Best Practices
+
+1. **Never commit credentials:**
+   - Always check `.gitignore` before pushing
+   - Use `git status` to verify no credential files
+
+2. **Use restrictive file permissions:**
+   ```bash
+   chmod 600 ~/.kalshitools/*.pem
+   ```
+
+3. **Separate demo and production:**
+   - Use different key pairs
+   - Store production keys outside the repo
+   - Double-check `KALSHI_ENV` before trading
+
+4. **Rotate keys regularly:**
+   - Regenerate API keys periodically
+   - Delete old keys from Kalshi portal
+
+### Testing Best Practices
+
+1. **Test configuration first:**
+   ```bash
+   kalshitools config show
+   ```
+
+2. **Verify connectivity:**
+   ```bash
+   kalshitools portfolio balance
+   ```
+
+3. **Use small quantities for testing:**
+   ```bash
+   --quantity 1  # Not --quantity 1000
+   ```
+
+4. **Always check order details:**
+   ```bash
+   # Review the order summary before confirming
+   # Use --yes to skip confirmation (be careful!)
+   ```
+
+### Code Development
+
+1. **Run tests before committing:**
+   ```bash
+   npm test
+   ```
+
+2. **Build and test locally:**
+   ```bash
+   npm run build
+   ./bin/dev.js config show
+   ```
+
+3. **Use TypeScript types:**
+   - Leverage the typed API client
+   - Check `src/lib/types.ts` for available types
+
+4. **Follow existing patterns:**
+   - Look at existing commands for structure
+   - Use oclif conventions
+   - Add tests for new features
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Configuration
+kalshitools config init                    # Interactive setup
+kalshitools config show                    # View config (redacted)
+kalshitools config show --json             # JSON output
+
+# Portfolio
+kalshitools portfolio balance              # Account balance
+kalshitools portfolio positions            # Current positions
+kalshitools portfolio fills                # Trade history
+
+# Markets
+kalshitools markets list                   # All markets
+kalshitools markets list --status active   # Active only
+kalshitools markets show TICKER            # Market details
+
+# Orders
+kalshitools orders list                    # Your orders
+kalshitools orders create ...              # Place order
+kalshitools orders create ... --dry-run    # Simulate order
+kalshitools orders cancel ORDER_ID         # Cancel order
+
+# Help
+kalshitools --help                         # Main help
+kalshitools COMMAND --help                 # Command help
+```
+
+### Environment Variables
+
+```bash
+KALSHI_ENV=demo                            # demo or production
+KALSHI_API_KEY_ID=your@email.com           # Your email
+KALSHI_PRIVATE_KEY_PATH=/path/to/key.pem   # Private key path
+LOG_LEVEL=debug                            # Logging level
+```
+
+### File Locations
+
+```
+~/.config/kalshitools/config.json          # Main config file
+~/.kalshitools/demo-private-key.pem        # Default key location
+.env                                        # Local env vars (gitignored)
+.env.example                               # Template (committed)
+```
+
+## Getting Help
+
+- **Issues**: https://github.com/yourusername/kalshitools/issues
+- **Kalshi API Docs**: https://docs.kalshi.com
+- **Demo Portal**: https://demo-api.kalshi.co
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on:
+- Code style
+- Pull request process
+- Testing requirements
+- Documentation standards

package/oclif.manifest.json

@@ -516,5 +516,5 @@
       ]
     }
   },
-  "version": "1.0.0"
+  "version": "1.0.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gaberoo/kalshitools",
   "description": "CLI for interacting with Kalshi prediction markets API",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -45,7 +45,11 @@
   "files": [
     "./bin",
     "./dist",
-    "./oclif.manifest.json"
+    "./oclif.manifest.json",
+    "./docs",
+    "./SETUP_DEMO_API.md",
+    "./.env.local.example",
+    "./.env.example"
   ],
   "homepage": "https://github.com/kalshitools/kalshitools",
   "keywords": [