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

First Run

1. Run comvi init to create a .comvirc.json in your project root.
2. Set COMVI_API_KEY in your environment (or .env file).
3. Run comvi typegen to generate TypeScript types.

npx comvi init
export COMVI_API_KEY=your_api_key_here
npx comvi typegen

Configuration

The comvi init command creates a .comvirc.json in your project root. You can also write it by hand:

.comvirc.json

{
  "apiBaseUrl": "https://api.comvi.io",
  "outputPath": "src/types/i18n.d.ts",
  "strictParams": true,
  "translationsPath": "./src/locales",
  "fileTemplate": "{namespace}/{languageTag}.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
translationsPath	string	No	'./src/locales'	Directory for local translation JSON files
fileTemplate	string	No	'{namespace}/{languageTag}.json'	File layout for pull/push. Default namespace stored at root as {languageTag}.json; other namespaces nested under {namespace}/. Custom templates are matched literally
format	'json'	No	'json'	Translation file format
locales	string[]	No	All project locales	Restrict pull/push to these BCP 47 locale tags. --locale flag overrides entirely
namespaces	string[]	No	All namespaces	Restrict pull/push to these namespaces. --ns flag overrides entirely
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 init

Create a .comvirc.json configuration file. Validates your API key against the platform when COMVI_API_KEY is set.

comvi init

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.

Global Flags

These flags apply to every command:

Flag	Description
--env-file <path>	Load a specific .env file instead of auto-discovery
--no-env-file	Skip auto-loading .env entirely

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
COMVI_NO_ENV	Set to 1 to skip auto-loading .env (same as --no-env-file)

# 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 API key, auth failure, network error, unexpected failure)
4	Validation error (invalid locale/namespace filter, malformed config)

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: 22
      - 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