CLI

Preview

@verbumia/cli

A small, scriptable CLI for everything you'd otherwise click through the dashboard: bootstrap a project, push and pull translations, gate CI on remote drift, peek at the missing-key queue. MIT-licensed, distributed via npm and Homebrew.

Preview · CLI は開発中です。コマンドや設定は 1.0 までに変わる可能性があります — ページ末尾の予定された変更を参照してください。9 つのコマンドとその引数は V1 で確定済みですが、wire フォーマットは変わる可能性があります。

Install

Requires Node 20 LTS or newer. Two binaries get installed: verbumia and the shorter alias vrb — interchangeable.

ターミナル Tap は V1 公開予定

1# 1 度だけグローバルにインストール — bin "verbumia" と短いエイリアス "vrb"2npm i -g @verbumia/cli 4# またはインストールせずに使う5npx @verbumia/cli@latest <command> 7# Homebrew tap は V1 ローンチ時に公開8brew install verbumia/tap/verbumia-cli

認証

ダッシュボードの Org Settings → API Keys → Create から API キーを取得します(シークレットは 1 度だけ表示されるので、vrb_live_<prefix>.<secret> 全体をコピー)。status / pull / missing / projects には project:read、push には project:write スコープを使ってください。

対話

1verbumia login2? Org Settings → API Keys からの API キーを貼り付けてください(入力はマスクされます):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ GET /v1/auth/me で検証 — marc@example.com (org: acme)。5✓ ~/.verbumia/credentials に保存(chmod 600)。

CI / 非対話

1# CI / 非対話 — env はファイルに勝つが、--token には負ける2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

ソースの優先順位は --token フラグ → VERBUMIA_TOKEN env → ~/.verbumia/credentials です。credentials ファイルは {"default":"<token>","<host>":"<token>"} の形式の JSON で、同じマシン上で prod / staging / セルフホストインスタンスごとに別々のキーを保持できます。

プロジェクトを設定

リポジトリで verbumia init を実行するとルートに verbumia.config.json が生成されます。手動でも書けますし、verbumia.config.{ts,js,toml,yml} も自動検出されます。

verbumia.config.json

1// verbumia.config.json — プロジェクトのルート2// 自動検出: verbumia.config.{ts,js,toml,yml}3{4  "project_uuid": "<project_uuid>",5  "source_language": "en",6  "locales": ["en", "fr-CA", "es", "ja"],7  "namespaces": ["common", "checkout"],8  "format": "json-i18next",9  "push": {10    "source_dir": "./src/locales",11    "file_pattern": "{locale}/{namespace}.json",12    "on_missing_namespace": "create"13  },14  "pull": {15    "dest_dir": "./src/locales",16    "file_pattern": "{locale}/{namespace}.json",17    "format": "json-i18next"18  },19  "missing_handler": {20    "endpoint": "https://api.verbumia.ca/v1/missing",21    "enabled_for_envs": ["dev", "staging"]22  }23}

フィールドリファレンス

フィールド	型	デフォルト / 注記
project_uuid	string	— required
source_language	string	"en"
locales	string[] \| null	null = all
namespaces	string[] \| null	null = all
format	string	"json-i18next" \| "xliff" \| "json-flat"
push.source_dir	string	"./src/locales"
push.file_pattern	string	"{locale}/{namespace}.json"
push.on_missing_namespace	"create" \| "error"	"create"
pull.*	object	mirrors push.* (read path)
missing_handler	object	{ endpoint, enabled_for_envs }

コマンド

すべてのコマンドは、デフォルト以外の設定ファイルを指す --config <path>、解決済み認証を上書きする --token <vrb_live_…>、機械可読な出力にする --json を受け付けます。

verbumia init 現在のディレクトリに verbumia.config.json を生成します。project_uuid、ソース言語、フォーマットを対話形式で設定します。

フラグ

--project <uuid> project_uuid を事前入力
--source-language <code> BCP-47(デフォルト "en")
--format <fmt> json | xliff

例

verbumia init --project <uuid>

verbumia login 対話形式で API キーを入力します。CLI は GET /v1/auth/me で検証し、~/.verbumia/credentials にモード 600 で書き込みます。

フラグ

--token <vrb_live_…> キーをインラインで渡す(プロンプトをスキップ。スクリプト用)

例

verbumia login

verbumia logout ~/.verbumia/credentials を消去します。サーバー側のキー失効は行いません — それはダッシュボードで実施してください。

フラグ

コマンド固有のフラグはありません。上記のグローバルフラグを使ってください。

例

verbumia logout

verbumia whoami アクティブキーの org、プロジェクト紐づけ、付与スコープを表示します。「アカウントが違う」系のサプライズをデバッグするのに便利です。

フラグ

コマンド固有のフラグはありません。上記のグローバルフラグを使ってください。

例

verbumia whoami

verbumia projects アクティブなキーがアクセスできるプロジェクトを一覧表示します。

フラグ

--json 機械可読な出力(デフォルトは TTY テーブル)

例

verbumia projects --json

verbumia status ローカルファイルとリモートプロジェクトの読み取り専用 diff — ロケールと namespace ごとに added / removed / changed。書き込みなし。

フラグ

--locale <code> 1 つのロケールに絞り込み
--namespace <slug> 1 つの namespace に絞り込み

例

verbumia status --locale fr-CA

verbumia push ローカルの i18n ファイルを Verbumia にアップロードします: 新規キーを作成し、変更値を更新し、参照されているがサーバーに存在しないキーは on-missing-key ポリシーに従って処理します。

フラグ

--locale <code> このロケールのみ push
--namespace <slug> この namespace のみ push
--dry-run 適用せずプランだけ表示
--on-missing-key <create|skip> ローカルファイルがサーバーに存在しないキーを参照しているときの挙動

例

verbumia push --dry-run

verbumia pull リモートの翻訳を、設定済みの pull.dest_dir にダウンロードします — ファイル単位で原子的。「export」パスとしても使えます。--format を渡すと出力時に変換できます。

フラグ

--locale <code> このロケールのみ pull
--namespace <slug> この namespace のみ pull
--format <fmt> json | xliff(この実行で config.format を上書き)

例

verbumia pull --format xliff

verbumia missing ランタイム SDK が捕捉した欠落キーイベントを一覧します。読み取り専用 — ダッシュボードを開かずにターミナルからトリアージするのに便利です。

フラグ

--locale <code> ロケールでフィルタ
--since <iso> この ISO-8601 タイムスタンプより新しいイベントのみ
--limit <n> 最大行数(デフォルト 20)

例

verbumia missing --locale ja --limit 50

別個の export コマンドはありません — pull --format でカバーします。Lokalise / Crowdin / Phrase からの import は、対応する backend エンドポイントが揃った V1 後に提供されます。当面は push.source_dir に JSON または XLIFF を置いて verbumia push を実行してください。

CI 連携

PR ごとに verbumia status --json を実行してください。ドリフト時の非ゼロ終了は「i18n に断りなくキーを出した人がいないか?」という安価なゲートになります。

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — リモートドリフトでビルドをゲート2name: i18n status3on: { pull_request: { branches: [main] } }4jobs:5  status:6    runs-on: ubuntu-latest7    steps:8      - uses: actions/checkout@v49      - uses: actions/setup-node@v410        with: { node-version: 20 }11      - run: npx -y @verbumia/cli status --json12        env:13          VERBUMIA_TOKEN: ${{ secrets.VERBUMIA_TOKEN }}

予定されている破壊的変更

透明性のために固定しています。それぞれは 1 リリース分の deprecation ウィンドウとともに minor リリースに乗ります — 最新の @verbumia/cli を使っていれば、破壊の前に警告が出ます。

V1.1 — config.format は { input, output } に分割され、push と pull が異なるフォーマットを使えるようになります。
V1.1 — push --on-missing-key は 2 値の enum ではなくポリシーオブジェクト(multi-case)になります。
V1.1 — フォーマット文字列 "json-flat" は命名一貫性のため "flat-json" にリネームされます。