@genspark/cli 1.0.1

package/README.md

@@ -0,0 +1,474 @@
+# Genspark Tool CLI (gsk)
+
+Command-line interface for Genspark AI services. Provides web search, content crawling, image/video/audio generation, file management, and service URL creation.
+
+Designed for integration with AI agents (e.g., OpenCode) — results go to stdout as JSON, progress/debug info goes to stderr.
+
+## Installation
+
+Pre-installed in the Genspark Desktop sandbox container. The binary is available as `gsk` (or `genspark`).
+
+For manual setup:
+
+```bash
+cd resources/genspark-tool-cli
+npm install
+npm run build
+# Binary: dist/index.js
+```
+
+Requires Node.js >= 18.
+
+## Configuration
+
+Config is loaded from three sources (highest priority first):
+
+1. **CLI options** — `--api-key`, `--base-url`, etc.
+2. **Environment variables** — `GSK_API_KEY`, `GSK_BASE_URL`, `GSK_PROJECT_ID`
+3. **Config file** — `~/.genspark-tool-cli/config.json`
+
+```json
+{
+  "api_key": "gsk_...",
+  "base_url": "http://host.containers.internal:3000",
+  "project_id": "project_abc123",
+  "debug": false,
+  "timeout": 300000
+}
+```
+
+In the Genspark Desktop container, this config file is auto-generated on container start.
+
+## Global Options
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `--api-key <key>` | `GSK_API_KEY` | — | API key (required) |
+| `--base-url <url>` | `GSK_BASE_URL` | `http://localhost:8582` | Backend API base URL |
+| `--project-id <id>` | `GSK_PROJECT_ID` | — | Project ID for access control |
+| `--debug` | — | `false` | Enable debug output |
+| `--timeout <ms>` | — | `300000` (5 min) | Request timeout |
+| `--output <format>` | — | `json` | Output format: `json` or `text` |
+
+## Commands
+
+### list-tools (alias: `ls`)
+
+List all available tools from the backend.
+
+```bash
+gsk list-tools
+gsk ls
+```
+
+### web_search (alias: `search`)
+
+Search the web.
+
+```bash
+gsk search "latest AI news"
+gsk search "latest AI news" -n 5
+gsk search "最新のAIニュース" -l ja
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-n, --num <count>` | `10` | Number of results (1-50) |
+| `-l, --language <code>` | — | Language code (e.g., `en`, `zh`, `ja`) |
+
+### crawler (alias: `crawl`)
+
+Extract content from a web page or document.
+
+```bash
+gsk crawl "https://example.com/article"
+gsk crawl "https://example.com/gallery" --images
+gsk crawl "https://example.com/page" --no-text --images
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-text` | extract text | Skip text content extraction |
+| `-i, --images` | `false` | Include image URLs in response |
+
+### summarize_large_document (alias: `summarize`)
+
+Analyze a document and answer questions about it.
+
+```bash
+gsk summarize "https://example.com/report.pdf" "What are the key findings?"
+```
+
+Arguments: `<url>` `<question>`
+
+### image_search (alias: `img-search`)
+
+Search for images on the web.
+
+```bash
+gsk img-search "modern architecture"
+```
+
+### understand_images (alias: `analyze`)
+
+Analyze images with AI vision model.
+
+```bash
+gsk analyze "Describe this image" -i "https://example.com/image.jpg"
+gsk analyze "Extract all text" -i "https://img1.jpg" "https://img2.jpg"
+gsk analyze "What's in this photo?" -i "https://example.com/photo.jpg"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i, --image_urls <url...>` | — | Image URL(s) to analyze (**required**, can specify multiple) |
+| `-r, --instruction <text>` | — | Custom analysis instruction |
+
+### image_generation (alias: `img`)
+
+Generate images using AI. Supports text-to-image and image-to-image.
+
+```bash
+# Text-to-image
+gsk img "A beautiful sunset over mountains" -r "16:9" -o ./sunset.png
+gsk img "Modern office at night" -s "4k" -r "1:1"
+
+# Image-to-image (reference-based)
+gsk upload "./reference.png"
+# Output: { "data": { "file_wrapper_url": "https://www.genspark.ai/api/files/s/abc123", ... } }
+gsk img "A portrait in similar style" -i "https://www.genspark.ai/api/files/s/abc123"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-r, --aspect_ratio <ratio>` | `1:1` | Aspect ratio (`1:1`, `16:9`, `9:16`) |
+| `-s, --image_size <size>` | `auto` | Image size: `auto`, `2k`, `4k` |
+| `-m, --model <name>` | — | Model to use (optional) |
+| `-i, --image_urls <url...>` | — | Reference image URL(s) for image-to-image |
+| `-o, --output-file <path>` | — | Download the generated file to a local path |
+
+### video_generation (alias: `video`)
+
+Generate videos using AI.
+
+```bash
+gsk video "A cat playing with yarn" -m "kling/v1.6/standard" -d 5 -o ./cat.mp4
+gsk video "Sunrise over a beach" -m "minimax/hailuo-02/standard" -r "16:9" -d 8
+
+# Image-to-video
+gsk upload "./photo.jpg"
+gsk video "Camera pan around the subject" -m "kling/v1.6/standard" -i "https://www.genspark.ai/api/files/s/abc123"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-m, --model <name>` | — | Model (**required**). e.g., `kling/v1.6/standard`, `minimax/hailuo-02/standard` |
+| `-r, --aspect_ratio <ratio>` | `16:9` | Aspect ratio |
+| `-d, --duration <sec>` | `5` | Duration in seconds (2-15) |
+| `-i, --image_urls <url...>` | — | Reference image URL(s) |
+| `-a, --audio_url <url>` | — | Audio URL for soundtrack |
+| `-o, --output-file <path>` | — | Download the generated file to a local path |
+
+### audio_generation (alias: `audio`)
+
+Generate audio: TTS, music, or sound effects.
+
+```bash
+# Text-to-speech
+gsk audio "Hello, welcome to Genspark!" -m "google/gemini-2.5-pro-preview-tts" -r "professional female voice"
+gsk audio "Hello, welcome to Genspark!" -m "google/gemini-2.5-pro-preview-tts" -o ./hello.mp3
+
+# Music with lyrics
+gsk audio "A pop song" -m "fal-ai/minimax/speech-2.6-hd" -l "Verse 1: ..." -d 120
+
+# Sound effect
+gsk audio "Door creaking slowly open" -m "sfx-model"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-m, --model <name>` | — | Model (**required**). e.g., `elevenlabs/v3-tts`, `fal-ai/minimax/speech-2.6-hd` |
+| `-d, --duration <sec>` | `0` (auto) | Duration in seconds |
+| `-r, --requirements <text>` | — | Voice requirements for TTS |
+| `-l, --lyrics <text>` | — | Lyrics for song generation |
+| `-o, --output-file <path>` | — | Download the generated file to a local path |
+
+### upload
+
+Upload a local file and get a file wrapper URL.
+
+```bash
+gsk upload "./image.png"
+gsk upload "/home/user/workspace/document.pdf"
+```
+
+**Supported file types** (auto-detected from extension):
+- Images: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+- Documents: `.pdf`, `.txt`, `.md`, `.html`, `.xml`, `.csv`
+- Code: `.js`, `.ts`, `.css`
+- Media: `.mp3`, `.mp4`, `.wav`, `.webm`
+- Archives: `.zip`
+- Data: `.json`
+- Other: `application/octet-stream`
+
+**Process:**
+1. Requests a pre-signed upload URL from the backend
+2. Uploads file to Azure Blob Storage via PUT
+3. Returns a file wrapper URL for use in other commands
+
+**Output:**
+```json
+{
+  "status": "ok",
+  "message": "File uploaded successfully",
+  "data": {
+    "file_wrapper_url": "https://www.genspark.ai/api/files/s/abc123",
+    "file_name": "image.png",
+    "content_type": "image/png",
+    "size_bytes": 123456
+  }
+}
+```
+
+### download
+
+Download a file from a file wrapper URL.
+
+```bash
+# Get download URL only
+gsk download "https://www.genspark.ai/api/files/s/abc123"
+
+# Download and save to local file
+gsk download "https://www.genspark.ai/api/files/s/abc123" -s "./downloaded.png"
+```
+
+| Option | Description |
+|--------|-------------|
+| `-s, --save <path>` | Download and save to local file path |
+
+### analyze_media (alias: `media-analyze`)
+
+Analyze various types of media content including images, audio, and video.
+
+```bash
+gsk media-analyze -i "https://example.com/image.jpg" -r "Describe the content"
+gsk media-analyze -i "https://example.com/video.mp4" -r "Summarize the video"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i, --media_urls <urls>` | — | Media URL(s) to analyze (**required**) |
+| `-r, --requirements <text>` | — | Analysis instructions |
+
+### audio_transcribe (alias: `transcribe`)
+
+Transcribe audio files to text. Supports multiple audio formats.
+
+```bash
+gsk transcribe -i "https://example.com/audio.mp3"
+gsk transcribe -i "https://example.com/meeting.wav" -m "whisper-large-v3"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i, --audio_urls <url...>` | — | Audio URL(s) to transcribe (**required**) |
+| `-m, --model <name>` | — | Transcription model to use |
+
+### get_service_url (alias: `service-url`)
+
+Get a public HTTPS URL for a service running in the sandbox.
+
+```bash
+gsk service-url --port 3000
+gsk service-url --port 8080 -n "My API" --health-check "/health"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port <number>` | — | Port where service is running (**required**) |
+| `-s, --sandbox <id>` | — | Sandbox ID (optional, auto-detected from project_id) |
+| `-n, --name <name>` | — | Service name for logging |
+| `--health-check <path>` | — | Health check endpoint path |
+
+### aidrive (alias: `drive`)
+
+AI-Drive file storage and management. List, create, delete, move files and directories. Download videos, audio, and files from URLs directly to AI-Drive.
+
+```bash
+# List files in root directory
+gsk drive ls
+gsk drive ls -p "/documents" -f file
+
+# Create directory
+gsk drive mkdir -p "/my-folder"
+
+# Move file
+gsk drive move -p "/old-path/file.txt" --target_path "/new-path/file.txt"
+
+# Download video/audio/file to AI-Drive
+gsk drive download_video --video_url "https://example.com/video.mp4" --target_folder "/videos"
+gsk drive download_file --file_url "https://example.com/doc.pdf" --target_folder "/docs"
+
+# Upload content to AI-Drive
+gsk drive upload --file_content "Hello World" --upload_path "/notes/hello.txt"
+
+# Get readable URL for a file
+gsk drive get_readable_url -p "/documents/report.pdf"
+
+# Compress/decompress
+gsk drive compress -p "/my-folder"
+gsk drive decompress -p "/archive.zip"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --path <path>` | — | File or directory path in AI-Drive |
+| `-f, --filter_type <type>` | `all` | Filter: `all`, `file`, `directory` |
+| `--file_type <type>` | `all` | File type filter: `all`, `audio`, `video`, `image` |
+| `--target_path <path>` | — | Target path for move operations |
+| `--target_folder <path>` | — | Target folder for downloads |
+| `--video_url <url>` | — | Video URL for download_video action |
+| `--audio_url <url>` | — | Audio URL for download_audio action |
+| `--file_url <url>` | — | File URL for download_file action |
+| `--file_name <name>` | — | Custom file name for downloads |
+| `--file_content <text>` | — | Content to upload |
+| `--upload_path <path>` | — | Destination path for upload |
+
+### create_task (alias: `task`)
+
+Create and execute tasks using specialized AI agents. Supports multiple agent types for content generation.
+
+```bash
+# Create a podcast
+gsk task podcasts --task_name "AI Trends" --query "Create a podcast about AI trends in 2025" --instructions "Focus on practical applications"
+
+# Create a document
+gsk task docs --task_name "Quantum Report" --query "Write a technical report on quantum computing" --instructions "Include recent breakthroughs"
+
+# Create slides
+gsk task slides --task_name "Q4 Results" --query "Create a presentation about our Q4 results" --instructions "Use charts and data visualizations"
+
+# Deep research
+gsk task deep_research --task_name "Fusion Energy" --query "Research the latest advances in fusion energy" --instructions "Cover both public and private sector"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--task_name <name>` | — | Name for the task/project (**required**) |
+| `--query <text>` | — | Query describing what to create (**required**) |
+| `--instructions <text>` | — | Detailed instructions for the agent (**required**) |
+
+**Supported task types:** `super_agent`, `podcasts`, `docs`, `slides`, `deep_research`, `website`, `video_generation`, `audio_generation`
+
+### stock_price (alias: `stock`)
+
+Retrieve current stock price information, company profile, financial metrics, and ratios.
+
+```bash
+gsk stock AAPL
+gsk stock MSFT
+gsk stock GOOGL
+```
+
+Returns stock data including 5-year historical prices, daily prices, company profile, financial metrics, and ratios.
+
+## File Wrapper URLs
+
+URLs in format `https://www.genspark.ai/api/files/s/...` are file wrapper URLs that require authentication.
+
+- **Cannot** be accessed directly with `wget`, `curl`, or browsers (401/403)
+- **Download**: `gsk download <url> -s <local_path>`
+- **Upload**: `gsk upload <local_path>` to get a file wrapper URL
+
+**In most cases you don't need to handle these manually** — `gsk analyze`, `gsk img`, `gsk video`, and `gsk summarize` accept local file paths directly via `-i` and auto-upload them. Use `-o` to save generated results locally.
+
+```bash
+# Direct local file workflow (preferred):
+gsk img "Enhance this" -i ./photo.png -o ./result.png
+
+# Manual upload/download (rarely needed):
+gsk upload "./photo.png"
+gsk download "https://www.genspark.ai/api/files/s/abc123" -s "./result.png"
+```
+
+## API Protocol
+
+The CLI communicates with the backend via streaming NDJSON (newline-delimited JSON) over HTTP POST to `/api/tool_cli/<tool_name>`.
+
+### Request Headers
+
+```
+Content-Type: application/json
+X-Api-Key: <api_key>
+X-Project-ID: <project_id>    (if configured)
+X-Debug: true                  (if --debug enabled)
+```
+
+### Response Format
+
+Server streams multiple JSON lines:
+
+```jsonl
+{"version": 1, "debug": true, "message": "Starting search..."}
+{"version": 1, "debug": true, "message": "Found 5 results", "elapsed_seconds": 1.2}
+{"version": 1, "status": "ok", "message": "Search complete", "data": {...}}
+```
+
+- **Debug lines** (`"debug": true`): Progress messages, only shown to stderr when `--debug` is enabled
+- **Final result**: Has `"status": "ok"` or `"status": "error"` with `"data"` field
+- **Protocol versioning**: Messages with `version > 1` are silently ignored (forward compatibility)
+
+## Output Conventions
+
+| Stream | Content | Consumer |
+|--------|---------|----------|
+| **stdout** | JSON result | AI agent (parsed into context) |
+| **stderr** | `[INFO]`, `[DEBUG]`, `[WARN]`, `[ERROR]` messages | Human / logs |
+
+This separation allows AI agents to parse clean JSON from stdout while humans can follow progress on stderr.
+
+## Project Structure
+
+```
+genspark-tool-cli/
+├── src/
+│   ├── index.ts      # CLI entry point, command definitions (Commander.js)
+│   ├── client.ts      # ApiClient class, HTTP requests, NDJSON parsing
+│   ├── config.ts      # Config file loader (~/.genspark-tool-cli/config.json)
+│   ├── types.ts       # TypeScript interfaces for all requests/responses
+│   └── logger.ts      # Logger (stdout for results, stderr for debug/info)
+├── dist/              # Compiled JavaScript (built output)
+├── package.json
+└── tsconfig.json
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development (ts-node)
+npm run dev -- search "test query"
+
+# Run built version
+npm start -- search "test query"
+
+# Lint
+npm run lint
+
+# Clean build output
+npm run clean
+```
+
+### Adding a New Command
+
+1. Add request/response types in `src/types.ts`
+2. Add API method in `src/client.ts`
+3. Add command definition in `src/index.ts` (command name MUST match backend tool name)
+4. Rebuild: `npm run build`
+5. Rebuild sandbox image: `npm run build-sandbox` (from GensparkDesktop root)
+6. Update `AGENTS.md.template` with the new command documentation

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+/**
+ * API Client for Genspark Tool CLI
+ */
+import type { GlobalOptions, ApiResponse, ToolListResponse, FileUploadUrlRequest, FileUploadUrlResponse, FileDownloadRequest, FileDownloadResponse } from "./types.js";
+/**
+ * Make an unauthenticated request to the backend.
+ * Used for device-flow auth endpoints that don't require an API key.
+ */
+export declare function unauthenticatedRequest<T>(baseUrl: string, endpoint: string, method?: "GET" | "POST", body?: unknown): Promise<T>;
+export declare class ApiClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private debugMode;
+    private projectId?;
+    constructor(options: GlobalOptions);
+    private request;
+    /**
+     * List available tools with full schemas
+     */
+    listTools(): Promise<ToolListResponse>;
+    /**
+     * Execute any tool by name with arguments
+     */
+    executeTool(toolName: string, args: Record<string, unknown>): Promise<ApiResponse>;
+    /**
+     * Get a pre-signed URL for uploading a file
+     */
+    getUploadUrl(params: FileUploadUrlRequest): Promise<ApiResponse<FileUploadUrlResponse>>;
+    /**
+     * Get a downloadable URL for a file wrapper URL
+     */
+    getDownloadUrl(params: FileDownloadRequest): Promise<ApiResponse<FileDownloadResponse>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,KAAK,GAAG,MAAc,EAC9B,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,OAAO,EAAE,aAAa;YAQpB,OAAO;IA+JrB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAS5C;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC;IAIvB;;OAEG;IACG,YAAY,CAChB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAQ9C;;OAEG;IACG,cAAc,CAClB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,WAAW,CAAC,oBAAoB,CAAC,CAAC;CAG9C"}