zentao-shared

zentao-cli shared rules

This skill guides you on how to operate ZenTao resources through zentao-cli, as well as what precautions to take.

Configuration initialization

Automatic configuration bootstrapping process

When the user has not configured or authentication fails:

1. Detect configuration status

   zentao-cli auth status
   

   If it returns ZEN_AUTH_FAILED or ZEN_CONFIG_INVALID, it means it is not configured or the configuration is invalid.

2. Ask the user for configuration information and save location

   You must explicitly ask for the save location: global or current project?

Ask the user for the following:

• ZenTao service address (for example http://172.168.80.30:8001/zentao）
• ZenTao account
• ZenTao password
• Save location: global (~/.zentao-cli/config.toml) or current project (.zentao-cli/config.toml）？

⚠️ Important: You must wait for the user to explicitly answer the save location before executing the configuration command. It is forbidden to default to global configuration when the user has not chosen.

1. Execute configuration

   Global save:

   zentao-cli config set -g url "用户提供的地址"
   zentao-cli auth login -g --account 账号 --password 密码
   

   Current project save:

   zentao-cli config set url "用户提供的地址"
   zentao-cli auth login --account 账号 --password 密码
   

   Note:config set only supports url、token、product_id、project_id, and does not support directly setting the account and password. It must be done in two steps: first set the URL, then use auth login to obtain a token via the account and password.

2. Verify that configuration succeeded

   zentao-cli auth status
   

Quick check

# 检查认证状态
zentao-cli auth status

# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN

Obtain Token (manual)

1. Log in to the ZenTao Web interface
2. Go to Personal Settings → API Token
3. Generate a new Token
4. Set it as the ZENTAO_TOKEN environment variable

Environment variable description

Variable	Required	Description
ZENTAO_URL	Yes	ZenTao server address, for example https://zentao.example.com
ZENTAO_TOKEN	Yes	API Token, used for authentication
ZENTAO_PRODUCT_ID	No	Default product ID
ZENTAO_PROJECT_ID	No	Default project ID

Authentication

Token-based authentication

ZenTao uses Token for authentication, and the Token is passed through the ZENTAO_TOKEN environment variable.

# 验证认证状态
zentao-cli auth status

Error response format：

{
  "status": "error",
  "error": {
    "code": "ZEN_AUTH_FAILED",
    "message": "Invalid token or token expired",
    "hint": "Verify ZENTAO_TOKEN is correct"
  }
}

Common error codes

Code	Description	Resolution
ZEN_AUTH_FAILED	Token is invalid or expired	Verify whether ZENTAO_TOKEN is correct
ZEN_NOT_FOUND	Resource does not exist	Check the ID and retry
ZEN_CONFIG_INVALID	Configuration is invalid	Verify ZENTAO_URL and ZENTAO_TOKEN
ZEN_API_ERROR	ZenTao API returned an error	Check the server status or retry later
ZEN_PARAM_MISSING	Missing required parameters	Provide all required parameters

Handling insufficient permissions

When encountering permission-related errors:

1. Confirm the current user role (in ZenTao this is usually admin、leader or member）
2. Verify whether the Token has the permissions required to operate on that resource
3. If it is an administrator, check whether the user has been correctly assigned to the relevant project/product

Configuration priority

CLI parameter priority from highest to lowest:

1. Command-line parameters（--product, --project , etc.)
2. Environment variables（ZENTAO_PRODUCT_ID, ZENTAO_PROJECT_ID）
3. Default configuration

# 命令行参数优先级最高
zentao-cli task list --project 5  # 使用 --project 参数

# 环境变量作为默认值
export ZENTAO_PROJECT_ID=5
zentao-cli task list              # 使用环境变量

# 默认值兜底
zentao-cli task list              # 使用配置中的默认值

General options

Option	Description
--format	Output format:json、pretty、table、ndjson、csv
--product	Filter by product ID
--project	Filter by project ID
--status	Filter by status

Output format

# JSON 输出（默认，用于脚本）
zentao-cli story list --product 1 --format json

# Pretty 打印输出（默认，用于终端）
zentao-cli story list --product 1 --format pretty

# 表格输出
zentao-cli story list --product 1 --format table

Update check

After executing the zentao-cli command, if a new version is detected, the JSON output will include the _notice.update field (including message、command , etc.).

When you see _notice.update in the output, after completing the current request, additionally inform and propose an update：

1. Inform of the current version and latest version number
2. Propose executing:

   npm update -g zentao-cli && npx skills add zentao/cli -g -y
   

3. Remind the user to exit and reopen the AI Agent to load the latest Skills

Rule: Do not silently ignore update prompts. Even if the current task is unrelated to updates, you should additionally inform the user after completing their request.

Security rules

• Do not output secret keys(token, appSecret) to the terminal in plaintext.
• Confirm user intent before write/delete operations。
• Use --dry-run to preview dangerous requests.