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:

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

{
  "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

Commands

list-tools (alias: ls)

List all available tools from the backend.

gsk list-tools
gsk ls

web_search (alias: search)

Search the web.

gsk search "latest AI news"
gsk search "latest AI news" -n 5
gsk search "最新のAIニュース" -l ja

crawler (alias: crawl)

Extract content from a web page or document.

gsk crawl "https://example.com/article"
gsk crawl "https://example.com/gallery" --images
gsk crawl "https://example.com/page" --no-text --images

summarize_large_document (alias: summarize)

Analyze a document and answer questions about it.

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.

gsk img-search "modern architecture"

understand_images (alias: analyze)

Analyze images with AI vision model.

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"

image_generation (alias: img)

Generate images using AI. Supports text-to-image and image-to-image.

# 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"

video_generation (alias: video)

Generate videos using AI.

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"

audio_generation (alias: audio)

Generate audio: TTS, music, or sound effects.

# 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"

upload

Upload a local file and get a file wrapper URL.

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:

{
  "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.

# 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"

analyze_media (alias: media-analyze)

Analyze various types of media content including images, audio, and video.

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"

audio_transcribe (alias: transcribe)

Transcribe audio files to text. Supports multiple audio formats.

gsk transcribe -i "https://example.com/audio.mp3"
gsk transcribe -i "https://example.com/meeting.wav" -m "whisper-large-v3"

get_service_url (alias: service-url)

Get a public HTTPS URL for a service running in the sandbox.

gsk service-url --port 3000
gsk service-url --port 8080 -n "My API" --health-check "/health"

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.

# 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"

create_task (alias: task)

Create and execute tasks using specialized AI agents. Supports multiple agent types for content generation.

# 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"

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.

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.

# 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:

{"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

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

# 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