@zds-ai/cli 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 A conversational AI CLI tool powered by Grok with intelligent text editor capabilities and tool usage.
 
-<img width="980" height="435" alt="Screenshot 2025-07-21 at 13 35 41" src="https://github.com/user-attachments/assets/192402e3-30a8-47df-9fc8-a084c5696e78" />
+<img width="720" height="528" alt="Image" src="https://github.com/user-attachments/assets/f697a273-141e-4f02-8c15-37143aa7ec0e" />
 
 ## Features
 
@@ -22,6 +22,26 @@ A conversational AI CLI tool powered by Grok with intelligent text editor capabi
 - GROK API key from X.AI
 - (Optional, Recommended) Morph API key for Fast Apply editing
 
+### System Dependencies
+
+zai-cli requires the following system tools for certain features:
+
+- **ripgrep** (required for search functionality)
+  - macOS: `brew install ripgrep`
+  - Ubuntu/Debian: `apt install ripgrep`
+  - Windows: `choco install ripgrep` or download from [releases](https://github.com/BurntSushi/ripgrep/releases)
+  - Other platforms: See [ripgrep installation guide](https://github.com/BurntSushi/ripgrep#installation)
+
+- **Python 3 with openpyxl** (optional, required for XLSX file reading)
+  - Install: `pip3 install openpyxl` or `python3 -m pip install openpyxl`
+  - Most systems already have Python 3 installed
+
+- **exiftool** (optional, required for PNG metadata extraction)
+  - macOS: `brew install exiftool`
+  - Ubuntu/Debian: `apt install libimage-exiftool-perl`
+  - Windows: Download from [exiftool.org](https://exiftool.org/)
+  - Other platforms: See [exiftool installation guide](https://exiftool.org/install.html)
+
 ### Global Installation (Recommended)
 
 ```sh
@@ -49,52 +69,52 @@ bun link
 1. Get your GROK API key from [X.AI](https://x.ai)
 
 2. Set up your API key (choose one method):
-
-**Method 1: Environment Variable**
-
-```sh
-export GROK_API_KEY=your_api_key_here
-```
-
-**Method 2: .env File**
-
-```sh
-cp .env.example .env
-# Edit .env and add your API key
-```
-
-**Method 3: Command Line Flag**
-
-```sh
-zai-cli --api-key your_api_key_here
-```
-
-**Method 4: User Settings File**
-
-Create `~/.grok/user-settings.json`:
-
-```json
-{
-  "apiKey": "your_api_key_here"
-}
-```
+    
+    **Method 1: Environment Variable**
+    
+    ```sh
+    export GROK_API_KEY=your_api_key_here
+    ```
+    
+    **Method 2: .env File**
+    
+    ```sh
+    cp .env.example .env
+    # Edit .env and add your API key
+    ```
+    
+    **Method 3: Command Line Flag**
+    
+    ```sh
+    zai-cli --api-key your_api_key_here
+    ```
+    
+    **Method 4: User Settings File**
+    
+    Create `~/.grok/user-settings.json`:
+    
+    ```json
+    {
+      "apiKey": "your_api_key_here"
+    }
+    ```
 
 3. (Optional, Recommended) Get your Morph API key from [Morph Dashboard](https://morphllm.com/dashboard/api-keys)
 
 4. Set up your Morph API key for Fast Apply editing (choose one method):
 
-**Method 1: Environment Variable**
-
-```sh
-export MORPH_API_KEY=your_morph_api_key_here
-```
-
-**Method 2: .env File**
-
-```sh
-# Add to your .env file
-MORPH_API_KEY=your_morph_api_key_here
-```
+    **Method 1: Environment Variable**
+    
+    ```sh
+    export MORPH_API_KEY=your_morph_api_key_here
+    ```
+    
+    **Method 2: .env File**
+    
+    ```sh
+    # Add to your .env file
+    MORPH_API_KEY=your_morph_api_key_here
+    ```
 
 ### Custom Base URL (Optional)
 
@@ -319,6 +339,38 @@ Add to `~/.grok/user-settings.json`:
 
 **Model Priority**: `--model` flag > `GROK_MODEL` environment variable > user default model > system default (grok-code-fast-1)
 
+### Image Support
+
+zai-cli supports sending images to vision-capable AI models.  Use the `@` prefix to reference image files in your messages:
+
+```sh
+# Absolute path
+zai-cli --prompt "What's in this image? @/Users/joseph/photos/image.jpg"
+
+# Relative path
+zai-cli --prompt "Analyze @./screenshot.png"
+
+# Tilde expansion
+zai-cli --prompt "Describe @~/Pictures/photo.jpg"
+
+# Paths with spaces (quoted)
+zai-cli --prompt 'Compare these images: @"~/My Pictures/photo1.jpg" @"~/My Pictures/photo2.jpg"'
+
+# Paths with spaces (escaped)
+zai-cli --prompt "What's here? @/Users/joseph/My\ Documents/image.png"
+```
+
+**Supported Image Formats**: .jpg, .jpeg, .png, .gif, .webp, .bmp
+
+**Vision-Capable Models**: Image support works with vision models like:
+- `grok-4-1-fast-reasoning`
+- `grok-vision-beta`
+- Other vision-enabled models (via custom base URLs)
+
+**Automatic Fallback**: If you send an image to a model that doesn't support vision, zai-cli will automatically detect the error and retry with text-only content.
+
+**Interactive Mode**: The `@` syntax works in both interactive and headless (`--prompt`) modes.
+
 ### Command Line Options
 
 ```sh

package/dist/agent/grok-agent.d.ts

@@ -1,9 +1,10 @@
 import { GrokMessage, GrokToolCall } from "../grok/client.js";
+import type { ChatCompletionContentPart } from "openai/resources/chat/completions.js";
 import { ToolResult } from "../types/index.js";
 import { EventEmitter } from "events";
 export interface ChatEntry {
     type: "user" | "assistant" | "tool_result" | "tool_call" | "system";
-    content?: string;
+    content?: string | ChatCompletionContentPart[];
     timestamp: Date;
     tool_calls?: GrokToolCall[];
     toolCall?: GrokToolCall;
@@ -15,6 +16,10 @@ export interface ChatEntry {
     };
     isStreaming?: boolean;
     preserveFormatting?: boolean;
+    metadata?: {
+        rephrased_note?: string;
+        [key: string]: any;
+    };
 }
 export interface StreamingChunk {
     type: "content" | "tool_calls" | "tool_result" | "done" | "token_count" | "user_message";
@@ -61,7 +66,8 @@ export declare class GrokAgent extends EventEmitter {
     private activeTaskAction;
     private activeTaskColor;
     private apiKeyEnvVar;
-    private pendingContextEdit;
+    private pendingContextEditSession;
+    private rephraseState;
     constructor(apiKey: string, baseURL?: string, model?: string, maxToolRounds?: number, debugLogFile?: string, startupHookOutput?: string, temperature?: number, maxTokens?: number);
     private startupHookOutput?;
     private systemPrompt;
@@ -119,12 +125,20 @@ export declare class GrokAgent extends EventEmitter {
     getActiveTask(): string;
     getActiveTaskAction(): string;
     getActiveTaskColor(): string;
-    setPendingContextEdit(tmpJsonPath: string, contextFilePath: string): void;
-    getPendingContextEdit(): {
+    setPendingContextEditSession(tmpJsonPath: string, contextFilePath: string): void;
+    getPendingContextEditSession(): {
         tmpJsonPath: string;
         contextFilePath: string;
     } | null;
-    clearPendingContextEdit(): void;
+    clearPendingContextEditSession(): void;
+    setRephraseState(originalAssistantMessageIndex: number, rephraseRequestIndex: number, newResponseIndex: number, messageType: "user" | "system"): void;
+    getRephraseState(): {
+        originalAssistantMessageIndex: number;
+        rephraseRequestIndex: number;
+        newResponseIndex: number;
+        messageType: "user" | "system";
+    } | null;
+    clearRephraseState(): void;
     setPersona(persona: string, color?: string): Promise<{
         success: boolean;
         error?: string;