Back to Details

zentao-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

禅道 CLI

ZenTao CLI

通过 
zentao
命令行工具查询和操作禅道数据。CLI 自动处理认证、分页，支持工作区上下文和数据过滤/排序。
Query and operate ZenTao data via the 
zentao
command-line tool. The CLI automatically handles authentication and pagination, and supports workspace context, data filtering/sorting.

前置准备

Prerequisites

安装

Installation

bash
npm install -g zentao-cli
bash
npm install -g zentao-cli

或 bun install -g zentao-cli

or bun install -g zentao-cli

或 pnpm install -g zentao-cli

or pnpm install -g zentao-cli

或免安装运行：npx zentao-cli

or run without installation: npx zentao-cli


如果用户没有安装，引导用户进行全局安装使用，如果系统存在 bun 或 pnpm 则优先使用 bun 或 pnpm 进行全局安装。

If the user hasn't installed it, guide them to install it globally. If bun or pnpm is available on the system, prioritize using bun or pnpm for global installation.

认证

Authentication

首次执行任意 
zentao
命令会自动提示登录。也可显式登录：
bash
zentao login -s https://zentao.example.com -u admin -p 123456
环境变量（优先级低于命令行参数）：
变量说明
ZENTAO_URL
禅道服务地址
ZENTAO_ACCOUNT
用户账号
ZENTAO_PASSWORD
密码
ZENTAO_TOKEN
直接指定 Token（有此变量可省略密码）
登录成功后凭证缓存在 
~/.config/zentao/zentao.json
，后续无需重复登录。
The first time you execute any 
zentao
command, you will be prompted to log in automatically. You can also log in explicitly:
bash
zentao login -s https://zentao.example.com -u admin -p 123456
Environment variables (lower priority than command-line parameters):
VariableDescription
ZENTAO_URL
ZenTao service address
ZENTAO_ACCOUNT
User account
ZENTAO_PASSWORD
Password
ZENTAO_TOKEN
Specify Token directly (password can be omitted if this variable exists)
After successful login, credentials are cached in 
~/.config/zentao/zentao.json
, so you don't need to log in repeatedly later.

命令格式

Command Format

使用简写方式（推荐）：
操作命令
列表
zentao <module>
详情
zentao <module> <id>
创建
zentao <module> create --field=value
更新
zentao <module> update <id> --field=value
删除
zentao <module> delete <id>
动作
zentao <module> <action> <id>
帮助
zentao <module> help
也支持 
--data='JSON'
传入 JSON 数据。
Use the shorthand format (recommended):
OperationCommand
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
You can also pass JSON data using 
--data='JSON'
.

模块与操作速查

Module & Operation Quick Reference

模块名中文支持的操作
program项目集CRUD
product产品CRUD
project项目CRUD
execution执行/迭代CRUD
story需求CRUD + activate / change / close
epic业务需求CRUD + activate / change / close
requirement用户需求CRUD + activate / change / close
bugBugCRUD + activate / close / resolve
task任务CRUD + activate / close / finish / start
testcase测试用例CRUD
testtask测试单CUD（按产品/项目/执行查列表）
productplan产品计划CUD（按产品查列表）
build版本CUD（按项目/执行查列表）
release发布CUD（按产品查列表）
feedback反馈CRUD + activate / close
ticket工单CRUD + activate / close
system应用CU（按产品查列表）
user用户CRUD
file附件编辑名称 + 删除
CRUD = 列表 + 详情 + 创建 + 更新 + 删除；CUD = 无独立列表接口，需指定所属范围
Module NameChineseSupported Operations
programProgramCRUD
productProductCRUD
projectProjectCRUD
executionExecution/IterationCRUD
storyStoryCRUD + activate / change / close
epicEpicCRUD + activate / change / close
requirementRequirementCRUD + activate / change / close
bugBugCRUD + activate / close / resolve
taskTaskCRUD + activate / close / finish / start
testcaseTest CaseCRUD
testtaskTest TaskCUD (query list by product/project/execution)
productplanProduct PlanCUD (query list by product)
buildBuildCUD (query list by project/execution)
releaseReleaseCUD (query list by product)
feedbackFeedbackCRUD + activate / close
ticketTicketCRUD + activate / close
systemSystemCU (query list by product)
userUserCRUD
fileAttachmentRename + Delete
CRUD = List + Details + Create + Update + Delete; CUD = No independent list interface, need to specify the scope

列表范围参数

List Scope Parameters

部分模块的列表需要指定所属范围：
bash
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 的工单
设置工作区后可省略这些参数（见下方工作区章节）。
Lists for some modules need to specify the scope:
bash
zentao story --product=1                # Stories of product #1
zentao bug --product=1                  # Bugs of product #1
zentao task --execution=1               # Tasks of execution #1
zentao execution --project=5            # Executions of project #5
zentao build --project=5                # Builds of project #5
zentao testtask --product=1             # Test tasks of product #1
zentao release --product=1              # Releases of product #1
zentao productplan --product=1          # Product plans of product #1
zentao feedback --product=1             # Feedback of product #1
zentao ticket --product=1               # Tickets of product #1
These parameters can be omitted after setting up the workspace (see the Workspace section below).

AI 使用策略

AI Usage Strategy

输出格式

Output Format

  • 展示给用户：不加 
    --format
    参数，默认输出 Markdown 表格（列表）或列表（单个对象）
  • 需要程序化处理：加 
    --format=json
    ，返回结构化 JSON
  • For display to users: Do not add the 
    --format
    parameter, default output is Markdown table (list) or list (single object)
  • For programmatic processing: Add 
    --format=json
    to return structured JSON

交互确认

Interactive Confirmation

AI 场景下执行删除操作时加 
--yes
跳过确认提示：
bash
zentao bug delete 1 --yes
Add 
--yes
to skip the confirmation prompt when performing delete operations in AI scenarios:
bash
zentao bug delete 1 --yes

不知道 ID 时

When ID is Unknown

先查列表获取 ID，再操作具体对象：
bash
zentao product --pick=id,name           # 查看产品列表
zentao bug --product=1 --pick=id,title  # 查看 Bug 列表
zentao bug 42                           # 查看具体 Bug
First query the list to get the ID, then operate on the specific object:
bash
zentao product --pick=id,name           # View product list
zentao bug --product=1 --pick=id,title  # View Bug list
zentao bug 42                           # View specific Bug

写操作前确认

Confirmation Before Write Operations

执行创建、更新、删除等写操作前，先向用户确认操作内容。用户明确要求不确认时可跳过。
Confirm the operation content with the user before performing write operations such as create, update, delete. You can skip the confirmation if the user explicitly requests it.

数据处理

Data Processing

摘取字段

Pick Fields

bash
zentao product --pick=id,name,status
bash
zentao product --pick=id,name,status

过滤

Filter

bash
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
支持的运算符：
:
等于、
!=
不等于、
>
<
>=
<=
、
~
包含、
!~
不包含。
bash
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, 
!~
does not contain.

模糊搜索

Fuzzy Search

bash
zentao bug --product=1 --search=登录 --search-fields=title,steps
bash
zentao bug --product=1 --search=login --search-fields=title,steps

排序

Sort

bash
zentao bug --product=1 --sort=pri_asc,severity_asc
bash
zentao bug --product=1 --sort=pri_asc,severity_asc

分页

Pagination

bash
zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --all            # 获取全部
zentao bug --product=1 --limit=10       # 只取前 10 条
bash
zentao bug --product=1 --page=1 --recPerPage=50
zentao bug --product=1 --all            # Get all
zentao bug --product=1 --limit=10       # Get only the first 10 items

常用操作示例

Common Operation Examples

查看进行中的项目和执行

View Ongoing Projects and Executions

bash
zentao project --filter='status:doing' --pick=id,name,status
zentao execution --project=5 --pick=id,name,status
bash
zentao project --filter='status:doing' --pick=id,name,status
zentao execution --project=5 --pick=id,name,status

创建需求

Create a Story

bash
zentao story create --product=1 --title="需求标题" --assignedTo=admin --pri=3
bash
zentao story create --product=1 --title="Story Title" --assignedTo=admin --pri=3

创建并解决 Bug

Create and Resolve a Bug

bash
zentao bug create --product=1 --title="Bug标题" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42
bash
zentao bug create --product=1 --title="Bug Title" --severity=2 --pri=2 --type=codeerror --openedBuild=trunk
zentao bug resolve 42

创建、启动并完成任务

Create, Start and Finish a Task

bash
zentao task create --execution=1 --name="任务名" --type=devel --assignedTo=admin --estimate=4
zentao task start 100
zentao task finish 100 --consumed=4
bash
zentao task create --execution=1 --name="Task Name" --type=devel --assignedTo=admin --estimate=4
zentao task start 100
zentao task finish 100 --consumed=4

查看帮助

View Help

bash
zentao bug help          # 查看 Bug 模块的参数和操作
zentao help              # 查看所有命令
bash
zentao bug help          # View parameters and operations for the Bug module
zentao help              # View all commands

意图识别

Intent Recognition

用户意图CLI 命令
所有产品/项目/项目集
zentao product
/ 
zentao project
/ 
zentao program
进行中的项目
zentao project --filter='status:doing'
某产品的 Bug
zentao bug --product=<id>
某执行的任务
zentao task --execution=<id>
创建/新增 Bug
zentao bug create ...
解决 Bug
zentao bug resolve <id>
关闭 Bug
zentao bug close <id>
激活 Bug
zentao bug activate <id>
创建需求
zentao story create ...
变更/关闭/激活需求
zentao story change/close/activate <id>
业务需求
zentao epic ...
（同 story）
用户需求
zentao requirement ...
（同 story）
创建/启动/完成/关闭任务
zentao task create/start/finish/close ...
测试用例
zentao testcase ...
测试单
zentao testtask ...
产品计划
zentao productplan ...
版本/Build
zentao build ...
发布
zentao release ...
反馈
zentao feedback ...
工单
zentao ticket ...
用户列表
zentao user
当前用户信息
zentao profile
User IntentCLI Command
All products/projects/programs
zentao product
/ 
zentao project
/ 
zentao program
Ongoing projects
zentao project --filter='status:doing'
Bugs of a product
zentao bug --product=<id>
Tasks of an execution
zentao task --execution=<id>
Create/add a Bug
zentao bug create ...
Resolve a Bug
zentao bug resolve <id>
Close a Bug
zentao bug close <id>
Activate a Bug
zentao bug activate <id>
Create a story
zentao story create ...
Change/close/activate a story
zentao story change/close/activate <id>
Epic
zentao epic ...
(same as story)
Requirement
zentao requirement ...
(same as story)
Create/start/finish/close a task
zentao task create/start/finish/close ...
Test case
zentao testcase ...
Test task
zentao testtask ...
Product plan
zentao productplan ...
Build
zentao build ...
Release
zentao release ...
Feedback
zentao feedback ...
Ticket
zentao ticket ...
User list
zentao user
Current user info
zentao profile

错误处理

Error Handling

错误码含义处理方式
E1001未登录/凭证缺失执行 
zentao login
E1004Token 失效执行 
zentao login
重新登录
E2001模块不存在执行 
zentao help
查看可用模块
E2002对象不存在检查 ID 是否正确
E2003缺少必要参数执行 
zentao <module> help
查看参数
E2006无权限提示用户检查权限
E5001请求超时检查网络或禅道服务状态
Error CodeMeaningSolution
E1001Not logged in/credentials missingExecute 
zentao login
E1004Token expiredExecute 
zentao login
to re-login
E2001Module does not existExecute 
zentao help
to view available modules
E2002Object does not existCheck if the ID is correct
E2003Missing required parametersExecute 
zentao <module> help
to view parameters
E2006No permissionPrompt the user to check permissions
E5001Request timeoutCheck network or ZenTao service status

注意事项

Notes

  • 不确定模块参数时，先执行 
    zentao <module> help
    查看帮助
  • browseType
    常用值：
    all
    （全部）、
    doing
    （进行中）、
    closed
    （已关闭）
  • 静默模式：
    --silent
    只输出错误信息
  • 多账号切换：
    zentao profile
    查看和切换账号
  • When unsure about module parameters, execute 
    zentao <module> help
    to view help first
  • Common values for 
    browseType
    : 
    all
    (all), 
    doing
    (ongoing), 
    closed
    (closed)
  • Silent mode: 
    --silent
    only outputs error messages
  • Multi-account switching: 
    zentao profile
    to view and switch accounts