Comvi CLI

The Comvi CLI (@comvi/cli) lets you manage translations from your terminal. Sync translation files, generate TypeScript types, and integrate Comvi into your build pipeline.

Installation

npm install -D @comvi/cli

Or install globally:

npm install -g @comvi/cli

Configuration

Create a .comvirc.json in your project root:

.comvirc.json

{
  "apiBaseUrl": "https://api.comvi.io",
  "outputPath": "src/types/i18n.d.ts",
  "strictParams": true,
  "defaultNsName": "default",
  "translationsPath": "./src/locales",
  "fileTemplate": "{languageTag}/{namespace}.json",
  "format": "json",
  "push": {
    "forceMode": "ask"
  },
  "pull": {
    "emptyDir": false
  }
}

Configuration Options

Option	Type	Required	Default	Description
apiKey	string	No	$COMVI_API_KEY	API key for authentication. Prefer the environment variable
apiBaseUrl	string	No	'https://api.comvi.io'	Comvi API base URL
outputPath	string	No	'src/types/i18n.d.ts'	Output file path for generated TypeScript types
strictParams	boolean	No	true	Require interpolation params in generated types
defaultNsName	string	No	'default'	Namespace whose keys are emitted without a prefix
translationsPath	string	No	'./src/locales'	Directory for local translation JSON files
fileTemplate	string	No	'{languageTag}/{namespace}.json'	File layout for pull/push
format	'json'	No	'json'	Translation file format
push.forceMode	'override' | 'keep' | 'ask' | 'abort'	No	'ask'	Conflict handling for comvi push
pull.emptyDir	boolean	No	false	Clear the translations directory before comvi pull

Tip

Store your API key in an environment variable (COMVI_API_KEY) instead of the config file. The CLI reads from the environment automatically, so you can safely commit .comvirc.json without secrets.

Commands

comvi pull

Download translations from the Comvi platform to your local project.

comvi pull

See comvi pull for full options.

comvi push

Upload local translation files to the Comvi platform.

comvi push

See comvi push for full options.

comvi typegen

Generate TypeScript type definitions from your translation keys.

comvi typegen

See comvi typegen for full options.

Environment Variables

The CLI reads these environment variables. They override values in .comvirc.json.

Variable	Description
COMVI_API_KEY	API key for authenticating with the Comvi API. Overrides apiKey in config
COMVI_API_BASE_URL	API base URL. Overrides apiBaseUrl in config

# Use environment variables in CI
COMVI_API_KEY=tlk_abc123 npx comvi pull

Exit Codes

Code	Meaning
0	Success
1	General error (invalid config, missing required options, unexpected failure)
2	Authentication error (invalid or missing API key)
3	Network error (API unreachable, timeout)
4	Validation error (invalid project ID, unsupported locale)

CI/CD Integration

Add Comvi to your build pipeline to keep translations in sync:

.github/workflows/i18n.yml

name: Sync Translations
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx comvi pull
      - run: npx comvi typegen
        env:
          COMVI_API_KEY: ${{ secrets.COMVI_API_KEY }}

See CI/CD Integration for more detailed workflows.

Next Steps

• comvi pull — download translations
• comvi push — upload translations
• comvi typegen — generate TypeScript types
• CI/CD Integration — automate translation sync