跳到主要内容
Verbumia
免费开始

CLI

v0.2.1 · npm · MIT

@verbumia/cli

一个小巧、可脚本化的 CLI,涵盖你原本要在 dashboard 里点击完成的事情:初始化项目、push/pull 翻译、在 CI 里阻断远端漂移、查看缺失键队列。MIT 许可,通过 npm 与 Homebrew 分发。

Breaking · 0.1 → 0.2

The whole CLI now runs on the MCP surface, so it needs an API key with the mcp:* scope — project-scoped keys return 403. Generate one in the dashboard under Org Settings → API Keys and re-issue any key you used with 0.1.

安装

需要 Node 20 LTS 或更新版本。会装两个二进制:verbumia 和较短别名 vrb — 可互换。

terminal 
1# 全局安装一次 — bin "verbumia" 加上更短别名 "vrb"2npm i -g @verbumia/cli 4# 或者无需安装直接使用5npx @verbumia/cli <command>

认证

在 dashboard 的 Org Settings → API Keys → Create 取一把 API key(secret 只显示一次,请复制完整 vrb_live_<prefix>.<secret>)。给 status / pull / missing / projects 用 project:read scope,给 push 用 project:write。

terminal 
1# interactive — stores the key per host in ~/.verbumia/credentials (0600)2verbumia login --host https://api.verbumia.dev3API key: vrb_live_••••••••.••••••••••••••••4✓ saved for https://api.verbumia.dev 6# CI — no prompt, key read from the environment7export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>8verbumia push

Resolution order, first wins: the VERBUMIA_TOKEN environment variable, then ~/.verbumia/credentials for the active host. Mint the key under Org Settings → API Keys with the mcp:* scope.

配置你的项目

在 repo 中运行 verbumia init,会在根目录生成 verbumia.config.json,也可以手写。CLI 还会自动检测 verbumia.config.{ts,js,toml,yml}(如果你偏好这些格式)。

verbumia.config.json 
1# committed to your repo — no secrets here2{3  "host": "https://api.verbumia.dev",4  "project_uuid": "<project_uuid>",5  "version_slug": "main"6}
~/.verbumia/credentials 
1# ~/.verbumia/credentials — mode 0600, per user, never commit2{ "default": "https://api.verbumia.dev",3  "hosts": {4    "https://api.verbumia.dev": { "api_key": "vrb_live_..." }5  } }

version_slug defaults to main. Keep the API key out of verbumia.config.json — it belongs in the credentials file or VERBUMIA_TOKEN only.

命令

每个命令都接受 --config <path> 指向非默认配置文件、--token <vrb_live_…> 覆盖已解析的 auth、以及 --json 输出机器可读结果。

Auth & setup

verbumia login 交互式输入 API key。CLI 通过 GET /v1/auth/me 校验,然后以 mode 600 写入 ~/.verbumia/credentials。

Flags

  • --host <url> API host to authenticate against.
  • --token <key> 内联传入 key(跳过提示;适合脚本)

示例

verbumia login --host https://api.verbumia.dev
verbumia logout 清除 ~/.verbumia/credentials。不会在服务端撤销 key — 那需要在 dashboard 里操作。

Flags

无命令特定 flag。请使用上面描述的全局 flag。

示例

verbumia logout
verbumia whoami 打印当前 key 的 org、项目绑定与已授予的 scope。快速排查“账号不对”这类意外。

Flags

无命令特定 flag。请使用上面描述的全局 flag。

示例

verbumia whoami
verbumia init 在当前目录生成 verbumia.config.json,通过交互式问询设置 project_uuid、源语言与格式。

Flags

  • --project <uuid> 预填 project_uuid
  • --version <slug> Version slug to target (defaults to main).
  • --force Overwrite an existing config file.

示例

verbumia init --project <uuid> --version main

Inspect

verbumia projects list 列出当前 key 可访问的项目。

Flags

无命令特定 flag。请使用上面描述的全局 flag。

示例

verbumia projects list
verbumia keys list List keys as namespace_slug/key_name.

Flags

  • --namespace <slug> Restrict to one namespace.

示例

verbumia keys list --namespace common
verbumia status 本地文件与远端项目的只读 diff — 按 locale 与 namespace 列出 added / removed / changed。无写入。

Flags

  • --language <code> Limit the diff to one language.
  • --namespace <slug> Limit the diff to one namespace.
  • --src <dir> Source directory (defaults to locales).

示例

verbumia status
verbumia missing 列出运行时 SDK 捕获的待处理缺失键事件。只读 — 适合不打开 dashboard 直接在终端做 triage。

Flags

  • --language <code> Filter by language.
  • --namespace <slug> Filter by namespace.
  • --limit <n> 最大行数(默认 20)

示例

verbumia missing --limit 50

Import & sync

verbumia import <files...> One-shot i18next import — nested or flat; creates keys, upserts translations, idempotent.

Flags

  • --dry-run Preview only; sends nothing.
  • --status <draft|translated> Incoming status (default translated).
  • --language <code> Force the language instead of inferring it from the path.
  • --namespace <slug> Force the namespace (required for a bare <lang>.json).
  • --version <slug> Target a non-default version.

示例

verbumia import locales/fr/common.json
verbumia push 把本地 i18n 文件上传到 Verbumia:创建新 key、更新已变更的值,并按 on-missing-key 策略处理本地引用但服务端缺失的 key。

Flags

  • --src <dir> Source directory (defaults to locales).
  • --dry-run Preview only; sends nothing.
  • --status <state> Incoming status (default translated).

示例

verbumia push --dry-run
verbumia pull 把远端翻译下载到配置的 pull.dest_dir — 按文件原子写入。也兼任你的“export”路径:传入 --format 在导出时转换格式。

Flags

  • --language <code> Limit to one language.
  • --namespace <slug> Limit to one namespace.
  • --dest <dir> Destination directory (defaults to locales).

示例

verbumia pull --language fr
verbumia export Export as i18next JSON — flat by default, --nested for trees.

Flags

  • --nested Emit nested trees instead of flat keys.
  • --out <dir> Write files to a directory instead of stdout.

示例

verbumia export --nested --out ./dump
verbumia releases publish Trigger a CDN release; subscribed SDKs refresh live.

Flags

  • --version <slug> Version to publish (defaults to main).
  • --dry-run Preview only; publishes nothing.

示例

verbumia releases publish
verbumia snapshot Fetch the public CDN bundles into a build-time module for offline-first SDK fallback.

Flags

  • --format <ts|json> Output format: ts (default) or json.
  • --out <file> Write to a file instead of stdout.
  • --cdn <base> CDN base (defaults to https://cdn.verbumia.ca).

示例

verbumia snapshot --out src/verbumia-bundles.ts

Every command also accepts --host <url> to override the configured API host for a single run.

已知即将的破坏性变更

为透明性钉住。每项都会随一次 minor 发布到来,带一个 release 周期的 deprecation 窗口 — 跑在最新的 @verbumia/cli,你会在破坏前看到警告。

接下来

快速上手
React + i18next
接入运行时 SDK 并捕获缺失键。
MCP
配置 Claude Desktop
用你的 AI agent 驱动同一个项目。
Guide
Update source values
Change a key's source text after it exists.