Skip to content
langctl

This page is available in English only.

Get started

CLI reference

CLI Installation

The langctl CLI keeps the translation files in your repository in sync with langctl — locally and in CI/CD.

Requirements

  • Node.js 20 or newer (node --version)
  • macOS, Linux or Windows

Install

terminal 
npm install -g langctl
langctl --version

Other package managers work too:

terminal 
pnpm add -g langctl
yarn global add langctl

Or run it without installing — handy in CI:

terminal 
npx langctl@latest --help

Tip

In CI, pin the major version (npx langctl@0 …) so a future breaking release can’t change your pipeline unexpectedly.

Verify

terminal 
$ langctl --version
0.3.0

$ langctl --help
Usage: langctl [options] [command]

Commands:
init        set up this repository: authenticate if needed and write langctl.json
auth        store an API key (prefer --stdin so the key stays out of shell history)
whoami      show the organization, key and scopes in use, and check connectivity
pull        download translations into files
push        upload translation files (by default only the source language)
export      export translations to a file (one-off)
import      import one translation file
projects    manage projects
keys        manage translation keys
team        manage team members
org         organization info
...

Set up a repository

Run init in the root of your app. It asks for an API key if you don’t have one stored (input is hidden), lets you pick the project, file format and location, and writes a langctl.json you can commit:

terminal 
langctl init

Create the API key first at app.langctl.com → API Keys — it is shown only once. Then:

terminal 
langctl pull     # download translations into your files
langctl push     # upload new strings from your source-language file

Everything can also be passed as flags, so init works non-interactively too:

terminal 
langctl init --project web-app --format json --output "src/locales/{lang}.json"

Upgrading from 0.2

0.3 is a rewrite focused on reliability. Things to know when upgrading:

  • Node.js 20+ is required.
  • pull/export use each platform’s default layout (locales/{lang}.json, res/values-xx/strings.xml, xx.lproj/Localizable.strings, lib/l10n/app_xx.arb). Pass -o or set output in langctl.json to keep your old paths.
  • Exporting several languages to a single file is now an error instead of silently overwriting it.
  • Destructive commands ask for confirmation and need --yes when not run interactively.
  • keys translate takes the text with -t/--text; keys create accepts --value LANG=TEXT for any language.
  • team commands need an API key with the org:admin scope.

See the full changelog.

Next steps