zai-cli

<p align="center"> <img src="assets/zai-logo.svg" alt="Z.AI Logo" width="120" height="120"> </p>

<h1 align="center">ZAI CLI</h1>

<p align="center"> MCP-native command line interface for Z.AI capabilities: vision analysis, web search, web reader, and GitHub repo exploration. </p>

<p align="center"> <a href="https://www.npmjs.com/package/zai-tools"><img src="https://img.shields.io/npm/v/zai-tools.svg" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a> </p>

---

Features

• Vision - Analyze images, screenshots, diagrams, charts, videos using GLM-4.6V
• Search - Real-time web search with domain and recency filtering
• Reader - Fetch and parse web pages to markdown
• Repo - Search and read GitHub repository code via ZRead
• OCR - Extract text, tables, formulas from images and PDFs
• Text - LLM chat completions with streaming
• Image - AI image generation
• Tokenize - Token counting
• Tools - MCP tool discovery, schemas, and raw calls
• Code Mode - TypeScript tool chaining for agent automation
• Skills - Browse and run bundled skill definitions and multi-step pipelines

Quick Start

export Z_AI_API_KEY="your-api-key"

npx zai-tools --help
npx zai-tools vision analyze ./screenshot.png "What errors do you see?"
npx zai-tools search "React 19 new features" --count 5

Get your API key at: https://z.ai/manage-apikey/apikey-list

Installation

As an Agent Skill

OpenSkills (universal - works with any AI coding agent):

npx openskills install ameno-/zai-cli

Claude Code (native skill marketplace):

claude skill install ameno-/zai-tools --skill zai-cli

As a CLI Tool

npm i -g zai-tools
zai-tools --help

Or use directly with npx:

npx zai-tools --help

Usage

The CLI is self-documenting. Use --help at any level:

zai-tools --help              # All commands
zai-tools vision --help       # Vision commands
zai-tools search --help       # Search options
zai-tools repo --help         # GitHub repo commands

Examples

# Vision - analyze images
zai-tools vision analyze ./image.png "Describe this"
zai-tools vision ui-to-code ./design.png --output code
zai-tools vision extract-text ./screenshot.png --language python
zai-tools vision diagnose-error ./error.png

# Search - web search
zai-tools search "TypeScript best practices" --count 10
zai-tools search "security news" --recency oneDay

# Reader - fetch web content
zai-tools read https://docs.example.com/api
zai-tools read https://blog.example.com --format text

# Repo - GitHub exploration
zai-tools repo tree facebook/react
zai-tools repo search vercel/next.js "app router"
zai-tools repo read anthropics/anthropic-sdk-python README.md
zai-tools repo search openai/codex "config" --language en
zai-tools repo tree openai/codex --path codex-rs --depth 2

# Doctor - check setup
zai-tools doctor
zai-tools doctor --no-vision

# OCR - extract text from images/PDFs
zai-tools ocr ./document.png
zai-tools ocr ./report.pdf --mode table --pages 1-5

# Text - LLM chat
zai-tools text "What is TypeScript?"
zai-tools text "Summarize this" --file ./doc.txt --model glm-5.1

# Image - generate images
zai-tools image "A futuristic city skyline at sunset"
zai-tools image "Portrait of a cat" --model cogview-4 --save ./output.png

# Tokenize - count tokens
zai-tools tokenize "Hello, how are you?"

# Auth - check API key
zai-tools auth status
zai-tools auth check

# Config - view and set defaults
zai-tools config show
zai-tools config set vision_model glm-5v-turbo

# Skills - browse and run skill definitions
zai-tools skill list
zai-tools skill show prd-to-app

Output Format

Default output is data-only for token efficiency. Non-TTY output (piped) auto-switches to JSON. Use --output-format json or --json for structured responses:

{
  "success": true,
  "data": "...",
  "timestamp": 1234567890
}

Notes

• repo search defaults to English results. Use --language zh for Chinese.
• repo tree supports --path (directory scope) and --depth (expand subtrees).
• tools, tool, call, doctor accept --no-vision to speed startup when vision tools are not needed.
• read supports --with-images-summary, --no-gfm, and --keep-img-data-url for richer parsing control.
• Vision tool calls automatically retry transient 5xx/network errors (default: 2 retries). Configure with ZAI_MCP_VISION_RETRY_COUNT (or ZAI_MCP_RETRY_COUNT for all tools).
• Tool discovery can be cached to speed tools/tool/doctor (default: on, 24h TTL). Configure with ZAI_MCP_TOOL_CACHE, ZAI_MCP_TOOL_CACHE_TTL_MS, ZAI_MCP_CACHE_DIR.

Repository Layout

├── packages/zai-cli/    # npm package source
├── skills/zai-cli/      # Agent skill (SKILL.md)
└── .claude-plugin/      # Claude Code marketplace config

Development

cd packages/zai-cli
npm install
npm run build
npm test
node scripts/bench-tools.mjs

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE.

Links

• npm package
• GitHub Repository