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
# or bun install -g zentao-cli
# or pnpm install -g zentao-cli
# or run without installation: npx zentao-cli

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

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):

Variable	Description
`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

Use the shorthand format (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`

You can also pass JSON data using

--data='JSON'

Module & 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	Epic	CRUD + activate / change / close
requirement	Requirement	CRUD + activate / change / close
bug	Bug	CRUD + activate / close / resolve
task	Task	CRUD + activate / close / finish / start
testcase	Test Case	CRUD
testtask	Test Task	CUD (query list by product/project/execution)
productplan	Product Plan	CUD (query list by product)
build	Build	CUD (query list by project/execution)
release	Release	CUD (query list by product)
feedback	Feedback	CRUD + activate / close
ticket	Ticket	CRUD + activate / close
system	System	CU (query list by product)
user	User	CRUD
file	Attachment	Rename + Delete

CRUD = List + Details + Create + Update + Delete; CUD = No independent list interface, need to specify the scope

List Scope Parameters

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 Usage Strategy

Output Format

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

Add

--yes

to skip the confirmation prompt when performing delete operations in AI scenarios:

bash

zentao bug delete 1 --yes

When ID is Unknown

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

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

Supported operators:

equals,

!=

not equals,

>=

<=

contains,

!~

does not contain.

Fuzzy Search

bash

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

Sort

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            # 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

Create a Story

bash

zentao story create --product=1 --title="Story Title" --assignedTo=admin --pri=3

Create and Resolve a Bug

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="Task Name" --type=devel --assignedTo=admin --estimate=4
zentao task start 100
zentao task finish 100 --consumed=4

View Help

bash

zentao bug help          # View parameters and operations for the Bug module
zentao help              # View all commands

Intent Recognition

User Intent	CLI 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

Error Code	Meaning	Solution
E1001	Not logged in/credentials missing	Execute `zentao login`
E1004	Token expired	Execute `zentao login` to re-login
E2001	Module does not exist	Execute `zentao help` to view available modules
E2002	Object does not exist	Check if 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 timeout	Check network or ZenTao service status

Notes

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

zentao-cli

NPX Install

Tags

SKILL.md Content (Chinese)

ZenTao CLI

Prerequisites

Installation

Authentication

Command Format

Module & Operation Quick Reference

List Scope Parameters

AI Usage Strategy

Output Format

Interactive Confirmation

When ID is Unknown

Confirmation Before Write Operations

Data Processing

Pick Fields

Filter

Fuzzy Search

Sort

Pagination

Common Operation Examples

View Ongoing Projects and Executions

Create a Story

Create and Resolve a Bug

Create, Start and Finish a Task

View Help

Intent Recognition

Error Handling

Notes