SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstest-bk-cli

test-bk-cli

Deployment & operations

View repository

Updated 10-16 09:46

About this skill

test-bk-cli Skill

This skill guides systematic and safe exploration of bk-cli(BlueKing platform command-line tool). The goal is to test all available read-only commands,never modify any existing configuration，never execute destructive commands。

Prerequisites (confirm before starting)

Before executing any command, first confirm the following two points with the user:

  1. bk-cli is installed：bk-cli version or bk-cli -h can execute normally.
  2. Existing context is safe: during testingneverswitch, overwrite, or delete the user's existing context.

If either condition is not met, stop and guide the user to fix it before continuing.

Phase 1: Basic Commands

Test help、version、update、completion such built-in commands to verify basic CLI availability.

bk-cli -h         # 获取完整子命令列表，作为后续阶段的依据
bk-cli version    # 查看版本信息
bk-cli update -h  # 查看 update 用法（不执行实际更新）
bk-cli completion -h  # 查看 completion 用法（不执行安装）

Note：update and completion only view -h, do not actually execute, to avoid modifying the local environment.

Phase 2: Authentication and Context

First view help separately, then test the various subcommands of context and auth according to the complete workflow.

View help

bk-cli context -h
bk-cli auth -h

Complete test workflow

In this phase, create a temporary context to fully test all subcommands, and clean up thoroughly after testing,without affecting the user's original default context。

Before execution, first obtain from the default context bk_api_url_tmpl（bk-cli context list), the new context uses the same URL. For authentication parameters, use the following fixed test values without asking the user:

  • Context name:test-ctx
  • bk_app_code：test_bk_app_code
  • bk_app_secret：test_bk_app_secret
  • bk_token：test_bk_token
# 1. 创建临时 context
bk-cli context create test-ctx --bk_api_url_tmpl="<default 的 url_tmpl>"

# 2. 切换到新 context
bk-cli context use test-ctx

# 3. 在新 context 下登录
bk-cli auth login --bk_app_code="test_bk_app_code" --bk_app_secret="test_bk_app_secret" --bk_token="test_bk_token"

# 4. 查看认证状态（应已认证）
bk-cli auth status

# 5. 登出
bk-cli auth logout

# 6. 再次查看认证状态（应未认证）
bk-cli auth status

# 7. 重新登录（恢复认证）
bk-cli auth login --bk_app_code="test_bk_app_code" --bk_app_secret="test_bk_app_secret" --bk_token="test_bk_token"

# 8. 列出所有 context（确认新 context 存在且 active）
bk-cli context list

# 9. 切回 default context
bk-cli context use default

# 10. 删除临时 context（清理）
bk-cli context delete test-ctx

Verify after the workflow ends:bk-cli context list no longer contains test-ctx, active remains default。

Phase 3: API Tool Commands

Test api and apigateway commands to learn the available gateways and interfaces.

bk-cli apigateway

bk-cli apigateway -h                            # 查看子命令
bk-cli apigateway list_gateways                 # 列出所有网关
bk-cli apigateway list_gateway_apis --gateway_name <name>   # 列出网关下的所有接口
bk-cli apigateway retrieve_gateway_api_details --gateway_name <name> --api_name <api>  # 查看接口详情

bk-cli api

bk-cli api is the raw HTTP client; in this phase test it together with apigateway : use apigateway to query the real API path corresponding to a system command, then use bk-cli api to directly call and verify.

Example test workflow:

# 1. 查询某网关下某个命令的真实 API 路径
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-apigateway --api_name v2_open_list_gateways

# 2. 从返回结果中提取 path、method
# 例如得到：GET /api/v2/open/gateways/

# 3. 用 bk-cli api 直接调用，可附加过滤参数
bk-cli api bk-apigateway GET "/api/v2/open/gateways/?name=bk-iam"

Select 2–3 representative read-only interfaces (GET/POST) for verification; there is no need to exhaustively test all interfaces.bk-cli api Used only in this phase; when testing system subcommands in Phase 4, it is forbidden to use it to bypass。

Phase 4: System Subcommands (Read-Only Only)

For each system subcommand (cmdb, gse, job, sops, nodeman, devops, etc.), follow these steps:

Test steps for each system

  1. Execute bk-cli <system> -h ——obtain the complete list of subcommands.
  2. Identify read-only commands: includes get_*、list_*、search_*、find_*、query_*、retrieve_*. Skip create_*、delete_*、update_*、transfer_*、operate_*、start_*、push_*、fast_execute_*、install_* etc.
  3. For each read-only command, execute bk-cli <system> <command> -h ——understand the required parameters.
  4. Collect necessary parameters——prefer to derive from the results of commands already executed in this session; only ask the user when derivation is truly impossible.
  5. Execute bk-cli <system> <command> and display the raw output. If the command fails, report the error truthfully and wait for user instructions.

Parameter sourcing strategy

Derive parameters from existing command results as much as possible to minimize interruptions to the user:

  • After executing search_business , obtain bk_biz_id。
  • After executing list_biz_hosts , obtain the host IP and bk_agent_id。
  • After executing search_set , obtain bk_set_id, which can be used for search_module。
  • After executing get_job_instance_status , obtain step_instance_id, which can be used for log queries.

Only ask the user for parameters that truly cannot be derived (such as those in the user's own job history: job_instance_id, devops's project_id).

Handling 403 errors

When the API gateway returns 403（X-Bkapi-Error-Code: 1640301, message:App has no permission）：

Stop immediately. Do not try other paths, do not retry. Tell the user:

"Encountered 403 insufficient permissions. You need to grant the application <bk_app_code> access to the <gateway_name> gateway in the API gateway management console. Please go to: API Gateway → Gateway Management → <gateway_name> → Permission Management → Application Permissions → Add <bk_app_code>. After completing the authorization, let me know and I will re-execute."

bk_app_code and gateway_name can be obtained from the 403 response headers and error message.

When the business system returns 403(such as bk_error_code: 9900403, IAM permission error):

Stop immediately. Tell the user:

"Encountered insufficient business permissions (IAM 9900403). You need to apply in the permission center for the application <bk_app_code> to have the <system_name> system's <action_name> permission. Please go to: BlueKing Permission Center → Apply for Permission → Select system <system_name> → Action <action_name>。"

Security rules (absolutely prohibited)

The following rules must not be violated:

  1. Never executecommands whose names contain the following words:create、delete、update(in system subcommands),transfer、install、start、operate、push、fast_execute、revoke、retry。
  2. Protect the default context—the second phase only performs auth testing on a temporary context, and must ultimately switch back to default and delete the temporary context; it is prohibited to perform any modification or deletion operations on the default context.
  3. The fourth phase may only use bk-cli <system> <command>—it is prohibited to use bk-cli api to bypass system subcommands, regardless of any errors encountered.
  4. Never guess API paths or parameters based on training knowledge—always use -h output to discover available commands and parameters.
  5. Stop immediately upon encountering 403—do not try other endpoints or alternative paths.
  6. Do not proactively use --dry-run—unless the user explicitly requests a command preview.

Output format

After each command test, display:

  1. The command actually executed.
  2. The raw CLI output (if the info/data array exceeds 10 entries, truncate to the first 3 and note the total count).
  3. A one-line result explanation (success / error type).

After each phase or system test ends, provide a summary table:

Command Status Notes
search_business ✅ Returned 1 business
list_biz_hosts ✅ 52 hosts in total
list_hosts_without_biz ❌ IAM 403 Requires the view_resource_pool_host permission

Example: Handling 403

收到 403：App has no permission [bk_app_code=bk_apigw_test, gateway=bk-sops]

→ 立即停止，告知用户：
"遇到了 403。请在 API 网关后台给 bk_apigw_test 授权 bk-sops 网关权限后告诉我，我重新执行。"