bk-cli-shared

---
name: "bk-cli-shared"
description: "当任务涉及 bk-cli 的通用使用规则时使用，尤其是认证、context 切换、stage/timeout、header/body、tenant、dry-run、verbose，或当用户在 bk-cli api、apigateway、cmdb 与后续 system 之间拿不准该怎么发请求、为什么请求失败、哪些输入是共享行为时，都应先使用这个 skill。"
license: "MIT"
---

# bk-cli shared — 通用使用规则与排障入口

## 何时优先使用本 Skill

- 用户问的是认证、context、tenant、header、body、timeout、stage、dry-run、verbose 这类“所有系统都通用”的规则。
- 用户在排查请求失败，但问题还没明确落到某个具体系统命令上。
- 用户不确定应该先看系统专属 skill，还是先确认共享输入和运行时设置。
- 用户想先把“请求是怎么发出去的”看清楚，再决定要不要深入到某个系统命令。

## 推荐读取顺序

1. 先读本 skill，确认共享使用规则和排障顺序。
2. 再读系统专属 skill，补上具体命令、字段和示例。
3. 如果系统专属命令还没覆盖目标接口，再读 `bk-cli-api` 处理原始调用。

## 基础准备

```bash
# 初始化 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"
```

## 通用 Flags

| Flag | 适用范围 | 说明 |
|------|----------|------|
| `--context <name>` | 全局 | 单次命令覆盖当前激活的 BlueKing context |
| `--stage <stage>` | API Gateway 请求 | 网关 stage，默认 `prod`，常见值为 `testing` |
| `--dry-run` | 请求类命令 | 只预览请求，不发起网络请求 |
| `--verbose` | 请求类命令 | 将请求/响应细节打印到 stderr |
| `--insecure` | 请求类命令 | 跳过 HTTPS 证书校验，仅用于临时调试 |
| `--header 'Key:Value'` | 请求类命令，可重复 | 传入额外请求头；header name 和 value 会在本地校验 |
| `--body '<json>'` | 支持 body 的请求类命令 | 传入 JSON body，CLI 管理 `Content-Type: application/json` |
| `--timeout <duration>` | `bk-cli api` | 单次覆盖 context timeout，例如 `180s` |

## 多 Context 管理

context 表示一个独立的 BlueKing 部署目标，不是 API Gateway stage；`prod`、`testing` 这类环境阶段应通过 `--stage` 控制。

```bash
# 创建不同部署的 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
```

- 每个 context 都维护自己的一套凭据和默认项。
- `bk-cli auth login` 会把凭据写入当前 active context，或写入 `--context <name>` 指定的 context。
- 命令执行时 context 来源优先级是：显式 `--context`，当前 active context，本地已有 context 的 fallback。
- 显式指定不存在的 `--context` 会直接报错，不会静默回退。
- context 名称必须匹配 `^[a-z][a-z0-9-]*$`，例如 `default`、`clouds`、`prod-1`。
- tenant 是 context 的默认值；单次覆盖租户时使用 `--header 'X-Bk-Tenant-Id:<value>'`。

## 通用请求规则

- stdout 输出结构化 JSON envelope；CLI 级错误和 verbose 信息输出到 stderr。
- `--dry-run` 适合先确认 URL、query、body、headers 是否正确。
- `--verbose` 对请求类命令生效，请求/响应细节会输出到 stderr。
- `--insecure` 类似 `curl --insecure`，只影响真实 HTTPS 请求；临时调试自签名证书或测试环境时再使用。
- `--header` 必须包含 `:`，且 header name 不能为空；非法 header 不会进入网络请求阶段。
- `--header` 可以显式覆盖 `X-Bkapi-Authorization` 与 `X-Bk-Tenant-Id`。
- 传入 `--body` 时仍不能手动覆盖 `Content-Type`，该 header 由 CLI 管理。
- dry-run / verbose 会对 `X-Bkapi-Authorization` 做脱敏显示，即使该 header 是调用方显式覆盖的。
- 路径占位符值会被当作单个 URL path segment 转义，不能依赖它注入 `/`、`?` 等路径结构。

## 超时规则

- 每个 context 都有默认 `timeout`，未设置时为 `60s`。
- `bk-cli api` 默认使用当前 context 的 timeout；显式传 `--timeout <duration>` 时，本次请求优先使用该值。
- 某些系统命令可能会在自己的帮助信息或系统专属 skill 中说明额外的超时行为；遇到这类命令时，以该命令帮助和系统 skill 为准。

## 认证与登录

多数情况下，你不需要关心 CLI 内部如何组装认证头，只需要确保目标 context 已经登录到匹配的身份。

当前 bk-cli 公开支持三种登录形态：

- `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`

排查认证问题时，优先记住下面几点：

- `bk-cli auth status` 适合做“当前 context 有没有凭据”的检查。
- `bk-cli auth status` 在“没有凭据”时仍返回 `ok: true`，要看 `data.has_credentials` 是否为 `true`。
- `bk-cli auth check` 更适合脚本和 CI；目标 context 没有凭据时，会返回 `ok: false`、`error.code: no_credentials`，并以 exit code 1 结束。
- 如果你需要临时覆盖 CLI 自动生成的认证头，可以显式传 `--header 'X-Bkapi-Authorization:<json>'`；dry-run / verbose 仍会做脱敏显示。

## 与系统专属 Skill 的关系

- `bk-cli-api` 补充原始 API 调用的 URL 构造、`--query`、`--path` 和输出解析细节。
- 系统专属 skill 只补充该系统自己的命令语义、业务字段和示例。
- 本 skill 只负责共享使用规则、公共输入约定和排障入口，不解释命令是如何在仓库里实现出来的。
- 如果你是在扩展命令、维护 skill，或修改共享请求契约，请切换到 `AGENTS.md` 和 `docs/design.md`。

## API 调试参考（api-debug）

- 当用户已经拿到 API Gateway 的 HTTP status、`code_name`、错误消息，或需要快速判断错误是网关返回还是后端返回时，继续读取 `references/api-debug.md`。
- 该参考文档按 `status -> message/code_name -> 原因 -> 处理` 组织，适合 agent 先做快速定位，再补充上下文说明。
- 优先用它处理 400、403、404、429、499、502、504、508 这类常见网关错误；如果响应体不符合网关错误协议，也要先看它里面的“如何判断是不是网关返回”。

## 排障顺序建议

1. 先确认 context 是否正确，凭据是否写在目标 context 里。
2. 再确认 stage、tenant、timeout、header/body、TLS 证书输入是否符合共享规则。
3. 然后用 `--dry-run` 看最终请求构造是否符合预期。
4. 仍有问题时再看系统专属 skill 或 `--verbose` 输出，定位到具体命令或接口层面。