CLI

Preview

@verbumia/cli

Маленький скриптуемый CLI для всего, что ты иначе делал бы кликами в дашборде: bootstrap проекта, push и pull переводов, гейтинг CI на дрейф, просмотр очереди missing-keys. Лицензия MIT, поставка через npm и Homebrew.

Preview · CLI в разработке. Команды и конфиг могут поменяться до 1.0 — см. известные грядущие изменения внизу страницы. 9 команд и их аргументы зафиксированы для V1; wire-формат может ещё меняться.

Установка

Требуется Node 20 LTS или новее. Ставится два бинарника: verbumia и короткий алиас vrb — взаимозаменяемы.

терминал Tap публикуется в V1

1# поставить глобально один раз — bin "verbumia" плюс короткий алиас "vrb"2npm i -g @verbumia/cli 4# или использовать без установки5npx @verbumia/cli@latest <command> 7# Homebrew tap публикуется при запуске V18brew install verbumia/tap/verbumia-cli

Аутентификация

Получи API-ключ в Org Settings → API Keys → Create в дашборде (секрет показывается один раз; скопируй полный vrb_live_<prefix>.<secret>). Используй scope project:read для status / pull / missing / projects, project:write — для push.

интерактивно

1verbumia login2? Вставь API-ключ из Org Settings → API Keys (ввод скрыт):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Проверено через GET /v1/auth/me — marc@example.com (org: acme).5✓ Сохранено в ~/.verbumia/credentials (chmod 600).

CI / без интерактива

1# CI / без интерактива — env-переменная сильнее файла, но слабее --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

Приоритет источников: флаг --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. Файл credentials — это JSON вида {"default":"<token>","<host>":"<token>"}, чтобы держать отдельные ключи для prod / staging / self-hosted на одной машине.

Настрой проект

Запусти verbumia init в репо, чтобы создать verbumia.config.json в корне, или напиши вручную. CLI также автоопределяет 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, привязку к проекту и выданные scope'ы для активного ключа. Быстрый способ отладить сюрпризы вида «не тот аккаунт».

Флаги

Специфичных флагов нет. Используй глобальные флаги выше.

Пример

verbumia whoami

verbumia projects Список проектов, к которым у активного ключа есть доступ.

Флаги

--json машинно-читаемый вывод (по умолчанию TTY-таблица)

Пример

verbumia projects --json

verbumia status Только-чтение diff между локальными файлами и remote-проектом — added / removed / changed по локали и namespace. Без записи.

Флаги

--locale <code> сузить до одной локали
--namespace <slug> сузить до одного namespace

Пример

verbumia status --locale fr-CA

verbumia push Загружает локальные i18n-файлы в Verbumia: создаёт новые ключи, обновляет изменённые значения и решает по политике on-missing-key, когда ключ упомянут, но отсутствует на сервере.

Флаги

--locale <code> пушить только эту локаль
--namespace <slug> пушить только этот namespace
--dry-run показать план без применения
--on-missing-key <create|skip> что делать, когда локальный файл ссылается на ключ, отсутствующий на сервере

Пример

verbumia push --dry-run

verbumia pull Скачивает удалённые переводы в настроенный pull.dest_dir — атомарно по файлу. Заодно играет роль «export»: передай --format для конвертации на выходе.

Флаги

--locale <code> тянуть только эту локаль
--namespace <slug> тянуть только этот namespace
--format <fmt> json | xliff (перекрывает config.format для этого запуска)

Пример

verbumia pull --format xliff

verbumia missing Список накопленных событий missing-keys, собранных runtime SDK. Только чтение — удобно для триажа из терминала без открытия дашборда.

Флаги

--locale <code> фильтр по локали
--since <iso> только события новее этого ISO-8601 timestamp
--limit <n> максимум строк (по умолчанию 20)

Пример

verbumia missing --locale ja --limit 50

Отдельной команды export нет — её закрывает pull --format. import из Lokalise / Crowdin / Phrase появится после V1, как только подъедут соответствующие endpoints; пока кладёшь JSON или XLIFF в push.source_dir и запускаешь verbumia push.

Интеграция с CI

Запускай verbumia status --json на каждом PR. Ненулевой exit на дрейфе даёт дешёвый гейт «не зашипил ли кто-то ключ без ведома i18n?».

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — гейтить билд по дрейфу remote2name: 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 }}

Известные грядущие breaking changes

Зафиксированы для прозрачности. Каждое прилетит в minor-релизе с deprecation-окном на один релиз — сиди на свежем @verbumia/cli, и увидишь предупреждение до поломки.

V1.1 — config.format разделяется на { input, output }, чтобы push и pull могли использовать разные форматы.
V1.1 — push --on-missing-key становится policy-объектом (multi-case) вместо enum'а на 2 значения.
V1.1 — формат-строка "json-flat" переименована в "flat-json" ради консистентности именования.

Дальше

Быстрый старт

React + i18next

Подключить runtime SDK и захватывать пропущенные ключи.

MCP

Настрой Claude Desktop

Управляй тем же проектом из своего AI-агента.