Ark CLI 是火山方舟平台官方命令行工具，支持在本地终端快速完成认证与资源管理，并可将能力安装到常用 AI Agent 中，通过自然语言触发模型调用、推理接入点管理、内容生成与用量账单查询等操作。
快速开始#
环境要求： Node.js >= 16
1. 安装并登录 Ark CLI#
安装 Ark CLI#
在终端执行以下命令：
# 1. 通过 NPM 安装
npm install -g @volcengine/ark-cli
# 2. 验证安装
arkcli --version
登录 Ark CLI#
# 登录方式 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（Claude Code、Codex、Cursor、TRAE 等），它会自动完成安装。
根据下面命令帮我安装 Ark CLI：https://lf3-static.bytednsdoc.com/obj/eden-cn/psjryh/ljhwZthlaukjlkulzlp/intro/volc.md
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 的示例如下：
核心能力#
| 领域 | 能力说明 | 命令入口 |
|---|---|---|
| 认证与身份 | 支持登录方舟平台、查看认证状态、查看当前身份、生成与切换 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 |
命令语法参考#
Ark CLI 遵循以下命令结构：
# 快捷命令
arkcli +<shortcut> [flags]
# 领域命令
arkcli <domain> <resource> <verb> [flags]
# 领域快捷命令
arkcli <domain> +<shortcut> [flags]
# 原始 API 调用
arkcli api <registered-action> --params '{...}'
使用 --help 查看任意命令的详细用法：
arkcli --help
arkcli +chat --help
arkcli models search --help
arkcli train finetune create --help
全局标志#
| 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 表达式对输出做数据处理 |