arkcli-config
arkcli 本地配置管理。处理 profile 配置归因、update.mode 的 automatic/disabled 策略、config reset 与历史 yaml 排障;profile 类操作优先使用 arkcli profile <subcmd>。
arkcli config
⚠️ 0.1.16 起命令树迁移:arkcli config init/list/show/switch/delete 已标记 deprecated,请改用 arkcli profile create/list/show/use/delete(行为一致 + 新增 profile 切面字段 type/project/owner_trn/available_api_keys)。arkcli config reset 保留(清整个本地状态,超出单 profile)。0.2.x 删除全部已 deprecated 子命令。
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md,其中包含认证闸门、命令选择顺序与共享安全规则
CRITICAL — 配置类写操作前必须确认用户意图。profile show/list/keys list 可能同步远端 Key 并回写本地库存或默认 Key,不能当作无配置副作用的准入探测。
唤起信号(When To Trigger)
- 用户提到:
profile、base-url、api-key覆盖混乱,或仍在使用已删除的全局--region/--project-name - 用户现象:同一条业务命令“打到了错误环境/错误 base URL/错误账号”,怀疑是配置来源不一致
- 用户目标:初始化/更新 profile、切换默认 profile、重置本地配置文件
- 用户目标:启用、关闭或恢复 arkcli 的自动更新/更新提示策略
反唤起信号(When NOT To Trigger)
- 用户要解决的是“未登录/401/鉴权失败/没有权限”:先走
arkcli auth status,必要时转../arkcli-auth/SKILL.md - 用户目标是业务功能(models/+chat/+gen/+deploy/usage 等):不要停留在 config,排除配置后回到原任务
适用场景
- 初始化或更新 profile
- 查看当前解析后的配置
- 切换默认 profile
- 删除单个 profile 或重置整个本地配置
- 排查为什么业务命令连到了错误环境、错误账号或错误 base URL
Agent 快速执行顺序
- 先遵守 shared 的认证及宿主边界。普通 CLI 的当前身份/Profile 诊断用
arkcli auth status --format json、arkcli auth whoami --format json;宿主禁止额外认证探测时,使用宿主已给的上下文,不自行探测。 - Chat/Gen 的默认模型和路由用
arkcli resources list --modality <text|image|video> --format json,按 Resources Skill 区分发现、兼容性和真实调用验证。仅查看默认模型不等于授权发送收费请求。 - 切换默认 profile:
arkcli profile use <name> - 创建 profile:
arkcli profile create --type=...(详见 arkcli-profile 子树,本 skill 不重复) arkcli config reset是破坏性操作(清整个本地配置文件),必须确认用户意图- 更新策略只使用 allowlist 命令:
arkcli config set update.mode automatic|disabled - 用户明确需要 Profile 详情、清单或 Key 管理时才考虑
arkcli profile show/arkcli profile list;执行前说明可能同步并回写 Key。用户要求“不改配置/Key”时不执行它们,也不改用旧config show/list绕过限制。
配置归因(优先级)
arkcli 的解析优先级(从高到低):
- Profile 选择:
--profileflag >ARK_PROFILE环境变量 >config.yaml的default_profile> 第一个type=platform的 profile >"default"sentinel - API Key:
--api-key>ARK_API_KEY> profile > 同 identity store > 产品.env兼容值 - Base URL:
--base-url>ARK_BASE_URL> profile 自定义值 > 按 Profile 的 Region/Type 派生 > 默认值 - Region/Project: 由所选 Profile 持有;
ARK_REGION/ARK_PROJECT_NAME不再覆盖运行时
--api-key/--base-url 仅供数据面命令使用。无 Profile 时必须成对提供;覆盖 Base URL 时也必须显式提供 API Key。控制面/本地命令显式收到这两个 flag 会 fail-fast。
排障时要明确”是谁覆盖了谁”,不要直接猜测。
0.1.16 修正:
--profile现在优先于ARK_PROFILE(对齐 CLI 行业惯例 flag > env > config)。0.1.15 及更早版本是 env > flag,与本规则相反。
证据与结论
说明本轮实际检查了什么、哪些来源覆盖仍未验证,不要求复述固定评测词句。auth whoami 的 Profile 字段是持久切面摘要,不能据此声称临时 API Key/Base URL override 已验证或数据面调用一定成功。缺少证据时明确保留未知,不为补字段执行可能回写配置的命令。路径展示使用 $HOME/...,不读取凭证文件。
核心规则
- 本 skill 负责解释“为什么命令打到了错误环境/错误账号/错误 base URL”,并兼容历史
config init/list/show/switch/delete命令排障语义 - 常规准入沿
auth status/whoami→resources,不把 Profile 管理命令当无副作用查询 - profile 写操作(create / use / set-default / delete)走
arkcli profile子树 arkcli config reset负责全量清理;arkcli config set update.mode <mode>只写更新策略。不要用它写任意 YAML 路径。
Guard Checklist(必做)
- 只读意图:不执行可能回写 Key 的
profile show/list/keys list;脱敏不等于无副作用,命令名为 show/list 也不等于只读 - 写操作确认:
profile use/delete与config reset执行前必须复述影响范围并征得确认 - 全量清理提醒:
arkcli config reset删除config.yaml/config.json,不会清理$HOME/.arkcli/.env(token)或 identity store;要清理凭证请用arkcli auth logout
与其他 skill 的串联
- profile 创建 / 切换 / 资源 default 设置 / API Key 管理 → 转
arkcli-profile(推荐)或继续看本 skill 的兼容映射 - 业务命令失败且怀疑是
--profile、--base-url、API Key 来源或 Profile 的 Region/Project 不一致时,先转到这里 - 配置问题排除后,再回到原始业务 skill 继续
- 配置仍无法解释问题时,再考虑转
../arkcli-auth/SKILL.md或../arkcli-api-explorer/SKILL.md
命令一览
| 命令 | 说明 | 状态 |
|---|---|---|
arkcli config reset | 删除整个本地配置文件(保留) | ✅ 活跃 |
arkcli config set update.mode automatic | 显式为当前 exact install 启用 automatic;从非 latest 版本恢复时先安装 latest 再执行 | ✅ 活跃 |
arkcli config set update.mode disabled | 关闭静默自动安装,保留隐式版本检查、更新提示和手工 update | ✅ 活跃 |
arkcli profile show [--profile <name>] | 查看 Profile;可能同步并回写 Key | ✅ Profile 管理,替代 config show |
arkcli profile list | 列出 Profile;可能同步并回写各 Profile 的 Key | ✅ Profile 管理,替代 config list |
arkcli profile use <name> | 切换默认 profile | ✅ 替代 config switch |
arkcli profile delete <name> | 删除单个 profile | ✅ 替代 config delete |
arkcli profile create --type=... | 创建 profile(替代旧 config init) | ✅ 替代 config init |
arkcli config init/list/show/switch/delete | 旧子命令,0.2.x 移除 | ⚠️ deprecated |
公开模式只有 automatic 和 disabled。disabled 保留隐式版本检查和更新提示,但绝不静默安装;显式 arkcli update 和 arkcli update --check 也始终可用。缺失 update.mode 和历史配置中的 notify 对外都按 disabled 处理,历史配置中的 notify 继续按 disabled 兼容读取,但不得再建议用户设置 notify。
Windows、macOS、Linux 的 fail-closed transaction 与六个产品/平台生产 gate 均已开启。stable 全局 npm postinstall 会将安装后版本与 registry 当前 latest 比较:非 latest 持久化 disabled;当前 latest 不改 mode,已有 automatic 时为新 exact install 换发授权。postinstall 不立即执行版本替换。
新安装 enrollment
只有能证明“此前没有产品状态目录”且安装版本等于 registry latest 的 stable 全局 npm 新安装,才默认写入 automatic 并创建绑定当前 exact install 的惰性 pending evidence:
- 第一次成功的、符合安全条件的人工业务命令在一个策略事务中完成 pending → grace → active。
- 重新检查确认 exact-install consent 已 active 后,该 invocation 即可调度 automatic patch 更新。
由 npm postinstall 启动的全部 CLI 进程(包括其中的 +connect)以及用户手工执行的 +connect 都不消耗 enrollment、不做隐式版本检查,也不调度 automatic。AI Skill、CI、非 TTY、Client Preview、config、update 和内部维护命令同样不消耗 enrollment,也不调度 automatic。更新成功后,下一次成功的人工业务命令只在 stderr 显示一次 旧版本 -> 新版本 结果,不修改 stdout 或业务退出码。
当前生产 automatic 按明确产品策略关闭 24/48/72 小时与 10%/50%/100% cohort admission;原 rollout 实现与回归测试仍保留,在线 Probe 仍要求两次独立观测。普通 automatic 仍须满足 exact consent、实时 registry target/SRI/tarball 校验、reservation、退避和全部 staged-apply 安全边界。
每次 npm 重装都不得沿用旧 exact-install receipt。若安装版本等于当前 latest,不改既有 mode:automatic 换发新 receipt,disabled / 历史 notify 仍保持关闭。若安装版本不等于 latest,持久化 disabled。registry 失败时不改 mode、不发新 receipt;--ignore-scripts 也不会完成对齐。从非 latest 版本恢复时,先安装 latest,再明确执行 arkcli config set update.mode automatic。长期锁定版本使用:
arkcli config set update.mode disabled
npm i @volcengine/ark-cli@<exact-version> -g --registry https://registry.npmjs.org
为避免 registry 不可用时的不确定,需要确定锁版时仍建议先执行 arkcli config set update.mode disabled 再安装精确版本。disabled 位于 $HOME/.arkcli/config.yaml,安装 @latest 也不会自动改回 automatic。arkcli config reset 会尽力撤销 exact consent 后再清配置。npm 解析 @latest 与 postinstall 查询之间恰好发新版时,存在极小概率误判为非 latest 的竞态。
参考
- Downloads
- Security audit
- Pass
- Last updated
- 2d ago
- Current version
- v1.0.0
- License
- MIT-0
