Used to invoke the high-frequency system subcommands of the CMDB open API via bk-cli cmdb .
CRITICAL — Before starting, you MUST first use the Read tool to read ../bk-cli-shared/SKILL.md. The shared skill handles authentication, context, tenant, stage, dry-run, verbose, header/body, and general request rules; this skill only supplements cmdb the command's own semantics and input conventions.
Current coverage
This skill currently covers these high-frequency cmdb commands:
get_biz_internal_modulesearch_businesssearch_setcreate_setsearch_modulecreate_modulelist_biz_hosts_alllist_biz_hostslist_hosts_without_bizfind_host_biz_relationslist_biz_hosts_topotransfer_host_moduletransfer_host_across_biztransfer_host_to_idle_moduletransfer_host_to_fault_moduletransfer_host_to_recycle_moduletransfer_host_to_resource_poollist_resource_pool_hostsdelete_host
If more cmdb subcommands are added later, they should continue to be appended to this skill's ## Commands section, rather than split into new single-command skills.
Recommended workflow
- First confirm whether the target already has an existing
cmdbsubcommand. - If an existing subcommand is available, prefer using that command rather than falling back directly to the raw
bk-cli api。 - On the first call or when troubleshooting, prefer adding
--dry-runfirst to see the final URL, headers, and body. - If the existing subcommands still cannot cover your target API, then fall back to
bk-cli api bk-cmdb ...。
Input conventions
General rules
- Most
cmdbcommands support--stage、--header、--body;list_biz_hosts_allException: does not expose--body。 - When explicitly passing
--body '<json>', the request will be based on that JSON and will no longer use the command's built-in default request content. - These
cmdbcommands usually require credentials that can satisfy app+user; if the current context usesaccess_token, it can also satisfy the non-empty authentication requirement.
CSV list parameters
Currently cmdb list-type inputs uniformly prefer CSV-style flags:
--bk_biz_ids 1,2,3--bk_host_ids 100,200--bk_module_ids 20,30--fields bk_host_id,bk_host_innerip
--host_ips rules
- Form one:
10.0.0.1 - Form two:
27:10.0.0.2 - Meaning:
cloud_id:ip; when no prefix is written, the default iscloud_id=0 - As long as there is one invalid item, the command will directly report an error and will not silently skip it
Commands
Business and topology
search_business
bk-cli cmdb search_business [--bk_biz_id <id> | --bk_biz_ids <id,id,...>] [flags]
- When not explicitly passing
--body, you must provide one of the two:--bk_biz_idor--bk_biz_ids - Default
--fields bk_biz_id,bk_biz_name,bk_biz_maintainer,bk_biz_productor - Default
--limit 500 - Default
--supplier_account 0 - Call path:
POST /api/v3/open/biz/search/{supplier_account}/
get_biz_internal_module
bk-cli cmdb get_biz_internal_module --bk_biz_id <id> [--supplier_account 0]
- Get the business's built-in modules (idle machine / faulty machine / to be recycled)
- Call path:
GET /api/v3/open/topo/internal/{supplier_account}/{bk_biz_id}
Cluster and module
search_set
bk-cli cmdb search_set --bk_biz_id <id> [flags]
- Default
--fields bk_set_id,bk_set_name - Default
--limit 500 - Optional filters:
--bk_set_name、--bk_set_id - Call path:
POST /api/v3/open/set/search/{supplier_account}/{bk_biz_id}
create_set
bk-cli cmdb create_set --bk_biz_id <id> --bk_set_name <name> [flags]
- Default
bk_parent_id = bk_biz_id - Default
set_template_id = 0 - Always send
default = 0 - Optional fields:
--bk_set_env、--bk_service_status、--bk_set_desc、--bk_capacity - Call path:
POST /api/v3/open/set/{bk_biz_id}
search_module
bk-cli cmdb search_module --bk_biz_id <id> --bk_set_id <id> [flags]
- Default
--fields bk_module_id,bk_module_name - Default
--limit 500 - Optional filters:
--bk_module_name、--bk_module_id - Call path:
POST /api/v3/open/module/search/{supplier_account}/{bk_biz_id}/{bk_set_id}
create_module
bk-cli cmdb create_module --bk_biz_id <id> --bk_set_id <id> --bk_module_name <name> [flags]
- Default
bk_parent_id = bk_set_id - Optional fields:
--bk_module_type、--operator、--bk_bak_operator、--service_template_id、--service_category_id - Call path:
POST /api/v3/open/module/{bk_biz_id}/{bk_set_id}
Host query
list_biz_hosts_all
bk-cli cmdb list_biz_hosts_all --bk_biz_id <id> [--bk_set_id <id>] [--bk_module_id <id>] [--page_limit 500]
- The command will automatically loop through and fetch all paginated results and return them aggregated
- Does not expose
--body - dry-run only previews the first page request, and in
data.paginationadds pagination metadata - Call path:
POST /api/v3/open/hosts/app/{bk_biz_id}/list_hosts
list_biz_hosts
bk-cli cmdb list_biz_hosts --bk_biz_id <id> [--host_ips 10.0.0.1,27:10.0.0.2]
- Fixed fields:
bk_host_id,bk_host_innerip,bk_cloud_id,bk_host_name --host_ipsUsed to filter hosts by IP- Call path:
POST /api/v3/open/hosts/app/{bk_biz_id}/list_hosts
list_hosts_without_biz
bk-cli cmdb list_hosts_without_biz [--host_ips 10.0.0.1,27:10.0.0.2]
- Query all hosts within the business scope
- Fixed fields:
bk_host_id,bk_host_innerip,bk_cloud_id,bk_host_name,operator,bk_bak_operator - Call path:
POST /api/v3/open/hosts/list_hosts_without_app
find_host_biz_relations
bk-cli cmdb find_host_biz_relations --bk_host_ids 1,2,3
- Query host-to-business/cluster/module relationships
- Call path:
POST /api/v3/open/hosts/modules/read - If the upstream
datais not a list, the CLI normalizes the output to an empty array[]
list_biz_hosts_topo
bk-cli cmdb list_biz_hosts_topo --bk_biz_id <id> [--host_ips 10.0.0.1]
- Query business hosts and topology information
- Fixed fields:
bk_host_id,bk_host_innerip,bk_cloud_id - Call path:
POST /api/v3/open/hosts/app/{bk_biz_id}/list_hosts_topo
list_resource_pool_hosts
bk-cli cmdb list_resource_pool_hosts [flags]
- Optional:
--host_ips、--fields、--start、--limit - Fixed pagination sorting:
page.sort = bk_host_id - Call path:
POST /api/v3/open/hosts/list_resource_pool_hosts
Host transfer and deletion
transfer_host_module
bk-cli cmdb transfer_host_module --bk_biz_id <id> --bk_host_ids 1,2 --bk_module_ids 20,30 [--is_increment]
- Transfer host to module within business
- Call path:
POST /api/v3/open/hosts/modules
transfer_host_across_biz
bk-cli cmdb transfer_host_across_biz --src_bk_biz_id <id> --dst_bk_biz_id <id> --bk_host_ids 1,2 --bk_module_id 20
- Cross-business host transfer
- Call path:
POST /api/v3/open/hosts/modules/across/biz
transfer_host_to_idle_module
bk-cli cmdb transfer_host_to_idle_module --bk_biz_id <id> --bk_host_ids 1,2
- Call path:
POST /api/v3/open/hosts/modules/idle
transfer_host_to_fault_module
bk-cli cmdb transfer_host_to_fault_module --bk_biz_id <id> --bk_host_ids 1,2
- Call path:
POST /api/v3/open/hosts/modules/fault
transfer_host_to_recycle_module
bk-cli cmdb transfer_host_to_recycle_module --bk_biz_id <id> --bk_host_ids 1,2
- Call path:
POST /api/v3/open/hosts/modules/recycle
transfer_host_to_resource_pool
bk-cli cmdb transfer_host_to_resource_pool --bk_biz_id <id> --bk_host_ids 1,2 [--bk_module_id 50]
- Return host to resource pool
- Call path:
POST /api/v3/open/hosts/modules/resource
delete_host
bk-cli cmdb delete_host --bk_host_ids 100,200
- Delete host from resource pool
- Call path:
DELETE /api/v3/open/hosts/batch - The request will send
bk_host_idas a comma-separated string as required by the API, for example100,200
Example
# 先看 dry-run
bk-cli cmdb search_set --bk_biz_id 2 --bk_set_name web --dry-run
# 聚合业务下所有主机
bk-cli cmdb list_biz_hosts_all --bk_biz_id 2 --page_limit 200
# 只查指定云区域和 IP 的主机
bk-cli cmdb list_biz_hosts --bk_biz_id 2 --host_ips 0:10.0.0.1,27:10.0.0.2
# 把主机批量转到指定模块
bk-cli cmdb transfer_host_module \
--bk_biz_id 2 \
--bk_host_ids 1,2 \
--bk_module_ids 20,30
When to fall back bk-cli api
The following situations are better suited to using the raw API directly:
- The target API does not yet have a corresponding
cmdbsubcommand - Need to fully customize query/body without being constrained by existing flag semantics
- Need to first verify the complete method/path/body/header, then gradually converge into a high-level command
Example:
bk-cli api bk-cmdb POST /api/v3/open/hosts/modules \
--body '{"bk_biz_id":2,"bk_host_id":[1,2],"bk_module_id":[20],"is_increment":false}' \
--dry-run
Common errors
| Error symptom | Common cause | Suggestion |
|---|---|---|
one of bk_biz_id or bk_biz_ids is required when --body is not provided |
search_business not passed --body, and also did not pass --bk_biz_id / --bk_biz_ids |
Add a business filter condition, or explicitly pass --body |
host_ips contains an invalid host entry |
--host_ips contains an illegal token |
Change to the 10.0.0.1,27:10.0.0.2 format |
bk_host_ids must be a comma-separated list of integers |
--bk_host_ids contains empty values, non-numeric values, or negative numbers |
Change to the 1,2,3 format |
supplier_account cannot be empty |
--supplier_account is an empty string |
Use 0 or an explicit supplier account |
| Authentication failed / forbidden | Credentials do not meet the open API authentication requirements, or the application lacks permissions | First check the authentication rules of the shared skill, then verify the credentials and permissions of the current context |