Through zentao operate ZenTao. Use the offline help of the currently installed version as the basis for commands; fields, actions, and minimum server versions may change with CLI / SDK updates.
Getting Started
When a usable zentao command is already available, reuse it directly. First confirm the site, object scope, and operations the user wants to access; do not repeatedly ask about content already clarified in context.
zentao --version
zentao help
zentao profile --format=json
help, module/operation--help、propsdo not require login. Check help first before preparing requests; there is no need to connect to the server just to view parameters.profileonly lists locally saved accounts and sites; it does not validate Token, network, or business roles. When connection verification is needed, execute a read-only query within the scope the user wants to access.- When no local account is configured,
profilereturnsE1006; complete environment credentials can still be used for business commands. Do not conclude from this that the service is unavailable. - When not installed, choose according to the user environment
npm install -g zentao-cli、bun install -g zentao-cliorpnpm install -g zentao-cli; for one-off runs,npx zentao-cli <参数>。
When the user requests to install or update the skill, use zentao add-skill <agent>; when export to a custom directory is needed, use zentao add-skill --output ./exported-skills. The two forms are mutually exclusive, and both recursively include reference materials. Only process the targets specified by the user; before rerunning, preserve the customizations the user needs in skills with the same name.
Authentication and Account Selection
Business commands will error when credentials are missing and will not automatically pop up a login. When login is needed, have the user execute zentao loginin their own interactive terminal, and the CLI will collect credentials. Do not collect passwords or Tokens in the conversation, and do not read or print credential environment variables or local credential files.
Automation credentials are provided by the runtime environment:ZENTAO_URL + ZENTAO_ACCOUNT + ZENTAO_TOKEN or ZENTAO_PASSWORD. When the same source provides both a Token and a password, prefer the Token. Business commands should prioritize complete environment credentials, then fall back to the currently saved Profile.
zentao profile 'admin@https://zentao.example.com'
The above commands switch the local default account; complete environment credentials still take precedence, and a successful switch alone cannot be used to determine that subsequent requests used that account. The credential source must be adjusted by the runtime environment maintainer.
The default credential file is ~/.config/zentao/zentao.json; a custom path can use the global --config <路径> or ZENTAO_CONFIG_FILE, with the former taking precedence. Follow the configuration path selected by the user; do not confirm identity by directly reading the file.
Finding Commands and Parameters
| Intent | Command Form |
|---|---|
| List (only for modules that support default listing) | zentao <module> [范围参数] |
| Details (only for modules that support get) | zentao <module> <id> |
| Create / Update / Delete | zentao <module> create / zentao <module> update <id> / zentao <module> delete <id> |
| Status transition or named operation | zentao <module> <action> [参数] |
| Operation parameters, required items, minimum version | zentao <module> <action> --help |
| Field definitions of the returned object | zentao <module> props --format=json |
props is not a list of writable fields, nor does it represent the dynamic options of the current site. Creation, updates, and status transitions are all based on operation help; first understand the purpose of the parameters, then choose values.
- For business fields, prefer
--field=value, preserving the casing in the help. For complex objects, arrays, or long text, see references/writes.md。 - Do not infer that every module has CRUD.
doc、myhas no default list; a named operation must be selected. - Multiple path parameters must be passed separately; positional ID /
--idrepresents only the first path ID and cannot stand in for subsequent IDs. - When you don't know the ID, first search by product, project, or execution; only clarify once objects with the same name appear. Do not reuse the example IDs.
browseTypeis the server-side filter value specific to each API, for example projectdoing, requirementallstory; it cannot be copied across different modules.
Common entry points
First use the --help of the corresponding operation to confirm the installed version supports it, then substitute the real ID:
zentao product --pick=id,name
zentao story --product=1 --pick=id,title,status
zentao bug --product=1 --pick=id,title,status
zentao task --executionID=1 --pick=id,name,status
zentao project --browseType=doing --pick=id,name,status
zentao execution projectExecutions --projectID=5 --browseType=all
zentao productplan --productID=1
zentao release --productID=1
zentao build --project=5
zentao my tasks --pick=id,name,status
zentao my bugs --pick=id,title,status
zentao my todos
zentao doc myDocs --spaceID=1 --libID=2
Requirements are divided into epic(business requirements),requirement(user requirements),story(development requirements). Capabilities such as issues issue, risks risk, meetings meeting, workflows workflow, documents doc are discovered through module help; there is no need to apply the fields of tasks or bugs.
Server version
The help offline lists the complete registry, which does not mean the server supports all actions. The actual server version is checked before a request; minimum versions are compared within the same series, for example 22.5 / biz13.5 / max8.5 / ipd5.5. The specific threshold is subject to the help for that action; do not use a uniform version number to infer all newly added capabilities.
When encountering E2010 , report the current version and the requirement of that action. You may switch to an already supported query with equivalent semantics, for example querying tasks by execution, or paging through global executions and then filtering by project; do not treat the substitute query as a full result, and do not modify version information to bypass the check.zentao version The server information in it comes from a local cache and is not a real-time compatibility verification.
Execution and verification
- Queries are suitable for reading by default; for programmatic processing explicitly add
--format=json. For full statistics, filtering, sorting, raw responses, and JSON structure see references/data-output.md。 - Create, update, and status transitions are executed according to the goals and fields the user has authorized; explicit requests are not confirmed again. When the goal, status meaning, or necessary information is missing, only ask about what affects this operation.
- When the user only asks to view, analyze, or advise, return the results first. A demonstration does not represent authorization to modify existing business records.
- Update auto-completion only takes effect when a usable detail operation exists, and only fills in the writable fields declared by the current action; do not assume all modules have details or that all fields can be preserved. For specific boundaries and examples see references/writes.md。
- For deletion and batch operations, first establish the set of objects the user has authorized; automated deletion must explicitly pass
--yes. When a batch partially fails, report the succeeded, failed, and skipped objects separately; do not retry the whole batch. - Query the details by the returned ID or verify the key fields in the owning list before announcing results such as creation, association, or completion. When a write times out or the response is unclear, first query whether it has taken effect; in particular, do not blindly retry creation.
Error handling
Retain the key points of the error and handle it according to the cause; do not classify all errors as needing to log in again.
| Error code | Handling |
|---|---|
| E1001 / E1006 | Credentials are incomplete or no usable configuration exists; ask the user to log in interactively or configure complete environment credentials |
| E1003 / E1004 | Incorrect account or password, or the Token has expired; ask the user to log in again |
| E1005 / E1007 | The configuration is unreadable or the specified Profile does not exist; check the configuration path, and use profile to view available accounts |
| E2001 / E2005 | The module or action does not exist; check local help |
| E2002 | The object or API was not found; verify the ID, scope, and specific error URL, and do not immediately conclude that the record has been deleted |
| E2003 / E2004 / E2007 / E2009 | Missing parameters, wrong type/option, or invalid JSON; consult the action help to correct it |
| E2006 | No permission; explain the restricted operation and leave authorization to the user |
| E2008 | Server-side business or HTTP error; check the specific response, and do not treat HTTP 200 or raw output as success |
| E2010 | Unsupported by the server version; explain the requirement, choose a supported equivalent capability, or have the user upgrade |
| E2011 / E2012 | Unable to recognize the version format or site configuration; verify the site root address and its ?mode=getconfig response |
| E1002 / E5001 / E5002 | Address unreachable, timeout, or certificate verification failed; verify the network, address, and certificate; for write requests, confirm the result before deciding whether to retry |