comvi pull

Download every locale and namespace of the project to the configured translationsPath as flat JSON files.

Usage

Terminal

comvi pull [options]

Options

Option	Default	Meaning
-c, --config <path>	nearest .comvirc.json	Config file to read
-l, --locale <locales>	locales in config, else all	Comma-separated BCP-47 codes to download (en,pt-BR). A code the project does not have exits 4
-n, --ns <namespaces>	namespaces in config, else all	Comma-separated namespaces to download. A namespace the project does not have exits 4
-p, --path <path>	translationsPath in config	Output directory
--empty-dir	pull.emptyDir in config, else off	Remove the pulled locales and namespaces after the fetch succeeds, then write
--dry-run	off	List the files a pull would write, and with --empty-dir the files it would remove, without touching the filesystem

A flag replaces the config value for that run; the two lists never merge.

Output layout

src/locales/

src/locales/
├── en.json            # default namespace
├── de.json
├── common/
│   ├── en.json
│   └── de.json
└── auth/
    ├── en.json
    └── de.json

src/locales/common/en.json

{
  "greeting": "Hello, {name}!",
  "nav.home": "Home",
  "nav.settings": "Settings"
}

With the default fileTemplate of {namespace}/{languageTag}.json, the namespace marked default in the project is written at the root as {languageTag}.json and every other namespace gets a directory. A custom template such as {languageTag}/{namespace}.json is matched literally and turns that root special case off. Files are always flat: a key named nav.home is one property, never a nested nav object.

Examples

Pull two locales of one namespace

comvi pull --locale en,de --ns common

.github/workflows/build.yml

- run: npx comvi pull
  env:
    COMVI_API_KEY: ${{ secrets.COMVI_API_KEY }}
- run: npx comvi typegen
- run: npm run build

package.json

{
  "scripts": {
    "predev": "comvi pull && comvi typegen"
  }
}

Pulling in CI keeps translation files out of the repository and puts the latest published values in every build. In a monorepo, run the command from the package that owns the .comvirc.json, or pass --config ../../.comvirc.json.

Clear stale files

Terminal

comvi pull --empty-dir --dry-run
comvi pull --empty-dir

--empty-dir removes files that were deleted on the platform. The clear runs after the fetch and only once every requested locale and namespace came back, so a network failure, a rejected key or a typo in a filter leaves the working copy as it was. The clear follows the filters: --ns common --empty-dir removes the common files and nothing else, and a locales or namespaces list in the config scopes it the same way. Emptied directories are removed with their files. A translationsPath at or above the working directory is refused before anything is deleted.

Caution

With no locale and no namespace filter, from flags or from the config, --empty-dir removes everything under translationsPath, including files that are not translation files.

Exit codes

Code	Meaning
0	Files written, or a dry run finished
1	Missing .comvirc.json, auth failure, network error
4	Invalid config, a locale or namespace the project does not have, or a --dotenv file that does not exist

Next steps

• comvi push: upload local files back to the project.
• comvi typegen: generate types after a pull.
• Load translations on demand: how the SDK loads the files a pull wrote.
• CI/CD integration: full pipeline examples.