vefaas: Volcengine FaaS CLI
vefaas is the command-line tool for Volcengine Function Service (veFaaS). It enables serverless application deployment, function management, and configuration through a streamlined workflow.
Installation
CODEBLOCK0
Note: The domain volces.com is Volcengine (ByteDance cloud). This tarball is the official distribution channel for the CLI — not published to npm registry. Install method matches the front matter metadata.install spec.
Verify installation:
CODEBLOCK1
Tip: vefaas -v (or vefaas --version) will print the current version and, if a newer release is available, show instructions on how to update. When a user encounters unsupported features or wants to check for updates, run this command first.
Core Workflow
The typical deployment pattern:
- 1. Check Node.js:
node --version (requires >= 18, recommended 20+)
- If version is too low, switch using nvm (
nvm use 20) or fnm (
fnm use 20), or manually install a newer version
- 2. Check CLI:
vefaas --version to verify installation
- 3. Authenticate (try in order, stop at first success):
a. Auto-check (preferred): vefaas login --check — the CLI auto-detects available credentials (Ark Skill, injected tokens, etc.). If this passes, proceed to step 4.
b. SSO: vefaas login --sso — if browser is available.
c. AK/SK: vefaas login --accessKey <AK> --secretKey <SK> — last resort, prompt user.
- 4. Pre-flight check (MUST do before every deploy): INLINECODE11
- framework / language correct → don't touch start command or build settings
- port wrong → fix in code (e.g., process.env.PORT || 3000), or override via --port at deploy time
- Check dependency files: ensure package.json (Node.js) or requirements.txt (Python) lists all runtime deps — the server only installs what's declared, not what's globally installed locally
- 5. Deploy:
CODEBLOCK2
If you need to override specific parameters that inspect got wrong (port, build command, start command, etc.), pass them directly at deploy time:
CODEBLOCK3
- 6. Access:
vefaas domains to view URLs
Quick Commands
| Purpose | Command |
|---|
| Check version / update | INLINECODE21 (shows version and update instructions if available) |
| Check auth |
vefaas login --check (preferred, auto-detects credentials) |
| Login (SSO) |
vefaas login --sso (opens browser, auto-completes) |
| Login (AK/SK) |
vefaas login --accessKey <AK> --secretKey <SK> (last resort) |
| Init from template |
vefaas init --template <n> |
| Inspect project |
vefaas inspect (
run before deploy to verify detection) |
| Deploy new app |
vefaas deploy --newApp <n> --gatewayName $(vefaas run listgateways --first) --yes |
| Deploy existing |
vefaas deploy --app <n> --yes |
| List gateways |
vefaas run listgateways --first |
| View URLs |
vefaas domains |
| Set env var |
vefaas env set KEY VALUE |
| View config |
vefaas config list |
| Pull code |
vefaas pull --func <n> |
Global Options
| Option | Description |
|---|
| INLINECODE34 | Enable debug mode for troubleshooting |
| INLINECODE35 |
Non-interactive mode (required for CI/AI coding) |
|
--region | Region override (e.g., cn-beijing) |
Cookbooks
Step-by-step guides for common scenarios:
References
Detailed documentation on specific topics:
Security
- - Declared credentials only: This skill uses
VOLC_ACCESS_KEY_ID and VOLC_SECRET_ACCESS_KEY as declared in the front matter. The agent should not read or probe for any other env vars, .env files, or credential files. - Debug output:
vefaas --debug may print request/response payloads that contain tokens or secrets. Do not log, store, or surface debug output to the user unless they explicitly request troubleshooting. When sharing debug output, redact any values that look like keys, tokens, or secrets.
Important Notes
- - Always use
--yes for non-interactive mode in CI/CD and AI coding scenarios - Use
$(vefaas run listgateways --first) to get an available gateway - Config is stored in
.vefaas/config.json after linking - Use
--debug or -d to troubleshoot issues (see Security section for caveats) - Auth: always start with
vefaas login --check — the CLI auto-detects available credentials - Always run
vefaas inspect before every deploy — check framework/language detection, port, and dependency files (package.json / requirements.txt). Fix issues before deploying, not after - When a feature is unsupported or you suspect the CLI is outdated, run
vefaas -v to check version and see update instructions
vefaas: 火山引擎函数服务命令行工具
vefaas 是火山引擎函数服务（veFaaS）的命令行工具。它通过简化的工作流程实现无服务器应用部署、函数管理和配置。
安装
bash
npm i -g https://vefaas-cli.tos-cn-beijing.volces.com/volcengine-vefaas-latest.tgz
注意：域名 volces.com 属于火山引擎（字节跳动云）。此压缩包是该命令行工具的官方分发渠道——未发布到 npm 注册表。安装方法符合前置元数据 metadata.install 规范。
验证安装：
bash
vefaas --version
提示：vefaas -v（或 vefaas --version）将打印当前版本，如果有新版本可用，还会显示更新说明。当用户遇到不支持的功能或想检查更新时，请先运行此命令。
核心工作流程
典型的部署模式：
- 1. 检查 Node.js：node --version（需要 >= 18，推荐 20+）
- 如果版本过低，使用 nvm（nvm use 20）或 fnm（fnm use 20）切换，或手动安装新版本
- 2. 检查命令行工具：vefaas --version 验证安装
- 3. 身份验证（按顺序尝试，首次成功即停止）：
a. 自动检查（推荐）：vefaas login --check — 命令行工具自动检测可用凭证（Ark Skill、注入的令牌等）。如果通过，进入步骤 4。
b. 单点登录：vefaas login --sso — 如果浏览器可用。
c. 访问密钥/秘密密钥：vefaas login --accessKey --secretKey — 最后手段，提示用户。
- 4. 预检检查（每次部署前必须执行）：vefaas inspect
- framework / language 正确 → 不要修改启动命令或构建设置
- port 错误 → 在代码中修复（例如 process.env.PORT || 3000），或在部署时通过 --port 覆盖
- 检查依赖文件：确保 package.json（Node.js）或 requirements.txt（Python）列出了所有运行时依赖项——服务器只安装声明的依赖，而不是本地全局安装的内容
- 5. 部署：
bash
# 新应用
vefaas deploy --newApp
--gatewayName $(vefaas run listgateways --first) --yes
# 已有应用
vefaas deploy --app --yes
如果需要覆盖 inspect 检测错误的特定参数（端口、构建命令、启动命令等），在部署时直接传入：
bash
vefaas deploy \
--newApp my-app \
--gatewayName $(vefaas run listgateways --first) \
--buildCommand npm run build \
--outputPath dist \
--command node dist/index.js \
--port 3000 \
--yes
- 6. 访问：vefaas domains 查看 URL
快速命令
| 用途 | 命令 |
|---|
| 检查版本/更新 | vefaas -v（显示版本，如有更新说明） |
| 检查身份验证 |
vefaas login --check （推荐，自动检测凭证） |
| 登录（单点登录） | vefaas login --sso（打开浏览器，自动完成） |
| 登录（访问密钥/秘密密钥） | vefaas login --accessKey --secretKey （最后手段） |
| 从模板初始化 | vefaas init --template |
| 检查项目 | vefaas inspect（部署前运行以验证检测） |
| 部署新应用 | vefaas deploy --newApp --gatewayName $(vefaas run listgateways --first) --yes |
| 部署已有应用 | vefaas deploy --app --yes |
| 列出网关 | vefaas run listgateways --first |
| 查看 URL | vefaas domains |
| 设置环境变量 | vefaas env set KEY VALUE |
| 查看配置 | vefaas config list |
| 拉取代码 | vefaas pull --func |
全局选项
| 选项 | 描述 |
|---|
| -d, --debug | 启用调试模式以排查问题 |
| --yes |
非交互模式（CI/AI 编码必需） |
| --region | 区域覆盖（例如 cn-beijing） |
操作指南
常见场景的分步指南：
参考文档
特定主题的详细文档：
- - 配置 — 配置文件和设置
- 框架检测 — 支持的框架和自动检测
- 故障排除 — 调试模式、常见问题和解决方案
安全
- - 仅使用声明的凭证：此技能仅使用前置元数据中声明的 VOLCACCESSKEYID 和 VOLCSECRETACCESSKEY。智能体不应读取或探测任何其他环境变量、.env 文件或凭证文件。
- 调试输出：vefaas --debug 可能打印包含令牌或机密的请求/响应负载。除非用户明确请求故障排除，否则不要记录、存储或向用户显示调试输出。共享调试输出时，请对任何看起来像密钥、令牌或机密的值进行脱敏处理。
重要说明
- - 在 CI/CD 和 AI 编码场景中始终使用 --yes 启用非交互模式
- 使用 $(vefaas run listgateways --first) 获取可用网关
- 链接后配置存储在 .vefaas/config.json 中
- 使用 --debug 或 -d 排查问题（参见安全部分的注意事项）
- 身份验证：始终从 vefaas login --check 开始——命令行工具会自动检测可用凭证
- 每次部署前务必运行 vefaas inspect——检查框架/语言检测、端口和依赖文件（package.json / requirements.txt）。在部署前修复问题，而不是部署后
- 当某个功能不受支持或怀疑命令行工具已过时时，运行 vefaas -v 检查版本并查看更新说明
