CLI — Getting Started

multilocale is the command-line client for your translations on app.multilocale.com. It moves files: it downloads a project's dictionaries into your repository, imports the ones you already have, adds and edits phrases, and rolls a project out to new locales.

There is no Multilocale runtime library to install, and no @multilocale/* npm package is involved. Once the translation files are in your repository, your framework's own i18n runtime renders them — next-intl, react-i18next, Lingui, Android string resources, Apple .strings. See Rendering translations.

Start without a browser

One command creates the account, prints the generated password once, and stores the session so every later command is already authenticated:

npx multilocale signup --email you@example.com --json

{
  "email": "you@example.com",
  "password": "…",
  "passwordGenerated": true,
  "appUrl": "https://app.multilocale.com",
  "newOrganization": true,
  "loggedIn": true
}

No browser, no dashboard visit, no human — which makes this the entry point for agents and CI. Signup also creates a first project named after the local part of your email, with defaultLocale: "en", locales: ["en"] and paths: ["translations/%lang%.json"], so the file commands work immediately.

Pass --password to choose your own (it is then never echoed back), and --first-name / --last-name to override the names derived from the email address. Without --email on a TTY the command asks for one; without --email and without a TTY it fails immediately rather than hanging on a prompt.

If the address already has an account the command exits 1 with this email already has an account — the next step is login, not a retry.

Installation

npx multilocale needs no install. For a permanent one:

npm install -g multilocale

Node.js 16 or newer.

Authentication

login is for an account that already exists. It never asks for an email and password — the two ways in are a browser session and an API key secret:

multilocale login              # on a TTY: asks which of the two to use
multilocale login --browser    # browser flow, skipping the question
multilocale login --with-key   # masked prompt for an API key secret
multilocale logout             # clear the stored session and any stored key

--browser starts a temporary localhost server, opens app.multilocale.com, and receives the session tokens on the redirect back. If the browser does not open, the URL is printed to visit by hand. Tokens land in ~/.multilocale/ and are refreshed automatically.

--with-key prompts (masked) for an API key secret — created per project on app.multilocale.com, on the project's API keys page — verifies it with one authenticated GET /api/projects, and stores it. A key the API rejects is dropped rather than stored. New keys default to read-only scopes; widen them on the key's page before running write commands.

The secret is never accepted as a command-line argument: argv lands in shell history and in every ps listing. Prompt or environment variable only.

Without a terminal

Export the key instead of logging in at all:

export MULTILOCALE_API_KEY=<key secret>

Precedence is stored browser session → stored API key secret → MULTILOCALE_API_KEY, so an exported key never silently hijacks an interactive session. logout clears the stored credentials but cannot unset a variable in your shell: with the key exported, the CLI stays authenticated through it, and says so.

On a TTY, a command that needs credentials and finds none starts the browser login itself. With no TTY — agents, CI, pipes — it does not open a browser: it exits 1 immediately and prints both ways in on stderr.

Project selection

Most commands need a project. It is resolved in this order:

1. --project <idOrName> on the command
2. "projectId" in a multilocale.json found under the working directory
3. the only project on the account, if there is exactly one
4. an interactive picker, which then writes multilocale.json for next time

Step 4 needs a TTY. Headless with more than one project, the command fails with exit 1 and lists the project names instead of waiting forever on a prompt no one will answer — so commit a multilocale.json, or always pass --project, in CI and in agent runs.

Quick start

# 1. Account (or `npx multilocale login` if you have one)
npx multilocale signup --email you@example.com --json

# 2. A project with the locales you want
npx multilocale projects create my-app --locales en,es,fr --default-locale en

# 3. Where its translation files live in this repository
npx multilocale projects update my-app --paths "translations/%lang%.json"

# 4. Push the source strings you already have (once — see `import`)
npx multilocale import --project my-app

# 5. Machine-translate everything into every project locale
npx multilocale localize all --project my-app

# 6. Write the dictionaries back into the repository
npx multilocale download --project my-app

Then commit the files under translations/ and let your i18n runtime read them.

Machine-readable output

Every data command accepts --json: parseable JSON on stdout, no colour, progress moved to stderr. Errors are a single-line JSON object on stderr with exit code 1. multilocale schema prints the entire command tree as JSON, and multilocale schema <command> one command's arguments and flags — that is the authoritative reference for the installed version.

Global Options

Flag	Description
-V, --version	Print the CLI version
-e, --env <environment>	Environment to use (default: production)
-h, --help	Display help