SuperAPI AI Directory

bk-cli-cmdb

General & other

View repository

Updated 10-16 09:55

About this skill

bk-cli cmdb — CMDB capability usage instructions

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_module
  • search_business
  • search_set
  • create_set
  • search_module
  • create_module
  • list_biz_hosts_all
  • list_biz_hosts
  • list_hosts_without_biz
  • find_host_biz_relations
  • list_biz_hosts_topo
  • transfer_host_module
  • transfer_host_across_biz
  • transfer_host_to_idle_module
  • transfer_host_to_fault_module
  • transfer_host_to_recycle_module
  • transfer_host_to_resource_pool
  • list_resource_pool_hosts
  • delete_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

  1. First confirm whether the target already has an existing cmdb subcommand.
  2. If an existing subcommand is available, prefer using that command rather than falling back directly to the raw bk-cli api。
  3. On the first call or when troubleshooting, prefer adding --dry-run first to see the final URL, headers, and body.
  4. If the existing subcommands still cannot cover your target API, then fall back to bk-cli api bk-cmdb ...。

Input conventions

General rules

  • Most cmdb commands support --stage、--header、--body;list_biz_hosts_all Exception: 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 cmdb commands usually require credentials that can satisfy app+user; if the current context uses access_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 is cloud_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_id or --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.pagination adds 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_ips Used 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 data is 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_id as a comma-separated string as required by the API, for example 100,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 cmdb subcommand
  • 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