Content
# Tool List
Zentao CLI, a command-line tool for Zentao, supports accessing and operating Zentao data in your favorite terminal, friendly to AI Agents.
## Main Features
* ✅ Based on the latest Zentao RESTful API 2.0, supports v1 API automatic downgrade
* ✅ Compatible with old version Zentao server, automatically detects and switches to v1 API
* ✅ Convenient to use, can be run immediately through `npx zentao-cli`
* ✅ Secure user authentication management, supports multi-user switching, Token encryption storage (PBKDF2)
* ✅ Three authentication methods: password / Token / Cookie
* ✅ Supports data extraction, filtering, sorting, and automatically converts HTML to Markdown
* ✅ Friendly to AI Agents, helps information is complete, supports output Markdown
* ✅ Supports using as AI skills, supports installing skills to AI Agents through `zentao add-skill`
* ✅ Supports MCP service, use `npx zentao-cli mcp` to start MCP service
* ✅ Developed with modern bun and TypeScript, has type safety
* ✅ Provides complete test coverage, ensures code quality
* ✅ Supports workspace management, remembers user's last accessed product, project, and execution information, automatically infers current context
* ✅ Supports debug mode, use `--debug` or `-D` to view detailed request logs
* ✅ Supports batch operations, use comma or range expressions (e.g., `bug 1-5`), with progress bar and error aggregation
* ✅ Supports local caching, reduces repeated API calls (default 5 minutes TTL)
* ✅ Supports one-click installation script, prioritizes downloading pre-compiled binary from GitHub Releases
* ✅ Supports Docker running, provides docker-compose.yml
* ✅ Supports table output coloring, key state automatically highlighted
* ✅ Multi-level log function, supports error/warn/info/debug four levels
* ✅ Internationalization support, supports Chinese and English switching
* ✅ Geek version TUI interface, interactive operation experience
* ✅ Output redirection, supports `--output` and `--append`
* ✅ Command history, saved to `~/.zentao-history`
* ✅ Code syntax highlighting, supports JS/TS/Python/SQL/Bash and other languages
* ✅ CSV / JSON Lines export, supports `--format csv` and `--format jsonl`
* ✅ My to-do list, supports `zentao my tasks/bugs/stories` one-click query assigned work items
## Quick Start
### Compatibility Description
zentao-cli supports two Zentao API versions:
- **API v2** (Recommended): Modern RESTful API, suitable for Zentao 17.x and above
- **API v1** (Compatibility mode): Traditional API, suitable for old version Zentao server
zentao-cli will **automatically detect** the API version supported by the server:
- If v2 API returns empty response, automatically switches to v1 API
- No manual configuration required, completely transparent
### Installation and Login
```bash
# Globally install zentao-cli tool
npm install -g zentao-cli
# Other installation and running methods
# bun install -g zentao-cli # ← Install using bun
# npx zentao-cli # ← Run through npx without installation
# pnpm dlx zentao-cli # ← Run through pnpm without installation
# First use needs to log in
zentao login -s https://zentao.example.com -u admin -p 123456
# Directly execute to get available command help
zentao
# View Zentao products
zentao product
# View specified ID product
zentao product 1
# Update Zentao product #1
zentao product update --id=1 --name=Product1
# More functions can be viewed through help
zentao help
# View Zentao product help
zentao product help
# Install zentao-cli skill
zentao add-skill
# View assigned to-do tasks
zentao my tasks
# View assigned bugs
zentao my bugs
# Export product list to CSV
zentao product --format csv --output products.csv
```
## Core Commands
zentao-cli command format is simple and intuitive: `zentao <module name> [operation] [parameters]`. The following quickly get started through common scenarios.
### View and Manage Products
```bash
# View product list
zentao product
# View product details
zentao product 1
# Create product
zentao product create --name=NewProduct
# Update product name
zentao product update 1 --name=NewProductName
# Delete product
zentao product delete 1
```
### View and Process Bugs
```bash
# View bug list
zentao bug
# View bug details
zentao bug 329
# Resolve bug (execute operation)
zentao bug resolve 329 --resolution=fixed
```
### Requirements and Tasks
```bash
# View requirement list
zentao story
# Create task
zentao task create --name=ImplementLoginFunction --execution=10
```
### Data Filtering and Search
```bash
# Show only specified fields
zentao product --pick=id,name
# Filter by condition
zentao bug --filter 'status:active'
# Fuzzy search
zentao story --search=login --search-fields=title
# Sort by field
zentao bug --sort=id_desc
# JSON format output (suitable for program processing)
zentao product --format=json
# CSV export
zentao product --format=csv --output products.csv
# JSON Lines export (one object per line)
zentao bug --format=jsonl --output bugs.jsonl
# Debug mode, view detailed request logs
zentao product --debug
zentao product -D
```
### Interactive TUI Interface
```bash
# Start interactive interface
zentao tui
# Directly enter specified module
zentao tui -m bug
zentao tui --module product
```
### View Help
```bash
# View all commands
zentao help
# View specified module help (available operations and parameters)
zentao bug help
```
More functions (environment variables, account switching, batch operations, pipeline input, pagination control, etc.) please refer to [CLI Core Function Details](docs/cli-usage.md).
## Usage in AI Agents
### Using Through Zentao CLI Skill
Supports accessing and operating Zentao data through `zentao-cli` skill. Installing skills can be done through `zentao add-skill` one-click installation to AI Agent, currently supports Claude Code, Cursor, Cherry Studio, Codex, OpenCode, VS Code and other AI Agents.
Detailed usage can refer to: [Using Zentao in Agents](docs/use-zentao-in-agents.md), the following is a brief introduction.
```bash
# Install zentao-cli skill
$ zentao add-skill
Please select the AI Agent to install:
1) Claude Code
2) Cursor
3) Cherry Studio
4) Codex
5) OpenCode
6) VS Code
7) Antigravity
8) Gemini
9) All install
Please enter the number (1-9):9
# Install skill to Claude Code
$ zentao add-skill claude-code
```
If zentao-cli is not installed, you can use the following command to install, log in, and configure the skill:
```bash
# One-click install, log in, and configure skill
$ pnpm install -g zentao-cli && zentao login && zentao add-skill all
```
After installing the skill, you can use the Zentao CLI skill in the corresponding Agent tool.
```txt
What products are there in Zentao?
What are the development requirements of product xxx?
What are the risks of requirement xxx?
```
### Using Through MCP Service
Zentao CLI supports one-click configuration of MCP service, just execute `zentao add-mcp` command, then input Zentao URL, username, and password.
```bash
# One-click configure MCP service
$ zentao add-mcp
Please enter Zentao URL: https://zentao.example.com
Please enter username: admin
Please enter password: 123456
Please select the AI Agent to configure:
1) Cursor
2) Claude Desktop
3) Claude Code
4) Windsurf
5) Cline
6) Trae
7) VS Code
8) Cherry Studio
9) OpenCode
10) Codex
11) All configure
Please enter the number (1-11): 7
```
If zentao-cli is not installed, you can use the following command to install, log in, and configure MCP service:
```bash
# One-click install, log in, and configure MCP service
$ pnpm install -g zentao-cli && zentao login && zentao add-mcp
```
Unified support through `npx -y zentao-cli mcp` manually start MCP service, then access and operate Zentao data through MCP client. Currently, major Agents tools do not need to install zentao-cli in advance, just need to add the following configuration to MCP service configuration:
```json
{
"mcpServers": {
"zentao-cli": {
"command": "npx",
"args": ["-y", "zentao-cli", "mcp"],
"env": {
"ZENTAO_URL": "https://zentao.example.com",
"ZENTAO_ACCOUNT": "admin",
"ZENTAO_PASSWORD": "123456"
}
}
}
}
```
## Documents
| Document | Description |
| --- | --- |
| [CLI Core Function Details](docs/cli-usage.md) | User verification, data access and operation, data processing, output format, configuration management, etc. |
| [Using Zentao in Agents](docs/use-zentao-in-agents.md) | Using Zentao through skills or MCP in AI Agents |
| [Development Guide](docs/development.md) | Technology stack, project structure, testing |
| [Technical Scheme and Implementation Details](docs/implementation.md) | Internal interface call rules, verification mechanism, and persistent configuration |
| [Common Error Troubleshooting and Reference Manual](docs/errors.md) | Error code (Exxxx) query |
| [Follow-up Plan](docs/roadmap.md) | Functions to be implemented and improvement plans |
| [Change Log](CHANGES.md) | Change content of each version |
