vision-query

CLI tool for querying images via AI vision models. Supports Google Gemini, OpenAI-compatible providers (GLM, etc.), automatic proxy discovery, rate limiting, and preset modes.

Install

npm install -g @lenml/vision-query
# or
git clone <repo> && cd vision-query && pnpm install && pnpm run build

Quick Start

# create config
vision-query config set models.0.name gemini-3.1-flash-lite
vision-query config set models.0.provider google
vision-query config set models.0.api_key "your-api-key"

# analyze an image
vision-query photo.jpg -q "what is in this image?"

Configuration

See vision-query.config.example.json for a full reference.

Config file discovery (first found wins):

• ./vision-query.config.json
• ~/.vision-query.config.json
• $VISION_QUERY_CONFIG_PATH env var

Proxy

Supports HTTP CONNECT and SOCKS5 proxies. Auto-discovery probes 127.0.0.1:10808, :7890, :7891 and respects https_proxy/http_proxy env vars.

{ "proxy": "socks5://127.0.0.1:10808" }

Providers

Google — uses gemini-2.5-flash-lite by default. Set rate_limit fields per the API tier.

OpenAI-compatible — set base_url for any OpenAI-like API (GLM, vLLM, Ollama, etc.). Extra body fields like thinking go in options.

Rate Limiting

Configure rpm, rpd, tpm per model. Requests are tracked via ~/.vision-query.events.jsonl across CLI invocations.

Caching

Results are cached by image content + query + mode (SHA-256). Cache file: ~/.vision-query.cache.json, 7-day TTL. Use --no-cache to skip.

CLI Reference

vision-query [options] <image paths...>
vision-query config [--global] <get|set|list|path> [path] [value]
vision-query modes

Options

Flag	Description
-q, --query <text>	Query text for the image
--mode <name>	Mode preset (lite / default / high / high_json)
--model <name>	Use a specific model only, no fallback
--no-compress	Skip image compression
--no-transcode	Skip image transcoding
--no-cache	Ignore cached results

Modes

Mode	Description
lite	Brief one-sentence response
default	Detailed Chinese description
high	Comprehensive analysis (composition, subject, colors, context)
high_json	JSON output

Custom modes can be added in the config file under modes.

Config Subcommand

# list current config
vision-query config list
# list global config
vision-query config --global list
# get a specific key
vision-query config get models.0.name
# set a value
vision-query config set proxy socks5://127.0.0.1:10808

Architecture

src/
  main.ts          # entry point, CLI parsing via commander
  cli.ts           # commander program definition (main + subcommands)
  config.ts        # config loading, mode resolution
  config_cmd.ts    # config get/set/list subcommand logic
  fetch.ts         # proxy-aware fetch, auto-discovery, API request helper
  image.ts         # image processing (resize, transcode)
  rate_limiter.ts  # sliding-window rate limiter with JSONL persistence
  response.ts      # output formatting + JSON extraction
  providers/
    registry.ts    # provider factory + fallback chain
    openai.ts      # OpenAI-compatible provider
    google.ts      # Google Gemini provider