@volcengine/las-cli
v0.9.0
Published
LAS CLI (Go) - npm wrapper that installs platform binaries
Maintainers
Keywords
Readme
LAS CLI (Go)
这是将原 Node/TS 版本(dp/console: las-cli-v1.5.5)迁移到 独立 Go 仓库后的实现版本;当前 npm 包名为 @volcengine/las-cli。
本 README 面向 CLI 使用者(人类用户 + AI Agent)。如果你是要本地构建源码、改代码、参与发布或维护 CHANGELOG/打 tag,请直接看 CONTRIBUTING.md。
特性
auth:OAuth 登录与登录态管理(login/logout/status);登录后 CLI 会自动注入临时 STS 凭证用于tos直连,无需手动配置 AK/SKapi-key:在 OAuth 登录态下管理 LAS API Key(list/create/get/use)。运行算子相关命令时若未配置 API Key,CLI 会自动列出账号下可用 Key 让你选择,菜单末尾还提供「+ 创建新的 API Key」入口;账号下没有 Key 时则直接引导创建并用于本次命令;可用api-key use [api-key]主动切换当前生效的 Key(不带参数走交互菜单,带参数直接写入指定明文)operators:列出/查看/调用 LAS operators(支持 sync/async + 等待轮询)task:异步任务管理(list/status/wait/kill/clear)task create:基于las_seed_2_0的自然语言编排(后台执行,任务落盘,可 status 查看)tos:TOS 文件操作(upload/download/ls/presign)price:算子价格预估(信息不足时展示单价档位)inspect:探测媒体/PDF 基本信息(供price自动补齐参数)doc:通过文档 MCP 搜索和读取 LAS 官方文档(search/fetch,默认使用公网服务)配置文件:默认
~/.las-cli/config.json(目录权限 0700,文件权限 0600)- 可通过
LAS_CLI_CONFIG_DIR覆盖配置目录
- 可通过
支持无落盘配置(flags/env 覆盖,优先级:flag > env > config):
- flags(按命令生效,详见
--help):--api-key:覆盖las.apiKey--tos-bucket:覆盖tos.bucket--region:覆盖volcengine.region
- env:
LAS_API_KEY:覆盖las.apiKeyVOLCENGINE_REGION:覆盖volcengine.regionTOS_BUCKET:覆盖tos.bucketVOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY/VOLCENGINE_SESSION_TOKEN:用于las-cli tos直连 TOS
- TOS endpoint 将根据
volcengine.region自动拼接为tos-<region>.volces.com,无需通过环境变量或配置项手动设置。
- flags(按命令生效,详见
输出契约:默认 stdout 输出 JSON envelope,stderr 输出结构化错误 envelope
安装与快速开始
环境要求
- Node.js(npm/npx):用于 npm 安装与 Skills 安装
- git:从仓库安装 Skills 时需要
想从源码构建(需要 Go 1.22+)?请参考 CONTRIBUTING.md。
快速开始(人类用户)
Note for AI assistants: 如果你是 AI Agent 正在协助用户,请优先阅读“快速开始(AI Agent)”小节。
1) 安装
以下两种方式任选其一:
- npm 安装(推荐):
npm i -g @volcengine/las-cli
las-cli --version- 二进制安装脚本(适用于不走 npm 的环境):使用仓库
scripts/install-cli.sh/scripts/install-cli.ps1,可通过LAS_CLI_DOWNLOAD_PATH指定下载前缀;详见 CONTRIBUTING.md → 发布与分发。
2) 配置
v0.4.1 起推荐先执行一次
las-cli auth login完成 OAuth 登录:登录后 CLI 会自动注入临时 STS 凭证用于tos直连,且在调用算子时若未配置 LAS API Key,会自动列出账号下可用 Key 让你选择(菜单末尾还提供「+ 创建新的 API Key」入口),账号下没有 Key 时直接引导创建并用于本次命令——通常不再需要手工导出LAS_API_KEY/ AK/SK。
# 推荐:OAuth 登录(一次即可,登录态会持久化到系统 keychain,不可用时回退到 ~/.las-cli/auth.json)
las-cli auth login
# SSH / 容器 / 无浏览器环境改用跨设备模式:浏览器登录后从授权页复制授权码粘贴回终端
las-cli auth login --remote
las-cli auth status
# 主动管理 API Key(可选;首次调用算子时也会自动引导)
las-cli api-key list
las-cli api-key create --name my-key
# 切换当前 las.apiKey:不带参数走交互菜单,含「+ 创建新的 API Key」入口;带参数则直接写入指定明文
las-cli api-key use
las-cli api-key use sk-xxxxxxxxxxxxxxxx如需脱机使用或在 CI 环境运行,可改用环境变量/命令参数注入(避免写入磁盘):
# 直接使用 las-cli 时,注入已有的 LAS_API_KEY
export LAS_API_KEY="<las-api-key>"
export VOLCENGINE_REGION="cn-beijing" # 可选,覆盖 volcengine.region;仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)若你在 Arkclaw/OpenClaw 环境中运行 skill,平台会自动提供所需身份,通常无需手工配置额外认证环境变量。
如需持久化,可执行:
las-cli init
# 或:las-cli config init3) 第一次调用
las-cli operators list --format table
las-cli operators help las_asr_pro
# 按 help 提示准备 params.json 后调用
las-cli operators call las_asr_pro --params-file ./params.json
# 可选:指定调用方来源(默认 cli):--caller cli|api|skill
# 例如:
# las-cli operators call las_asr_pro --caller skill --params-file ./params.json(可选)如果你要使用 las-cli tos ...:
export VOLCENGINE_ACCESS_KEY="<ak>"
export VOLCENGINE_SECRET_KEY="<sk>"
export VOLCENGINE_SESSION_TOKEN="<session-token>" # 可选
export VOLCENGINE_REGION="cn-beijing" # 可选,覆盖 volcengine.region;仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)
export TOS_BUCKET="tos://<bucket>" # 可选,覆盖 tos.bucket(用于补全 <tos_key> 或 1 参数上传回退直连)快速开始(AI Agent)
目标:在不落盘 secrets的前提下,让 Agent 能稳定调用 las-cli 并解析结构化输出。
# 1) 安装 CLI(推荐 npm wrapper)
npm i -g @volcengine/las-cli
# 2) 安装 Agent Skills(推荐,让 Agent 具备可发现的工具描述)
# 默认走 SSH;若 agent 环境不支持 SSH clone,可改用 https 仓库地址
npx skills add [email protected]:dp/las-cli.git -g -y
# 3) 注入必要凭证(任选其一)
# - 若在 Arkclaw/OpenClaw 环境中运行 skill,平台会自动提供身份
# - 在交互式开发机上:执行 `las-cli auth login` 完成 OAuth 登录(v0.4.1 推荐);
# SSH / 容器 / 无浏览器环境改用 `las-cli auth login --remote`(手动粘贴授权码);
# 登录后 STS / API Key 会自动注入,无需再 export 任何 secrets
# - 在 CI / 无浏览器环境:继续注入 LAS_API_KEY
export LAS_API_KEY="<las-api-key>"
# 4) 验证可用性
las-cli --version
las-cli operators list如需执行 las-cli tos ...,同样推荐通过 env 注入 VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY / VOLCENGINE_SESSION_TOKEN(可选),并按需使用 VOLCENGINE_REGION / TOS_BUCKET 覆盖配置(TOS endpoint 会根据 volcengine.region 自动拼接为 tos-<region>.volces.com,无需手动配置)。
Skill 认证约定:在 Arkclaw/OpenClaw 环境中,las-cli 会优先使用平台自动提供的身份发起 Operator/File API 调用;仅在未提供该身份时才回退到 LAS_API_KEY / las.apiKey。
认证流程图见 docs/skill-tip-auth-flow.md。
建议 Agent 调用规范:优先用 --params-file 传参,默认输出为 JSON envelope(stdout 是数据,stderr 是错误/提示),避免使用 --format table 破坏可机读性。
Agent Skills 安装(给 AI Agent 使用)
仅允许 skill + script 接入的平台可使用新增的 skills-script/:
44 个 skill 均带 -script 后缀,可与原版并存。每个目录包含完整的 Python 脚本、
算子参数和价格快照;复制单个目录到目标 agent 的 skills 目录即可,运行时需要 Python 3.9+,
无需安装 las-cli、Go、npm 或 Python 第三方包。目标平台仍须允许 Python 执行及接口网络访问。
脚本版包含跨设备 OAuth/PKCE 登录、STS 刷新、API Key 选择/创建、文件上传下载、
同步/异步调用、状态查询与等待,以及离线价格预估。宿主可注入 VE_TIP_TOKEN 或
LAS_API_KEY;登录状态独立保存在 ~/.las-skills/,不读取原 CLI 配置。
授权链接、Key 选择和完整调用示例见各目录的 SKILL.md。
媒体探测中的 WAV 时长无需其他依赖;其他音视频和 PDF 可使用宿主已有的
ffprobe / pdfinfo,未安装时需显式补充计费用量。缺少价格配置或用量时不编造金额。
脚本版基于 skills-common 的完整算子集合生成,统一支持平台注入身份和用户授权,
不另复制 arkclaw / ida 的安装与登录指令差异。
维护时修改 scripts/skill_runtime/,然后运行 make build-script-skills 同步独立包。
业务说明来自 skills-common,算子与价格快照来自 internal/core。
make test-script-skills 检查包同步、独立运行、协议和计价回归;make test 已包含此检查。
这些测试不访问生产接口;真实授权、实际上传与付费算子仍需目标平台联调验证。
下面是原 CLI 版的安装方式:
前置:先安装
las-cli(至少选一种方式)
- npm(推荐):
npm i -g @volcengine/las-cli- 源码:在仓库根目录执行
make build,然后使用./bin/las-cli
安装 skills(参考 larksuite/cli 的做法,skills 与 CLI 解耦):
# 安装本仓库内的 skills
npx skills add [email protected]:dp/las-cli.git -g -y说明:如果 agent 环境不支持 SSH clone,可改用 https 仓库地址;更多参数请执行
npx skills --help。
1) 初始化
las-cli init
# 或者:
las-cli config init
las-cli config show
las-cli config show --format table
# 直接写入配置项(key 支持:volcengine.region / volcengine.accessKey / volcengine.secretKey / volcengine.sessionToken / las.apiKey / tos.bucket)
las-cli config set volcengine.region cn-beijing # 仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州)
# 清空所有本地配置(需要二次确认)
las-cli config clear
# 或跳过确认:
las-cli config clear -yBytePlus(Johor)数据面
BytePlus 不从 auth login 推断路由。调用算子时显式选择平台和地域,并由运行环境安全注入 LAS API Key:
export LAS_PLATFORM=byteplus
export LAS_REGION=ap-southeast-1
export LAS_API_KEY='<injected-by-host>'
las-cli operators call las_asr --platform byteplus --region ap-southeast-1 \
--params-file ./params.json这会调用 operator.las.ap-southeast-1.bytepluses.com。BytePlus TOS 使用 tos-ap-southeast-1.bytepluses.com,另需 BYTEPLUS_ACCESS_KEY 和 BYTEPLUS_SECRET_KEY(或 tos --ak/--sk);LAS_API_KEY 不能用于 TOS。api-key 和 price 当前仅支持 Volcengine,BytePlus 请在控制台处理。
2) 调用算子
las-cli operators list
las-cli operators list --format table
las-cli operators help las_asr_pro
las-cli operators help las_seed_2_0
# 推荐:用 params file
las-cli operators call las_asr_pro --params-file ./params.json
# 可选:指定调用方来源(默认 cli):--caller cli|api|skill
# 例如:
# las-cli operators call las_asr_pro --caller skill --params-file ./params.json
# 兼容旧版:直接传 --param(仅识别当前算子的参数定义)
las-cli operators call las_audio_convert --input_path tos://xx/a.wav --output_path tos://xx/b.wav跳过本地鉴权检查(沙箱/宿主身份场景)
显式传入全局参数 --skip-auth-check 后,算子调用、查询和等待跳过本地凭据检查、Key 校验、自动登录及依赖登录态的在线参数查询;缺少 API Key 时也会发送请求。已有的宿主 token 或 API Key 仍会沿用,没有凭据时不附加 Authorization 头,实际鉴权由服务端处理。
las-cli operators call las_storyboard_rewrite --skip-auth-check --caller skill --no-wait --params-file ./params.json
las-cli operators status <task_id> --operator las_storyboard_rewrite --skip-auth-check --caller skill
las-cli operators wait <task_id> --operator las_storyboard_rewrite --skip-auth-check --caller skill
las-cli tos upload ./input.mp4 --skip-auth-check --platform volcengine该选项默认关闭,只影响本次命令,不写入配置;后续查询也需显式传入。火山单参数上传在此模式下直接使用 File API,不要求 AK/SK 或桶配置。显式指定目标对象的直连 TOS、批量命令的 TOS 列举和结果写入仍需要原有签名及访问配置;该选项不跳过业务参数、路径和地域校验,也不改变服务端的 401/403 等响应。
3) 异步任务
las-cli task list
las-cli task list --format table
las-cli task status <task_id> --operator las_asr_pro
las-cli task wait <task_id> --operator las_asr_pro
las-cli task kill <task_id>文档搜索与读取
doc 是文档 MCP 的只读适配层,不执行 Skill 或调用模型,不需要 LAS API Key。默认连接公网 MCP:https://topic.bytedance.com/mcp/las-volc。
las-cli doc search "语音识别"
# 使用搜索结果中的 24 位文档 ID,不要传入 URL
las-cli doc fetch <id>
# 当正文末尾 PAGE_INFO 的 has_more=true 时,使用返回的 next_line_offset 继续读取
las-cli doc fetch <id> --line-offset 200 --line-limit 200stdout 使用 { ok, data, meta } JSON envelope。data 完整保留 MCP 工具结果:搜索结果在 data.content 的 text 项中,以 JSON 数组字符串返回,包含 ID、标题、摘要/高亮和分数;正文 text 项包含来源 URL 和 <<<PAGE_INFO ...>>> 分页标记。搜索摘要只用于定位,请读取相关正文后再回答,不要把第一页当作全文。CLI 不改写排序、正文或分页标记。
可用 --mcp-url <url> 或环境变量 LAS_DOC_MCP_URL 覆盖服务地址,优先级为 flag > env > 默认公网地址。--timeout 默认为 60 秒,覆盖初始化及工具调用;发生错误时返回 stderr 结构化错误并非零退出,不自动重试。请求使用 las-cli/<version> User-Agent,不转发 LAS API Key 或 OAuth 凭据。适配 HTTP JSON/SSE 响应,不支持 stdio 或旧式独立 SSE 端点。
4) TOS 文件操作
las-cli tos check <link> 检查链接是否为 TOS 地址,默认返回 JSON envelope,data 包含 link、is_tos、kind、bucket、key。可用 --format pretty|table 展示结果:
las-cli tos check "https://bucket.tos-cn-beijing.volces.com/path/file?x=1" --format prettyv0.4.1 起推荐先执行一次
las-cli auth login:登录后 CLI 会自动用账号 STS 发起 TOS 直连(presign / upload / download / ls 全部可用),可直接跳过下方"方式 A1) 直连 TOS(AK/SK)"。仅在 CI / 无浏览器场景或需要长期凭证时再回退到 AK/SK。
# 方式 A:通过环境变量配置(推荐,避免落盘)
## A1) 直连 TOS(AK/SK)
export VOLCENGINE_ACCESS_KEY="<ak>"
export VOLCENGINE_SECRET_KEY="<sk>"
export VOLCENGINE_SESSION_TOKEN="<session-token>" # 可选
# region / bucket 统一从配置读取
# - region: `las-cli config set volcengine.region cn-beijing`(仅支持 cn-beijing(华北2北京)/cn-shanghai(华东2上海)/cn-guangzhou(华南1广州))
# - bucket: `las-cli config set tos.bucket tos://<bucket>`
# 1 参数:若未配置 LAS_API_KEY,会自动回退为直连 TOS,并为你生成 object_key(默认 inputs/<timestamp>-<file>)
las-cli tos upload ./a.txt
# 2 参数:显式指定目标路径(只允许直连 TOS;必须 AK/SK)
las-cli tos upload ./a.txt tos://<bucket>/path/a.txt
las-cli tos ls tos://<bucket>/path/ --format table
las-cli tos presign get tos://<bucket>/path/a.txt --expires 3600
las-cli tos download tos://<bucket>/path/a.txt ./a.txt
## A2) File API(LAS_API_KEY)
# 1 参数:若配置了 LAS_API_KEY(或 config las.apiKey),会优先走 File API 上传,并返回 tos_url + presigned_url(24h)
export LAS_API_KEY="<las-api-key>"
las-cli tos upload ./a.txt
# 方式 B:通过配置文件(持久化)
las-cli config set volcengine.accessKey <ak>
las-cli config set volcengine.secretKey <sk>
las-cli config set volcengine.sessionToken <session-token> # 可选
las-cli config set tos.bucket tos://<bucket>
las-cli tos ls tos://<bucket>/5) 价格预估(price/inspect)
price 使用与 console 价格计算器一致的内置配置和计算公式,计价无需登录或联网;Volcengine 使用 CNY,BytePlus 使用 USD。配置随 CLI 发布更新,结果包含规则版本和配置 SHA-256。文件探测仍在 CLI 内完成;只有输入远端文件时需要下载/鉴权。
# 查看当前平台支持的算子,以及指定算子的字段、单位和模式 ID
las-cli price list
las-cli price las_video_super_resolution --describe --format pretty
# PDF 页数 / 视频输入信息
las-cli inspect pdf ./a.pdf --format pretty
las-cli inspect media ./a.mp4 --format pretty
# 兼容原有用量参数
las-cli price las_pdf_parse_doubao --pdf ./a.pdf --parse-mode detail --format pretty
las-cli price las_video_edit --media ./a.mp4 --mode simple --format pretty
# 转码分辨率是输出规格,必须显式指定;不再使用原视频分辨率代替
las-cli price las_video_resize --media ./a.mp4 --resolution 1080P --format pretty
# 字幕翻译:输入时长 × 识别单价 + 输入时长 × 语种数 × 翻译单价
las-cli price las_video_subtitle_translate --duration-seconds 600 \
--set subtitleSource=OCR_low --set targetLanguageCount=2 --format pretty
# 普通模式使用 --quantity(单位由 --describe 指明)
las-cli price las_voice_forge --quantity 333 --format pretty缺参时返回 computable=false、missing_fields、fields 和可选 modes,不猜测输出时长、输出帧率或 Token 用量。复杂字段通过重复的 --set key=value 传入,采用 console 表单字段名和单位;例如 inputTokens=1 表示 100 万 Tokens,而旧参数 --input-tokens 1000000 表示 100 万个原始 Tokens。
普通模式只预估所选计费项及固定费用;多个独立计费项需分别估算后相加。详细参数、兼容变化和配置更新方式见 价格计算器。
安装方式补充
npm 安装(推荐)
npm i -g @volcengine/las-cli
las-cli --version
las-cli --helpnpm 包会在 postinstall 阶段按平台从 CDN 下载二进制;命令入口为 scripts/run.js。
二进制安装脚本(不走 npm 的环境)
- macOS/Linux:
scripts/install-cli.sh - Windows:
scripts/install-cli.ps1
两者都会优先读取 LAS_CLI_DOWNLOAD_PATH(形如 https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>);若未设置则使用脚本内默认值。
# macOS/Linux
curl -fsSL https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>/install-cli.sh | bash
# Windows PowerShell
irm https://lf3-static.bytednsdoc.com/obj/<CDN_DIR>/install-cli.ps1 | iex各版本的更新点见 CHANGELOG.md;构建/发布/打 tag 等流程见 CONTRIBUTING.md。
