cost-katana-cli 2.1.1 → 2.2.1

package/README.md

@@ -1,227 +1,198 @@
 # Cost Katana CLI 🥷
 
-**Chat with AI from your terminal. Track costs automatically.**
+> **AI in your terminal. Costs on your screen.**
 
-```bash
-$ cost-katana chat
-
-You: Hello!
-AI: Hi! How can I help you today?
-💰 Cost: $0.0001
+Chat with GPT-4, Claude, Gemini—all from one command. See exactly what you spend, in real-time.
 
-You: Write me a Python function
-AI: Here's a Python function...
-💰 Session: $0.0023
-```
+---
 
-Simple. Powerful. Cost-aware.
+## 🚀 Get Started in 30 Seconds
 
-## Installation
+### Step 1: Install
 
 ```bash
 npm install -g cost-katana-cli
 ```
 
-## Quick Start
-
-### 1. Setup (One-time)
+### Step 2: Initialize
 
 ```bash
 cost-katana init
 ```
 
-Answer 2 questions:
-1. Your API key (from [costkatana.com](https://costkatana.com))
-2. Your default AI model
-
-Done! ✅
-
-### 2. Start Chatting
+### Step 3: Chat
 
 ```bash
 cost-katana chat
 ```
 
-That's it!
-
----
-
-## 📚 **More Examples**
-
-**Looking for more comprehensive examples?** Check out our complete examples repository
+```
+You: Hello!
+AI: Hi! How can I help you today?
+💰 Cost: $0.0001
 
-**🔗 [github.com/Hypothesize-Tech/costkatana-examples](https://github.com/Hypothesize-Tech/costkatana-examples)**
+You: Write me a Python function to sort a list
+AI: Here's a Python function...
+💰 Session: $0.0023
+```
 
-**What's included:**
-- ✅ 44 feature sections covering every Cost Katana capability
-- ✅ CLI examples and guides in [Section 9](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/9-cli)
-- ✅ HTTP REST API examples (`.http` files)
-- ✅ TypeScript/Node.js examples
-- ✅ Python SDK examples
-- ✅ Framework integrations (Express, Next.js, Fastify, NestJS, FastAPI)
-- ✅ Real-world use cases with best practices
-
-**Popular examples:**
-- [CLI Examples](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/9-cli) - Complete CLI guides
-- [Cost Tracking](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/1-cost-tracking) - Track costs across all providers
-- [Webhooks](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/10-webhooks) - Real-time notifications
-- [Workflows](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/13-workflows) - Multi-step AI orchestration
-- [Semantic Caching](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/14-cache) - 30-40% cost reduction
+**That's it.** You're now chatting with AI and tracking every cent.
 
 ---
 
-## Essential Commands
+## 📖 Tutorial: Master the CLI
 
-### Chat with AI
+### Part 1: Interactive Chat
+
+Start a conversation that remembers context:
 
 ```bash
-# Start interactive chat
 cost-katana chat
+```
 
-# Use specific model
-cost-katana chat --model claude-3-sonnet
+**In-session commands:**
+| Command | Action |
+|---------|--------|
+| `help` | Show all commands |
+| `cost` | Display session cost |
+| `models` | Switch AI model |
+| `clear` | Clear chat history |
+| `save` | Export conversation |
+| `quit` | Exit chat |
 
-# With system prompt
-cost-katana chat --system "You are a coding expert"
-```
+### Part 2: Quick Questions
 
-### Quick Question (No chat mode)
+Skip chat mode for one-off questions:
 
 ```bash
-# Ask a single question
+# Get an instant answer
 cost-katana ask "What is the capital of France?"
 
-# Save answer to file
-cost-katana ask "Explain Python" --output answer.txt
+# Save output to file
+cost-katana ask "Explain recursion" --output answer.md
 
-# Use different model
-cost-katana ask "Write a poem" --model gpt-4
+# Use a specific model
+cost-katana ask "Write a haiku" --model gpt-4
 ```
 
-### Analyze Costs
+### Part 3: Choose Your Model
 
 ```bash
-# See your spending
-cost-katana analyze
+# Use Claude for creative writing
+cost-katana chat --model claude-3-sonnet
 
-# Last 7 days
-cost-katana analyze --days 7
+# Use GPT-4 for complex reasoning
+cost-katana chat --model gpt-4
 
-# Export to CSV
-cost-katana analyze --export costs.csv
+# Use GPT-3.5 for simple tasks (10x cheaper)
+cost-katana chat --model gpt-3.5-turbo
 ```
 
-### List Models
+### Part 4: Add a System Prompt
+
+Shape the AI's personality:
 
 ```bash
-# See available models
-cost-katana models
+# Code reviewer
+cost-katana chat --system "You are a senior developer. Be concise and critical."
 
-# Filter by provider
-cost-katana models --provider openai
+# Writing assistant
+cost-katana chat --system "You are a professional copywriter. Focus on clarity."
 
-# Show with prices
-cost-katana models --prices
+# Tutor
+cost-katana chat --system "You are a patient teacher. Explain concepts step by step."
 ```
 
-### Supported Models
-
-The CLI uses type-safe model constants internally for reliability and autocomplete support. All models from the following providers are supported:
-
-**OpenAI**
-- GPT-5, GPT-5 Mini, GPT-5 Nano, GPT-5 Pro
-- GPT-4, GPT-4 Turbo, GPT-4o, GPT-4o Mini
-- GPT-3.5 Turbo
-- O1, O1 Mini, O1 Preview
-- DALL-E, Whisper, TTS
+### Part 5: Enable Cost Optimization
 
-**Anthropic**
-- Claude Sonnet 4.5
-- Claude 3.5 Sonnet, Claude 3.5 Haiku
-- Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku
+```bash
+# Cortex: 40-75% savings on long content
+cost-katana chat --cortex
 
-**Google**
-- Gemini 2.5 Pro, Gemini 2.5 Flash
-- Gemini 1.5 Pro, Gemini 1.5 Flash
+# Caching: 100% savings on repeated questions
+cost-katana chat --cache
 
-**AWS Bedrock**
-- Claude models via Bedrock
-- Titan models
-- Mistral models
+# Both together
+cost-katana chat --cortex --cache
+```
 
-**Others**
-- xAI Grok models
-- DeepSeek models
-- Mistral AI models
-- Cohere models
-- Groq models
-- Meta Llama models
+---
 
-For the complete list, run `cost-katana models` or visit [costkatana.com/docs](https://costkatana.com/docs)
+## 🎯 Essential Commands
 
-## Chat Session Commands
+### Chat
 
-While in a chat session, you can use:
+```bash
+cost-katana chat                              # Start interactive chat
+cost-katana chat --model claude-3-sonnet      # Use specific model
+cost-katana chat --system "Be concise"        # Add system prompt
+cost-katana chat --cortex                     # Enable optimization
+```
 
-- `help` - Show commands
-- `cost` - Show session cost
-- `models` - Switch model
-- `clear` - Clear history
-- `save` - Save conversation
-- `quit` - Exit
+### Ask
 
-## Advanced Features
+```bash
+cost-katana ask "Your question"               # Quick answer
+cost-katana ask "Question" --output file.md   # Save to file
+cost-katana ask "Question" --model gpt-4      # Use specific model
+```
 
-### Cost Optimization
+### Analyze
 
 ```bash
-# Enable Cortex (40-75% savings)
-cost-katana chat --cortex
-
-# Enable caching
-cost-katana chat --cache
+cost-katana analyze                           # View spending summary
+cost-katana analyze --days 7                  # Last 7 days
+cost-katana analyze --export costs.csv        # Export to CSV
 ```
 
-### Compare Models
+### Models
 
 ```bash
-# Compare costs across models
-cost-katana compare "Explain AI" --models gpt-4,claude-3-sonnet,gemini-pro
+cost-katana models                            # List all models
+cost-katana models --provider openai          # Filter by provider
+cost-katana models --prices                   # Show pricing
 ```
 
-### Budget Tracking
+### Compare
 
 ```bash
-# Set daily budget
-cost-katana budget set --daily 10
+cost-katana compare "Your prompt" --models gpt-4,claude-3-sonnet,gemini-pro
+```
 
-# Check budget status
-cost-katana budget status
+### Budget
 
-# Get alerts
-cost-katana budget alerts
+```bash
+cost-katana budget set --daily 10             # Set $10/day limit
+cost-katana budget status                     # Check remaining budget
+cost-katana budget alerts                     # View alerts
 ```
 
-## Configuration
-
-### View Config
+### Config
 
 ```bash
-cost-katana config
+cost-katana config                            # View current config
+cost-katana config set model gpt-4            # Change default model
+cost-katana config set temperature 0.7        # Set creativity level
+cost-katana config set daily-limit 5          # Set spending limit
 ```
 
-### Update Settings
+---
 
-```bash
-# Change default model
-cost-katana config set model gpt-4
+## 🤖 Supported Models
 
-# Set temperature
-cost-katana config set temperature 0.7
+| Provider | Models |
+|----------|--------|
+| **OpenAI** | GPT-5, GPT-4, GPT-4 Turbo, GPT-4o, GPT-3.5 Turbo, O1, O3 |
+| **Anthropic** | Claude Sonnet 4.5, Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus |
+| **Google** | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 1.5 Pro, Gemini 1.5 Flash |
+| **AWS Bedrock** | Claude, Titan, Mistral, Nova models |
+| **Others** | xAI Grok, DeepSeek, Mistral AI, Cohere, Meta Llama |
 
-# Set daily limit
-cost-katana config set daily-limit 5
-```
+Run `cost-katana models` for the complete list with pricing.
+
+---
+
+## ⚙️ Configuration
 
 ### Environment Variables
 
@@ -230,184 +201,189 @@ cost-katana config set daily-limit 5
 export COST_KATANA_API_KEY="dak_your_key"
 export COST_KATANA_MODEL="gpt-4"
 
-# Option 2: Direct Provider Keys (for self-hosted)
-# ⚠️ USER PROVIDED - CostKATANA does not include these keys
-export OPENAI_API_KEY="sk-..."        # Required for OpenAI models (GPT-4, GPT-3.5)
-export GEMINI_API_KEY="..."           # Required for Gemini models (Gemini 2.5, etc.)
-export AWS_ACCESS_KEY_ID="..."        # For AWS Bedrock (Claude, Nova)
+# Option 2: Direct Provider Keys (self-hosted)
+export OPENAI_API_KEY="sk-..."          # Required for GPT models
+export GEMINI_API_KEY="..."             # Required for Gemini models
+export AWS_ACCESS_KEY_ID="..."          # For AWS Bedrock
 export AWS_SECRET_ACCESS_KEY="..."
 ```
 
-> **⚠️ Important**: When using self-hosted mode, you must provide your own OpenAI and Gemini API keys.
+> ⚠️ **Self-hosted users**: You must provide your own OpenAI/Gemini API keys.
+
+---
 
-## Real-World Examples
+## 💡 Real-World Examples
 
-### Code Assistant
+### Code Review Assistant
 
 ```bash
 $ cost-katana chat --system "You are a senior developer. Be concise."
 
 You: Review this code: [paste code]
-AI: Here are the issues...
+AI: Issues found:
+    1. Missing error handling on line 15
+    2. Inefficient loop—use map() instead
+    3. Variable 'x' should be descriptive
 💰 Cost: $0.0045
 
 You: How do I fix issue #2?
-AI: Here's how to fix it...
+AI: Replace the for loop with: const results = items.map(item => transform(item));
 💰 Session: $0.0067
 ```
 
-### Content Writer
+### Content Writer with Optimization
 
 ```bash
 $ cost-katana chat --model gpt-4 --cortex
 
-You: Write a blog post about AI
-AI: [Generates comprehensive post with 70% cost savings]
+You: Write a blog post about machine learning trends in 2024
+AI: [Generates comprehensive 1500-word post]
 💰 Cost: $0.0123 (saved $0.041 with Cortex!)
 ```
 
-### Quick Answers
+### Quick Research
 
 ```bash
-# Get quick answers without entering chat mode
-$ cost-katana ask "What's the weather API for Node.js?"
-> Use the 'axios' library to call weather APIs like OpenWeatherMap...
+$ cost-katana ask "Best Node.js weather API libraries"
+> Popular options: axios + OpenWeatherMap, node-fetch + WeatherAPI...
 💰 Cost: $0.0002
 
-$ cost-katana ask "Python sort list by date" --output answer.md
-✅ Saved to answer.md
+$ cost-katana ask "Python datetime format examples" --output cheatsheet.md
+✅ Saved to cheatsheet.md
 💰 Cost: $0.0003
 ```
 
-## Tips
-
-### Save Money
+### Model Cost Comparison
 
 ```bash
-# Use cheaper models for simple tasks
-cost-katana chat --model gpt-3.5-turbo    # 10x cheaper
-
-# Enable optimization for long content
-cost-katana chat --cortex                  # 70-95% savings
-
-# Cache repeated queries
-cost-katana chat --cache                   # Free repeated answers
-```
-
-### Productivity
+$ cost-katana compare "Explain quantum computing" --models gpt-4,gpt-3.5-turbo,gemini-pro
 
-```bash
-# Save conversations
-cost-katana chat --output session.json
+📊 Cost Comparison
 
-# Load previous conversation
-cost-katana chat --file session.json
+Model              Cost        Tokens    Latency
+─────────────────────────────────────────────────
+gpt-4              $0.0120     450       2.3s
+gpt-3.5-turbo      $0.0012     420       0.8s
+gemini-pro         $0.0003     435       1.1s
 
-# Pipe output
-cost-katana ask "List of AI models" | grep gpt
+💡 Recommendation: gemini-pro (40x cheaper than gpt-4)
 ```
 
-## Comparison
-
-### Traditional AI CLIs
-
-```bash
-# Complex setup
-export OPENAI_API_KEY="sk-..."
-export ANTHROPIC_API_KEY="sk-ant-..."
+---
 
-# Different commands for each provider
-openai chat
-anthropic messages create
-```
+## 💰 Cost Optimization Tips
 
-### Cost Katana CLI
+| Strategy | Savings | Command |
+|----------|---------|---------|
+| Use GPT-3.5 for simple tasks | 90% | `--model gpt-3.5-turbo` |
+| Enable Cortex for long content | 40-75% | `--cortex` |
+| Cache repeated queries | 100% | `--cache` |
+| Use Gemini for high-volume | 95% | `--model gemini-pro` |
 
 ```bash
-# Simple setup
-cost-katana init
+# ❌ Expensive
+cost-katana chat --model gpt-4
 
-# One command for all providers
-cost-katana chat
+# ✅ Smart: Match model to task
+cost-katana chat --model gpt-3.5-turbo
 
-# Automatic cost tracking!
+# ✅ Smarter: Add optimization
+cost-katana chat --model gpt-3.5-turbo --cortex --cache
 ```
 
-## Troubleshooting
+---
+
+## 🔧 Troubleshooting
 
 ### "API key not found"
 
 ```bash
-# Run init again
 cost-katana init
-
-# Or set environment variable
+# or
 export COST_KATANA_API_KEY="dak_your_key"
 ```
 
 ### "Model not available"
 
 ```bash
-# See available models
-cost-katana models
-
-# Try a different model
-cost-katana chat --model gpt-3.5-turbo
+cost-katana models                    # See available models
+cost-katana chat --model gpt-3.5-turbo  # Try alternative
 ```
 
 ### "Rate limit exceeded"
 
 ```bash
-# CLI automatically retries
-# If persistent, try different model:
-cost-katana chat --model claude-3-haiku
+# CLI auto-retries. If persistent:
+cost-katana chat --model claude-3-haiku  # Switch provider
 ```
 
-## Dashboard Integration
+---
+
+## 📊 Dashboard Integration
 
-All your CLI usage is tracked at [costkatana.com/dashboard](https://costkatana.com/dashboard):
+All CLI usage syncs to [costkatana.com/dashboard](https://costkatana.com/dashboard):
 
 - Real-time cost tracking
-- Usage by model
+- Usage breakdown by model
 - Daily/weekly/monthly stats
 - Budget alerts
-- Optimization tips
+- Optimization recommendations
 
-```bash
-# Every command is tracked
-cost-katana chat
-cost-katana ask "Hello"
+---
 
-# View at: https://costkatana.com/dashboard
-```
+## 📚 More Examples
 
-## Why Cost Katana CLI?
+Explore 45+ complete examples:
 
-✅ **Simple**: 2-step setup, then just `cost-katana chat`  
-✅ **Universal**: Works with all AI providers  
-✅ **Cost-Aware**: See costs in real-time  
-✅ **Optimized**: Built-in 70-95% cost reduction  
-✅ **Tracked**: Everything logged to dashboard  
-✅ **Beautiful**: Clean, colorful terminal UI  
+**🔗 [github.com/Hypothesize-Tech/costkatana-examples](https://github.com/Hypothesize-Tech/costkatana-examples)**
 
-## Support
+| Section | Description |
+|---------|-------------|
+| [CLI Examples](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/9-cli) | Complete CLI guides |
+| [Cost Tracking](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/1-cost-tracking) | Track costs across providers |
+| [Semantic Caching](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/14-cache) | 30-40% cost reduction |
+| [Workflows](https://github.com/Hypothesize-Tech/costkatana-examples/tree/master/13-workflows) | Multi-step AI orchestration |
 
-- **Documentation**: https://docs.costkatana.com/cli
-- **Dashboard**: https://costkatana.com
-- **GitHub**: https://github.com/Hypothesize-Tech/costkatana-cli
-- **Discord**: https://discord.gg/D8nDArmKbY
-- **Email**: support@costkatana.com
+---
 
-## License
+## 🆚 Why Cost Katana CLI?
+
+| Feature | Traditional CLIs | Cost Katana CLI |
+|---------|------------------|-----------------|
+| Setup | Multiple API keys | One command: `cost-katana init` |
+| Providers | One per tool | All providers, one command |
+| Cost tracking | ❌ | ✅ Real-time |
+| Optimization | ❌ | ✅ 40-75% savings |
+| Dashboard | ❌ | ✅ Full analytics |
+
+---
+
+## 📞 Support
+
+| Channel | Link |
+|---------|------|
+| **Documentation** | [docs.costkatana.com/cli](https://docs.costkatana.com/cli) |
+| **Dashboard** | [costkatana.com](https://costkatana.com) |
+| **GitHub** | [github.com/Hypothesize-Tech/costkatana-cli](https://github.com/Hypothesize-Tech/costkatana-cli) |
+| **Discord** | [discord.gg/D8nDArmKbY](https://discord.gg/D8nDArmKbY) |
+| **Email** | support@costkatana.com |
+
+---
+
+## 📄 License
 
 MIT © Cost Katana
 
 ---
 
-**Start chatting with AI in your terminal!**
+<div align="center">
+
+**Start chatting with AI in your terminal** 🥷
 
 ```bash
 npm install -g cost-katana-cli
 cost-katana init
 cost-katana chat
-```
+```
+
+</div>

package/dist/commands/models.js

@@ -174,7 +174,7 @@ async function handleModels(options) {
     console.log(chalk_1.default.white('   • Use GPT-3.5-Turbo for simple tasks (10x cheaper than GPT-4)'));
     console.log(chalk_1.default.white('   • Use Claude-3-Haiku for fast, affordable responses'));
     console.log(chalk_1.default.white('   • Use Gemini-Flash for ultra-low cost'));
-    console.log(chalk_1.default.white('   • Enable --cortex for 70-95% additional savings on any model'));
+    console.log(chalk_1.default.white('   • Enable --cortex for 40-75% additional savings on any model'));
     console.log(chalk_1.default.gray('\nTo use a model:'));
     console.log(chalk_1.default.white('   cost-katana chat --model <model-name>'));
     console.log(chalk_1.default.white('   cost-katana ask "question" --model <model-name>'));

package/dist/constants/models.js

@@ -368,7 +368,7 @@ function getProviderFromModel(modelId) {
     if (cohereModels.includes(modelId))
         return 'Cohere';
     if (groqModels.includes(modelId))
-        return 'Groq';
+        return 'Grok';
     if (metaModels.includes(modelId))
         return 'Meta';
     return 'unknown';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cost-katana-cli",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "The simplest AI CLI. Chat with any AI model and track costs automatically.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,9 +27,9 @@
     "ci:build": "npm run build",
     "ci:check": "npm pack --dry-run",
     "ci:security": "npm audit --audit-level=moderate",
-    "release:patch": "npm version patch && git push origin master --follow-tags",
-    "release:minor": "npm version minor && git push origin master --follow-tags",
-    "release:major": "npm version major && git push origin master --follow-tags"
+    "release:patch": "git diff --cached --quiet || git commit -m 'chore: prepare for release' || true; git diff --quiet || (echo 'Error: Unstaged changes detected. Please commit or stash changes first.' && exit 1); npm version patch && git push origin master --follow-tags",
+    "release:minor": "git diff --cached --quiet || git commit -m 'chore: prepare for release' || true; git diff --quiet || (echo 'Error: Unstaged changes detected. Please commit or stash changes first.' && exit 1); npm version minor && git push origin master --follow-tags",
+    "release:major": "git diff --cached --quiet || git commit -m 'chore: prepare for release' || true; git diff --quiet || (echo 'Error: Unstaged changes detected. Please commit or stash changes first.' && exit 1); npm version major && git push origin master --follow-tags"
   },
   "keywords": [
     "ai",