Update cli-usage.md

Author: AndrewClements84

docs/cli-usage.md

@@ -1,77 +1,124 @@
-# 💻 CLI Usage Guide
+# ⚙️ CLI Usage — PromptStream.AI
 
-The **PromptStream.AI CLI** allows you to quickly build, validate, and generate prompts directly from the terminal.
+The **PromptStream.AI CLI** lets you build, validate, and analyze prompt templates directly from your terminal.
+It provides a clean developer workflow for experimenting with the Flow.AI ecosystem (Flow.AI.Core, TokenFlow.AI, and PromptStream.AI).
 
 ---
 
-## 🧱 Build
+## 🚀 Installation
 
-Render a prompt template with variables.
+Install the global tool via NuGet:
 
 ```bash
-promptstream build --template "./examples/welcome.txt" --var name=Andrew
+dotnet tool install --global promptstream.ai.cli
 ```
 
-Outputs:
-```
-✅ Prompt built successfully:
-Hello Andrew, welcome to PromptStream.AI!
-```
+Once installed, you can call it using the `promptstream` command from anywhere.
 
 ---
 
-## ✅ Validate
+## 🧱 Basic Commands
+
+### 🧩 Build
 
-Validate a prompt for completeness and token safety.
+Render and substitute variables in a template.
 
 ```bash
-promptstream validate --template "./examples/summary.txt" --var topic=AI
+promptstream build --template "Hello {{name}}" --var name=Andrew
 ```
 
----
+### 🔍 Validate
 
-Outputs:
-```
-✅ Valid prompt (37 tokens)
-```
+Check structure, token limits, and syntax.
 
----
+```bash
+promptstream validate --template "Summarize {{text}}" --var text="PromptStream.AI is awesome"
+```
 
-## 🤖 Generate
+### 📊 Analyze
 
-Build, validate, and generate a model reply.
+Estimate token counts and cost for a given prompt.
 
 ```bash
-promptstream generate --template "./examples/summary.txt" --var topic=AI
+promptstream analyze --template "Explain quantum computing simply."
 ```
 
-Outputs:
-```
-✅ Generation complete:
-[TokenFlow gpt-4o-mini] processed 32 tokens.
-```
+### 💬 Generate
 
----
+Build, validate, and request a response from the model provider.
+
+```bash
+promptstream generate --template "Write a haiku about AI" --save context.json
+```
 
-## 💬 Context
+### 🧠 Context
 
-Inspect or manage conversation history.
+Inspect, summarize, or clear conversation history.
 
 ```bash
 promptstream context --load context.json --summarize
-promptstream context --clear --save context.json
 ```
 
-Outputs:
+---
+
+## 🧩 Command Reference
+
+| Command | Description |
+|----------|--------------|
+| `build` | Renders and substitutes variables in a template. |
+| `validate` | Validates prompt structure and token usage. |
+| `analyze` | Estimates token usage and cost metrics. |
+| `generate` | Generates model output for a prompt. |
+| `context` | Loads, saves, summarizes, or clears context data. |
+
+---
+
+## 💡 Options
+
+| Option | Description |
+|---------|-------------|
+| `--template <value>` | Path to a `.json` file or inline text content. |
+| `--var <key=value>` | Variables to substitute (multiple allowed). |
+| `--context <path>` | Path to an existing context JSON file. |
+| `--save <path>` | Destination path to save context or output. |
+| `--model <id>` | Optional model ID (e.g. `gpt-4o-mini`). |
+| `--output <format>` | Output format (table or json). |
+
+---
+
+## 📸 Example Output
+
 ```
-📂 Loaded 4 messages from context.json
-Summary: 4 messages (user, assistant)
+📊 Prompt Analysis
+────────────────────────────────────────
+Model: gpt-4o-mini
+Prompt Tokens:     128
+Completion Tokens: 142
+Total Tokens:      270
+Estimated Cost:    $0.00052
+────────────────────────────────────────
+✅  Analysis complete — total tokens: 270
 ```
 
 ---
 
-### 🌈 Tips
+## 🧠 Integration Notes
+
+- The CLI uses **PromptStream.AI** services under the hood, leveraging Flow.AI.Core’s shared models.  
+- Variable substitution is handled via the same builder logic used by the library itself.  
+- Each command mirrors a service call: *Build → Validate → Analyze → Generate.*
+
+---
+
+## 🗺️ Links
+
+- [PromptStream.AI on GitHub](https://github.com/AndrewClements84/PromptStream.AI)
+- [NuGet Package](https://www.nuget.org/packages/PromptStream.AI.CLI)
+- [PromptStream.AI Docs](https://andrewclements84.github.io/PromptStream.AI)
+
+---
+
+**Author:** [AndrewClements84](https://github.com/AndrewClements84)  
+**License:** MIT  
+**Version:** 0.8.3
 
-- Use `--template` for inline text or a file path.  
-- Chain variables with multiple `--var` arguments.  
-- Combine `--context` and `--save` to preserve conversation state.