CLI

v0.2.1 · npm · MIT

@verbumia/cli

أداة CLI صغيرة وقابلة للأتمتة لكل ما كنت ستفعله بالنقر داخل لوحة التحكم: تهيئة مشروع، push وpull للترجمات، حجب الـ CI عند انجراف عن الـ remote، وإلقاء نظرة على طابور المفاتيح الناقصة. ترخيص 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>

المصادقة

احصل على مفتاح API من Org Settings → API Keys → Create في لوحة التحكم (يُعرض السر مرة واحدة فقط؛ انسخ السلسلة الكاملة vrb_live_<prefix>.<secret>). استخدم النطاق project:read لـ status / pull / missing / projects، والنطاق project:write لـ push.

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.

اضبط مشروعك

شغّل 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_…> لتجاوز المصادقة المحلولة، و--json لإخراج قابل للقراءة آلياً.

Auth & setup

verbumia login إدخال تفاعلي لمفتاح API. يتحقق الـ CLI من المفتاح عبر GET /v1/auth/me ثم يكتبه في ~/.verbumia/credentials بنمط 600.

الرايات

--host <url> API host to authenticate against.
--token <key> مرّر المفتاح inline (يتجاوز السؤال؛ مفيد للسكربتات)

مثال

verbumia login --host https://api.verbumia.dev

verbumia logout يمسح ~/.verbumia/credentials. لا يلغي المفتاح من جهة الخادم — لذلك استخدم لوحة التحكم.

الرايات

لا توجد رايات خاصة بهذا الأمر. استخدم الرايات العامة الموصوفة أعلاه.

مثال

verbumia logout

verbumia whoami يطبع org المفتاح النشط، وارتباطه بالمشروع، والنطاقات الممنوحة. طريقة سريعة لتشخيص مفاجآت «الحساب الخطأ».

الرايات

لا توجد رايات خاصة بهذا الأمر. استخدم الرايات العامة الموصوفة أعلاه.

مثال

verbumia whoami

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

مثال

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

Inspect

verbumia projects list يدرج المشاريع التي يستطيع المفتاح النشط الوصول إليها.

الرايات

لا توجد رايات خاصة بهذا الأمر. استخدم الرايات العامة الموصوفة أعلاه.

مثال

verbumia projects list

verbumia keys list List keys as namespace_slug/key_name.

الرايات

--namespace <slug> Restrict to one namespace.

مثال

verbumia keys list --namespace common

verbumia status diff للقراءة فقط بين الملفات المحلية والمشروع البعيد — added / removed / changed لكل لغة وnamespace. بدون كتابة.

الرايات

--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 في الـ runtime. للقراءة فقط — مفيد للتصنيف من الطرفية دون فتح لوحة التحكم.

الرايات

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

الرايات

--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: ينشئ مفاتيح جديدة، يحدّث القيم المتغيّرة، ويتصرف وفق سياسة on-missing-key حين يُشار إلى مفتاح غير موجود في الخادم.

الرايات

--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 للتحويل عند الإخراج.

الرايات

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

الرايات

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

الرايات

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

الرايات

--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 مع نافذة deprecation بطول إصدار واحد — ابقَ على أحدث @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.