bk-cli-shared

bk-cli shared — general usage rules and troubleshooting entry point

When to prefer this Skill

• The user is asking about rules that are "common to all systems," such as authentication, context, tenant, header, body, timeout, stage, dry-run, and verbose.
• The user is troubleshooting a failed request, but the problem has not yet clearly landed on a specific system command.
• The user is unsure whether to first look at a system-specific skill or first confirm shared input and runtime settings.
• The user wants to first see clearly "how the request is sent out" before deciding whether to go deeper into a specific system command.

Recommended reading order

1. First read this skill to confirm shared usage rules and troubleshooting order.
2. Then read the system-specific skill to fill in specific commands, fields, and examples.
3. If the system-specific commands do not yet cover the target API, then read bk-cli-api to handle raw calls.

Basic preparation

# 初始化 context
bk-cli context init \
  --bk_api_url_tmpl="https://bkapi.your-domain.com/api/{gateway_name}/"

# 登录：app + user
bk-cli auth login --bk_app_code="your_app" --bk_app_secret="your_secret" --bk_token="your_token"
bk-cli auth login --bk_app_code="your_app" --bk_app_secret="your_secret" --bk_ticket="your_ticket"

# 登录：access_token
bk-cli auth login --access_token="your_token"

# 环境自检
bk-cli doctor
bk-cli doctor --offline

Common Flags

Flag	Scope	Description
--context <name>	Global	A single command overrides the currently active BlueKing context
--stage <stage>	API Gateway request	Gateway stage, default prod, common values are testing
--dry-run	Request-type commands	Only preview the request, do not make a network request
--verbose	Request-type commands	Print request/response details to stderr
--insecure	Request-type commands	Skip HTTPS certificate verification, only for temporary debugging
--header 'Key:Value'	Request-type commands, repeatable	Pass additional request headers; header name and value are validated locally
--body '<json>'	Request-type commands that support body	Pass a JSON body, the CLI manages Content-Type: application/json
--timeout <duration>	bk-cli api	Override context timeout for a single run, for example 180s

Multi-Context management

A context represents an independent BlueKing deployment target, not an API Gateway stage;prod、testing environment stages such as these should be controlled via --stage control.

# 创建不同部署的 context，并设置该 context 的默认 timeout / tenant
bk-cli context create clouds \
  --bk_api_url_tmpl="https://bkapi.clouds.example.com/api/{gateway_name}/" \
  --tenant_id="tenant-a" \
  --timeout 120s

bk-cli context create devops \
  --bk_api_url_tmpl="https://bkapi.devops.example.com/api/{gateway_name}/"

# 查看、切换、单次覆盖 context
bk-cli context list
bk-cli context use clouds
bk-cli api bk-iam GET /api/v2/systems/ --context devops

• Each context maintains its own set of credentials and defaults.
• bk-cli auth login writes credentials into the current active context, or into the context specified by --context <name> the specified context.
• When a command executes, the context source priority is: explicit --context, current active context, fallback to an existing local context.
• Explicitly specifying a nonexistent --context will directly error out and will not silently fall back.
• Context names must match ^[a-z][a-z0-9-]*$, for example default、clouds、prod-1。
• tenant is the default value of the context; use this when overriding the tenant for a single run --header 'X-Bk-Tenant-Id:<value>'。

General request rules

• stdout outputs a structured JSON envelope; CLI-level errors and verbose information are output to stderr.
• --dry-run is suitable for first confirming whether the URL, query, body, and headers are correct.
• --verbose takes effect for request-type commands, and request/response details are output to stderr.
• --insecure similar to curl --insecure, only affects real HTTPS requests; use it again when temporarily debugging self-signed certificates or a test environment.
• --header must include :and the header name cannot be empty; an invalid header will not enter the network request stage.
• --header can explicitly override X-Bkapi-Authorization and X-Bk-Tenant-Id。
• When passing --body it still cannot manually override Content-Type, that header is managed by the CLI.
• dry-run / verbose will apply masking to X-Bkapi-Authorization for display, even if that header is explicitly overridden by the caller.
• Path placeholder values are escaped as a single URL path segment, and you cannot rely on it to inject /、? or other path structures.

Timeout rules

• Every context has a default timeout, and when unset it is 60s。
• bk-cli api uses the current context's timeout by default; when explicitly passing --timeout <duration> , this request preferentially uses that value.
• Some system commands may describe additional timeout behavior in their own help information or system-specific skill; when encountering such commands, defer to that command's help and the system skill.

Authentication and login

In most cases, you do not need to care how the CLI internally assembles authentication headers; you only need to ensure the target context is logged in to a matching identity.

Currently bk-cli publicly supports three login forms:

• bk-cli auth login --bk_app_code=X --bk_app_secret=Y --bk_token=Z
• bk-cli auth login --bk_app_code=X --bk_app_secret=Y --bk_ticket=Z
• bk-cli auth login --access_token=Z

When troubleshooting authentication issues, first remember the following points:

• bk-cli auth status is suitable for checking "whether the current context has credentials".
• bk-cli auth status still returns ok: truewhen "there are no credentials"; you need to check whether data.has_credentials is true。
• bk-cli auth check is more suitable for scripts and CI; when the target context has no credentials, it returns ok: false、error.code: no_credentials, and ends with exit code 1.
• If you need to temporarily override the authentication header automatically generated by the CLI, you can explicitly pass --header 'X-Bkapi-Authorization:<json>'; dry-run / verbose will still apply masking for display.

Relationship with system-specific Skills

• bk-cli-api supplements URL construction for raw API calls,--query、--path and output parsing details.
• A system-specific skill only supplements that system's own command semantics, business fields, and examples.
• This skill is only responsible for shared usage rules, common input conventions, and troubleshooting entry points; it does not explain how commands are implemented in the repository.
• If you are extending commands, maintaining skills, or modifying the shared request contract, please switch to AGENTS.md and docs/design.md。

API debugging reference (api-debug)

• When the user already has the API Gateway's HTTP status,code_name, error message, or needs to quickly determine whether the error is returned by the gateway or by the backend, continue reading references/api-debug.md。
• This reference document is organized by status -> message/code_name -> 原因 -> 处理 , suitable for an agent to first do quick localization, then supplement with contextual explanation.
• Prefer to use it to handle common gateway errors such as 400, 403, 404, 429, 499, 502, 504, 508; if the response body does not conform to the gateway error protocol, also first look at its "how to determine whether it is returned by the gateway".

Suggested troubleshooting order

1. First run bk-cli doctor --offline to confirm the local context, current selection, credential summary, and URL template rendering result.
2. If you need to confirm gateway connectivity, then run bk-cli doctor。
3. Then confirm whether the stage, tenant, timeout, header/body, TLS certificate inputs conform to the shared rules.
4. Then use --dry-run to see whether the final request construction is as expected.
5. If there are still issues, then look at the system-specific skill or --verbose output to localize to the specific command or API level.