zentao-user

User (v2)

CRITICAL — Before starting, you MUST first use the Read tool to read ../zentao-shared/SKILL.md, which contains authentication, environment variables, and error handling.

User identification tips: In ZenTao, users are identified by numeric ID, but in scenarios such as assigning tasks, Bugs, etc., account (account name) may be used. When making API calls, be careful to distinguish between id and account。

User identity scenarios: When the user mentions "me" (for example, "assign to me", "created by me"), the ID of the currently logged-in user is required. You can use zentao-cli user list to view your own account information.

Departments and roles: Users belong to a department (dept) and have a role (role). Common roles include: dev (development), manager (manager), qa (testing), pd (product), etc.

Friendly output: When outputting user details, in addition to displaying account and id, you should also display realname(real name) for identification.

User Role Types

Role	Description	Description
dev	Developer	Developer
manager	Manager	Manager
qa	QA/Test	Tester
pd	Product Designer	Product design
op	Operations	Operations
admin	Administrator	Administrator

Commands

• user list — List users with optional filters
• user get — Get user details by ID
• user me — Get current user info
• user create — Create a new user
• user update — Update user information
• user delete — Delete a user

Common Use Cases

Scenario 1: Query all users

# 列出系统中的所有用户
zentao-cli user list

Scenario 2: Query users by department

# 查看某部门下的所有用户
zentao-cli user list --dept 1

# 组合筛选：某部门的开发人员
zentao-cli user list --dept 1 --role dev

Scenario 3: Query users by role

# 查看所有开发人员
zentao-cli user list --role dev

# 查看所有测试人员
zentao-cli user list --role qa

Scenario 4: Get user details

# 通过用户 ID 获取详细信息
zentao-cli user get 123

# 输出包括：账号、姓名、邮箱、部门、角色等

Examples

# 列出系统中的所有用户
zentao-cli user list

# 查看某部门下的所有用户
zentao-cli user list --dept 1

# 查看所有开发人员
zentao-cli user list --role dev

# 通过用户 ID 获取详细信息
zentao-cli user get 123

Output Fields

Field	Type	Description
id	u64	User ID (unique identifier)
account	string	Login account name
realname	string	Real name
email	string	Email (optional)
dept	u64	Department ID (optional)
role	string	Role (optional)
phone	string	Phone (optional)
mobile	string	Mobile (optional)

Error Handling

Common errors

Error code	Description	Solution
ZEN_AUTH_FAILED	Token is invalid or expired	Check the ZENTAO_TOKEN configuration
ZEN_NOT_FOUND	User does not exist	Check whether the user ID is correct
ZEN_CONFIG_INVALID	Invalid configuration	Verify ZENTAO_URL and ZENTAO_TOKEN
ZEN_API_ERROR	ZenTao API returned an error	Check the server status or try again later

Error handling example

# 遇到 auth 错误时检查认证状态
zentao-cli auth status

# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN

Gotchas

1. id vs account: A user has id(numeric) and account(account name string), two identification methods. API parameters may accept one or both, so be careful to distinguish.

2. dept is 0: Some users may not have a department, and the dept field is 0 or empty.

3. role field value: role is a string such as "dev", "manager", not a numeric code. When using the --role parameter, the complete role name string should be used.

4. Handling when the user does not exist: When the queried user ID or account does not exist, the API returns an error instead of an empty list.

5. Batch operations: ZenTao user management mainly supports queries, and does not support batch creation/update of users (usually performed by administrators on the Web side).