# ArkCLI 快速入门

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

Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，通过自然语言触发模型调用、推理接入点管理、内容生成与用量账单查询等操作。

<span id="c7a9421d"></span>
# 快速开始

**环境要求：** Node.js >= 16

<span id="f0b3c5a2"></span>
## 1. 安装并登录 Ark CLI

**选项：手动安装并登录**

### 安装 Ark CLI

在终端执行以下命令：
```Bash
# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli

# 2. 验证安装
arkcli --version
```

### 登录 Ark CLI

```Bash
# 登录方式 1：火山 SSO 浏览器登录 (推荐)
arkcli auth login volc-sso


# 登录方式 2：火山 SSO 无浏览器登录 / 远程终端登录
arkcli auth login --no-browser


# 查看登录状态
arkcli auth status

# 装 skill 到你常用的 AI Agent (Claude Code / Cursor / TRAE / Gemini CLI 等)
arkcli +connect
```

**选项：通过 AI Agent 安装并登录**

将下方提示词复制给 AI Agent（Claude Code、Codex、Cursor、TRAE 等），它会自动完成安装。

````Plaintext
根据下面命令帮我安装 Ark CLI：https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/intro/volc.md
````

> **注意**
>
> 如果需要卸载 Skill, 在终端执行命令：`arkcli +connect uninstall`

<span id="9b84d0ce"></span>
## 2. 使用 Ark CLI

配置完成后，重启 AI Agent 即可开始使用。可以直接在 AI Agent 用自然语言说出你的需求，可参考以下示例。

| 你想做什么 | 在 AI Agent 发送 |
|-|-|
| 查询模型 | 帮我看下 doubao / seedream 相关模型   |
| 查询用量 | 看下这个账号今天 / 这周用了多少 token |
| 查询账单 | 帮我查一下最近账单和费用明细 |
| 查询套餐 | 看下当前 Agent Plan / Coding Plan 套餐和 seat 情况 |
| 换 API key | 帮我给测试 profile 换一个可用 key |
| 文本对话 |  用 doubao 模型回答一句：北京今天适合带伞吗  |
| 图片理解 | 帮我描述这张图片里有什么 |
| 文档理解 | 帮我抽取这个 PDF 的重点信息 |
| 生成图片 | 生成一张柴犬在樱花树下奔跑的图片 |
| 生成视频 | 生成一段 5 秒猫跳跃的视频 |
| 验证图片或视频来源 | 帮我验证这张图片是否是 Seedream 生成的: https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/ark-gen.jpeg |
| 部署 Endpoint | 帮我部署一个测试 Endpoint，并告诉我怎么调用 |
 | 生成代码 | 给我一段 Python 调 seed 2.0 的代码 | 
| 清理资源 | 把刚才创建的测试 Endpoint / gen task / chat response 清理掉 |

在 Claude Code 中使用 Ark CLI 的示例如下：
[视频](https://arkdocs.tos-cn-beijing.volces.com/videos/CodingPlan/arkcli.mov)

<span id="7d9e2c41"></span>
# 核心能力

| 领域 | 能力说明 | 命令入口 |
|-|-|-|
| 认证与身份 | 支持登录方舟平台、查看认证状态、查看当前身份、生成与切换 API Key、多 Profile 切换与管理等。 | `arkcli auth`、`arkcli profile` |
| 对话与推理 | 多模态对话、多轮对话、流式输出、思考相关参数调节等。 | `arkcli +chat` |
| 图片/视频生成 | 文生图、图生图、文生视频、图生视频、参考素材生成等。 | `arkcli +gen` |
| 多模态理解 | 支持对图片、文档、视频、音频等输入进行理解。 | `arkcli +understand` |
| 模型发现 | 支持基础模型查询、模型搜索、模型详情、可用参数、可用资源查看等。 | `arkcli models` |
| 推理资源与部署 | 支持创建推理接入点、查询、更新、启动、停止等能力，提供基于指定模型快速部署推理接入点。 | `arkcli infer`、`arkcli +deploy` |
| 模型精调 | 支持创建与管理精调任务，覆盖 SFT、LoRA、DPO 及 RL 训练流程；提供数据校验、超参与费用预览，支持产物导出部署等。 | `arkcli train` |
| Managed Agents | 管理 ARK Managed Agents，包括 Agent / Skill / Env / Session / File / Memory Store / Vault / MCP OAuth。 | `arkcli agent`|
| 文档检索 | 支持检索方舟文档、按 URL 获取方舟文档内容、分页列出文档页面等。 | `arkcli docs` |
| 用量统计 | 支持查询推理用量、免费额度或资源包余额、订阅套餐用量、分模型用量明细和团队席位用量。 | `arkcli usage` |
| 账单与定价 | 支持查询Ark分账账单明细，并按账期、接入点、API Key 或产品维度拆账；支持查询模型价格与套餐价格。 | `arkcli billing`、`arkcli pricing` |
| 套餐与席位 | 支持查询、购买和续费 Agent Plan / Coding Plan，查看套餐支持的模型，并管理个人或团队套餐。 | `arkcli plans` |
| Agent 集成与接入 | 支持自动检测本机 AI Agent，并安装、查看或卸载 Ark CLI skills；提供多语言代码示例等。 | `arkcli +connect`、`arkcli +code-example` |
| 诊断 | 统一诊断入口，覆盖业务侧诊断(账号、模型、接入点)，验证图片与视频产物的来源特征。 | `arkcli doctor` |

<span id="d1a4f3b8"></span>
# 命令语法参考

Ark CLI 遵循以下命令结构：

```Bash
# 快捷命令
arkcli +<shortcut> [flags]

# 领域命令
arkcli <domain> <resource> <verb> [flags]

# 领域快捷命令
arkcli <domain> +<shortcut> [flags]

# 原始 API 调用
arkcli api <registered-action> --params '{...}'

```

使用 `--help` 查看任意命令的详细用法：

```Bash
arkcli --help
arkcli +chat --help
arkcli models search --help
arkcli train finetune create --help

```

<span id="2a6f8b13"></span>
## 全局标志

| Flag | 说明 |
|-|-|
| `--api-key <key>` | 覆盖默认的 API Key |
| `--base-url <url>` | 自定义数据面 API Base URL |
| `--debug` | 输出请求/响应调试信息 |
| `--dry-run` | 预览模式，仅展示请求元信息，不实际执行 |
| `--page-all` | 自动拉取所有分页数据 |
| `--page-delay` | 翻页时的延迟，默认 200 毫秒。 |
| `--page-limit <n>` | 配合 `--page-all` 使用，限制最大拉取页数（默认 10） |
| `--profile <name>` | 指定使用的 Profile |
| `--project-name <name>` | 覆盖当前 Project |
| `--format json` | 输出格式指定为 JSON（默认） |
| `--region <region>` | 覆盖当前 Region |
| `--transform <path>` | 使用 GJSON 表达式对输出做数据处理 |