Via zentao command-line tool to query and operate ZenTao data. The CLI automatically handles authentication and pagination, and supports workspace context and data filtering/sorting.
Prerequisites
Installation
npm install -g zentao-cli
# 或 bun install -g zentao-cli
# 或 pnpm install -g zentao-cli
# 或免安装运行：npx zentao-cli
If the user has not installed it, guide the user to perform a global installation. If the system has bun or pnpm, prefer using bun or pnpm for the global installation.
Authentication
The first time any zentao command is executed, it will automatically prompt for login. You can also log in explicitly:
zentao login -s https://zentao.example.com -u admin -p 123456
Environment variables (lower priority than command-line arguments):
| Variable | Description |
|---|---|
ZENTAO_URL |
ZenTao service address |
ZENTAO_ACCOUNT |
User account |
ZENTAO_PASSWORD |
Password |
ZENTAO_TOKEN |
Specify Token directly (with this variable, the password can be omitted) |
After a successful login, credentials are cached in ~/.config/zentao/zentao.json, so there is no need to log in repeatedly afterward.
Command format
Use the shorthand form (recommended):
| Operation | Command |
|---|---|
| List | zentao <module> |
| Details | zentao <module> <id> |
| Create | zentao <module> create --field=value |
| Update | zentao <module> update <id> --field=value |
| Delete | zentao <module> delete <id> |
| Action | zentao <module> <action> <id> |
| Help | zentao <module> help |
Also supports --data='JSON' passing in JSON data.
Module and operation quick reference
| Module name | Chinese | Supported operations |
|---|---|---|
| program | Program | CRUD |
| product | Product | CRUD |
| project | Project | CRUD |
| execution | Execution/Iteration | CRUD |
| story | Story | CRUD + activate / change / close |
| epic | Business requirement | CRUD + activate / change / close |
| requirement | User requirement | CRUD + activate / change / close |
| bug | Bug | CRUD + activate / close / resolve |
| task | Task | CRUD + activate / close / finish / start |
| testcase | Test case | CRUD |
| testtask | Test build | CUD (list queried by product/project/execution) |
| productplan | Product plan | CUD (list queried by product) |
| build | Build | CUD (list queried by project/execution) |
| release | Release | CUD (list queried by product) |
| feedback | Feedback | CRUD + activate / close |
| ticket | Ticket | CRUD + activate / close |
| system | Application | CU (list queried by product) |
| user | User | CRUD |
| file | Attachment | Edit name + delete |
CRUD = list + details + create + update + delete; CUD = no standalone list interface, the owning scope must be specified
List scope parameters
The lists of some modules require specifying the owning scope:
zentao story --product=1 # 产品 #1 的需求
zentao bug --product=1 # 产品 #1 的 Bug
zentao task --execution=1 # 执行 #1 的任务
zentao execution --project=5 # 项目 #5 的执行
zentao build --project=5 # 项目 #5 的版本
zentao testtask --product=1 # 产品 #1 的测试单
zentao release --product=1 # 产品 #1 的发布
zentao productplan --product=1 # 产品 #1 的计划
zentao feedback --product=1 # 产品 #1 的反馈
zentao ticket --product=1 # 产品 #1 的工单
After setting a workspace, these parameters can be omitted (see the workspace section below).
AI usage strategy
Output format
- Display to the user: without adding the
--formatparameter, outputs a Markdown table (list) or list (single object) by default - Needs programmatic processing: add
--format=json, returns structured JSON
Interactive confirmation
In AI scenarios, when executing a delete operation, add --yes Skip confirmation prompt:
zentao bug delete 1 --yes
When you don't know the ID
First query the list to get the ID, then operate on the specific object:
zentao product --pick=id,name # 查看产品列表
zentao bug --product=1 --pick=id,title # 查看 Bug 列表
zentao bug 42 # 查看具体 Bug
Confirm before write operations
Before performing write operations such as create, update, and delete, confirm the operation details with the user. This can be skipped when the user explicitly requests no confirmation.
Data processing
Extract fields
zentao product --pick=id,name,status
Filter
zentao bug --product=1 --filter='status:active'
zentao bug --product=1 --filter='severity<=2,pri<=2' # AND
zentao bug --product=1 --filter='status:active' --filter='status:resolved' # OR
Supported operators:: equals,!= not equals,> < >= <=、~ contains,!~ not contains.
Fuzzy search
zentao bug --product=1 --search=登录 --search-fields=title,steps
Sort
zentao bug --product=1 --sort=pri_asc,severity_asc
Pagination
zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --all # 获取全部
zentao bug --product=1 --limit=10 # 只取前 10 条
Common operation examples
View in-progress projects and executions
zentao project --filter='status:doing' --pick=id,name,status
zentao execution --project=5 --pick=id,name,status
Create a requirement and associate a plan
zentao story create --product=1 --title="需求标题" --assignedTo=admin --pri=3
zentao story update 11 --title="需求标题" --plan=1
Create and resolve a bug
zentao bug create --product=1 --title="Bug标题" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42
Create, start, and complete a task
zentao task create --execution=1 --name="任务名" --type=devel --assignedTo=admin --estimate=4
zentao task start 100
zentao task finish 100 --consumed=4
View help
zentao bug help # 查看 Bug 模块的参数和操作
zentao story update help # 查看需求更新操作的参数和操作
zentao help # 查看所有命令
Intent recognition
| User intent | CLI command |
|---|---|
| All products/projects/programs | zentao product / zentao project / zentao program |
| In-progress projects | zentao project --filter='status:doing' |
| Bugs of a product | zentao bug --product=<id> |
| Tasks of an execution | zentao task --execution=<id> |
| Create/add bug | zentao bug create ... |
| Resolve bug | zentao bug resolve <id> |
| Close bug | zentao bug close <id> |
| Activate bug | zentao bug activate <id> |
| Create requirement | zentao story create ... |
| Change/close/activate requirement | zentao story change/close/activate <id> |
| Business requirement | zentao epic ...(same as story) |
| User requirement | zentao requirement ...(same as story) |
| Create/start/complete/close task | zentao task create/start/finish/close ... |
| Test case | zentao testcase ... |
| Test task | zentao testtask ... |
| Product plan | zentao productplan ... |
| Version/Build | zentao build ... |
| Release | zentao release ... |
| Feedback | zentao feedback ... |
| Ticket | zentao ticket ... |
| User list | zentao user |
| Current user information | zentao profile |
Error handling
| Error code | Meaning | Handling |
|---|---|---|
| E1001 | Not logged in/missing credentials | Execute zentao login |
| E1004 | Token invalid | Execute zentao login to log in again |
| E2001 | Module does not exist | Execute zentao help to view available modules |
| E2002 | Object does not exist | Check whether the ID is correct |
| E2003 | Missing required parameters | Execute zentao <module> help to view parameters |
| E2006 | No permission | Prompt the user to check permissions |
| E5001 | Request timed out | Check the network or ZenTao service status |
Notes
- When unsure about module parameters, first execute
zentao <module> helpto view help browseTypeCommon values:all(all),doing(in progress),closed(closed)- Silent mode:
--silentonly outputs error information - Multi-account switching:
zentao profileview and switch accounts