CLI

v0.2.1 · npm · MIT

@sonenta/cli

ダッシュボードでクリックする代わりに使える、小さくスクリプタブルな CLI: プロジェクトの bootstrap、翻訳の 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 以上が必要です。インストールされるのは 2 つのバイナリ: verbumia と短いエイリアス vrb — どちらでも使えます。

terminal

1# 1 度だけグローバルにインストール — bin "verbumia" と短いエイリアス "vrb"2npm i -g @sonenta/cli 4# またはインストールせずに使う5npx @sonenta/cli <command>

認証

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

terminal

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

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

プロジェクトを設定

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

sonenta.config.json

1# committed to your repo — no secrets here2{3  "host": "https://api.sonenta.com",4  "project_uuid": "<project_uuid>",5  "version_slug": "main"6}

~/.verbumia/credentials

1# ~/.verbumia/credentials — mode 0600, per user, never commit2{ "default": "https://api.sonenta.com",3  "hosts": {4    "https://api.sonenta.com": { "api_key": "vrb_live_..." }5  } }

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

コマンド

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

Auth & setup

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

フラグ

--host <url> API host to authenticate against.
--token <key> キーをインラインで渡す(プロンプトをスキップ。スクリプト用)

例

sonenta login --host https://api.sonenta.com

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

フラグ

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

例

sonenta logout

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

フラグ

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

例

sonenta whoami

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

フラグ

--project <uuid> project_uuid を事前入力
--version <slug> Version slug to target (defaults to main).
--force Overwrite an existing config file.

例

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

Inspect

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

フラグ

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

例

sonenta projects list

sonenta keys list List keys as namespace_slug/key_name.

フラグ

--namespace <slug> Restrict to one namespace.

例

sonenta keys list --namespace common

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

フラグ

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

例

sonenta status

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

フラグ

--language <code> Filter by language.
--namespace <slug> Filter by namespace.
--limit <n> 最大行数(デフォルト 20)

例

sonenta missing --limit 50

Import & sync

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

フラグ

--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.

例

sonenta import locales/fr/common.json

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

フラグ

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

例

sonenta push --dry-run

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

フラグ

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

例

sonenta pull --language fr

sonenta export Export as i18next JSON — flat by default, --nested for trees.

フラグ

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

例

sonenta export --nested --out ./dump

sonenta releases publish Trigger a CDN release; subscribed SDKs refresh live.

フラグ

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

例

sonenta releases publish

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

フラグ

--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.sonenta.com).

例

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

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

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

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

MCP surface + scope. The whole CLI moved from the project REST surface to the MCP surface. Re-issue your API key with the mcp:* scope — project-scoped keys now return 403.
push is one-shot. push now sends your entire locales/ tree in a single import call (it was create-key plus a PUT per translation). It is idempotent and prints created / updated / unchanged.
New commands. import, export, releases publish, snapshot and projects list are new in 0.2.0.