# 身份与配置

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

身份与配置：登录认证、本地配置、无交互引导，以及贯穿所有命令的 Profile 身份切面。

- `auth` 管 SSO 登录/登出与 ARK API Key；`config` 管本地 profile 配置与 `update.mode` 策略；
- `profile` 是 `type × region × project × owner_trn × api_keys` 五元组身份切面，是所有命令的配置中心来源；
- `resources` 只读，把 Endpoint 解析为权威模型与模态，是 Skills 与 API Explorer 的校准基线。

<span id="domain-auth"></span>
## auth

认证与凭证管理：SSO 登录、查看登录状态、退出登录、生成/重选 ARK API Key。

- `auth login` 是交互式入口；无浏览器环境用 `--no-browser` 两段式（先取 URL，再回贴 base64 code）；
- `auth login volc-sso` 是火山引擎 SSO 通道（0.1.16 起 SSO 登录自动绑定 profile 切面）；
- 凭证存储位置是实现细节，业务代码一律通过 profile 的 `cfg.APIKey` 读取，不要直接访问存储。

<span id="auth-apikey-command"></span>
### auth apikey

获取并配置 ARK API Key

```Bash
arkcli auth apikey
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--key-id` | int64 | 指定要选择的 API Key ID（非交互模式用） |

<span id="auth-apikey-create-command"></span>
### auth apikey create

创建并保存一把普通 ARK API Key

```Bash
arkcli auth apikey create
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过确认提示（非交互模式） |

<span id="auth-login-command"></span>
### auth login

登录火山方舟平台（火山引擎）

```Bash
arkcli auth login
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--code` | string | 无浏览器 Phase 2：把浏览器显示的 base64 授权码喂回以完成登录（agent/沙箱用） |
| `--credential-store` | string | Broker verifier 存储后端：encrypted-file（默认，不访问 keyring）或 keyring（不可用时直接失败） |
| `--login-mode` | string | 登录模式：auto（新链路失败时按错误类型降级）、legacy（仅旧链路）、broker（仅新链路） |
| `--no-browser` | bool | 无浏览器模式：在任意设备完成 SSO 登录后手动粘贴授权码 |

<span id="auth-login-volc-sso-command"></span>
### auth login volc-sso

通过火山引擎 SSO 登录

```Bash
arkcli auth login volc-sso
```

<span id="auth-logout-command"></span>
### auth logout

清除已保存的登录凭证

```Bash
arkcli auth logout
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--reset-service-account` | bool | （保留） |

<span id="auth-status-command"></span>
### auth status

查看当前登录状态

```Bash
arkcli auth status
```

<span id="auth-whoami-command"></span>
### auth whoami

查看当前已认证的身份

```Bash
arkcli auth whoami
```

<span id="domain-config"></span>
## config

本地配置管理入口。profile 创建、查看、切换与删除已迁移到 `profile` 域。

- 保留能力：`config reset`（清整个本地状态，破坏性）、`config set update.mode automatic|disabled`（更新策略）、`config lang`；
- profile 归因、历史 yaml 排障等场景见 `profile` 域。

<span id="config-lang-get-command"></span>
### config lang get

打印当前生效的持久化 UI 语言

```Bash
arkcli config lang get
```

<span id="config-lang-set-command"></span>
### config lang set

持久化全局 UI 语言

```Bash
arkcli config lang set <locale>
```

<span id="config-lang-unset-command"></span>
### config lang unset

清除持久化的 UI 语言，改用构建默认值

```Bash
arkcli config lang unset
```

<span id="config-reset-command"></span>
### config reset

删除所有本地配置文件

```Bash
arkcli config reset
```

<span id="config-set-command"></span>
### config set

设置允许修改的全局配置项

```Bash
arkcli config set <key> <value>
```

<span id="domain-profile"></span>
## profile

Profile 是 arkcli 在控制面与数据面之间的**统一身份切面**：`type × region × project × owner_trn × api_keys` 五元组绑成一组，作为所有命令执行的配置中心来源。

- 常用操作：列出/查看/新建/切换/删除/重命名，管理 profile 内 API Key 列表与各类默认资源；
- `profile project` 登录后重选 active project：project 相关 profile 重新派生，个人版 plan profile 原样保留，全程不换身份、不重登；
- 首登 project 选择器含「账号全部资源」合成项（默认），表示不设定 ProjectName、按账号全量。

<span id="profile-apikey-get-command"></span>
### profile apikey get

打印某个 profile 的默认 API Key 明文（机器可读）

```Bash
arkcli profile apikey get
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--plain` | bool | 只打印 key 本身，不带 JSON 外层结构 |

<span id="profile-create-command"></span>
### profile create

新建 profile（交互式或行内参数）

```Bash
arkcli profile create
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--name` | string | Profile 名称（默认：{type}_{region}_{project}） |
| `--type` | string | Profile 类型：platform \| agent-plan \| coding-plan \| agent-plan-team \| coding-plan-team |
| `--region` | string | 地域（默认：cn-beijing） |
| `--project` | string | 项目名称（默认：default） |
| `--default-api-key` | string | 要绑定的默认 API Key（可选） |
| `--owner-trn` | string | Owner TRN（可选；自愈场景通常留空） |
| `--plan-tier` | string | [仅套餐类型] 强制指定 PlanTier（agent-plan：small\|medium\|large\|max；coding-plan：lite\|pro）；跳过 ListSubscribeTrade 的自动探测 |
| `--set-default` | bool | 创建后把该 profile 设为默认 |
| `--no-interactive` | bool | 跳过交互提示；缺少必填字段时立即失败 |

<span id="profile-delete-command"></span>
### profile delete

删除 profile（非交互场景需用 --yes 确认）

```Bash
arkcli profile delete <profile>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认（适合内联执行） |

<span id="profile-apikey-list-command"></span>
### profile apikey list

列出当前或指定 profile 中的 API Key（脱敏）

```Bash
arkcli profile apikey list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |

<span id="profile-apikey-refresh-command"></span>
### profile apikey refresh

从控制面重新拉取 API Key 列表并更新 profile

```Bash
arkcli profile apikey refresh
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |

<span id="profile-apikey-use-command"></span>
### profile apikey use

按 1 起始的序号（来自 `apikey list`）或完整 Key 设置默认 API Key

```Bash
arkcli profile apikey use <index|api-key>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |

<span id="profile-list-command"></span>
### profile list

列出全部 profile（标记出当前生效的）

```Bash
arkcli profile list
```

<span id="profile-models-list-command"></span>
### profile models list

查看各模态的 PlanTier 与默认 Resources

```Bash
arkcli profile models list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |

<span id="profile-models-refresh-command"></span>
### profile models refresh

重新拉取文本模型列表，并更新 Resources.Text.Default（取第一个）

```Bash
arkcli profile models refresh
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |

<span id="profile-project-command"></span>
### profile project

重新选择生效 project；会删除旧的 platform profile，并为新 project 新建一个

```Bash
arkcli profile project [<project-name>]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--yes` | bool | 跳过交互确认（适合内联执行） |

<span id="profile-rename-command"></span>
### profile rename

设置 profile 的显示名（可含中文与空格）

```Bash
arkcli profile rename <profile> --to <display-name>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--to` | string（必填） | 展示名称（可含中文/空格；空字符串表示清除标签） |

<span id="profile-set-default-command"></span>
### profile set-default

为当前生效 profile 的某个模态设置默认资源 ID

```Bash
arkcli profile set-default <id>
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--modality` | string | 模态：text \| image \| video |
| `--skip-verify` | bool | 跳过内联校验（绕过控制面可用性检查） |

<span id="profile-show-command"></span>
### profile show

查看 profile 详情（密钥脱敏，含推导出的 base_url）

```Bash
arkcli profile show [profile]
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（位置参数的替代写法） |

<span id="profile-use-command"></span>
### profile use

切换后续所有命令使用的生效 profile

```Bash
arkcli profile use [profile]
```

<span id="domain-resources"></span>
## resources

实时控制面资源查询：列出当前/指定 profile 可见资源及其调用兼容性，并把 Endpoint 解析为权威模型、模态与候选工作流。

- 只读，不写 profile.yaml；拿到临时 `ep-...` 不确定该走 chat/understand/gen 时，先在本域 resolve；
- 是 Skills 与 API Explorer 的校准基线：返回的模型绑定与模态信息即真实可调用的契约。

<span id="resources-list-command"></span>
### resources list

列出当前生效 profile 可用的资源（实时查询，不走缓存）

```Bash
arkcli resources list
```

| Flag | 类型 | 说明 |
| --- | --- | --- |
| `--profile` | string | Profile 名称（默认：当前激活 profile） |
| `--modality` | string | 模态：text \| image \| video |

<span id="resources-resolve-command"></span>
### resources resolve

把 Endpoint 解析为它绑定的模型、模态、API 与候选工作流

```Bash
arkcli resources resolve <endpoint-id>
```