Command reference

Every command of the easyi18n CLI with its options, as --help prints them. For the workflows these commands belong to, start with the CLI overview.

Version

This reference comes from the --help output of CLI 0.13.0-rc.6. CLI 0.12.0, the version on pub.dev on October 11, 2026, has no pull --force, no sync --force, no init --stack web, no init --agents and no mcp config; its other commands and options are the same. Run easyi18n <command> --help to see what your installed version accepts.

Command	What it does	API key scope
init	Set up a project: write easyi18n.yaml and wire the stack.	None
doctor	Check the integration.	read for the server checks
extract	Scan the code for tr() strings, offline.	None
push	Register tr() strings and translate them.	translate
sync	Upload a catalog file, translate, publish and write it back.	translate, publish, read
pull	Download published files.	read
status	Compare the last pull with the published version.	read
apply	Rewrite tr() literals that source review corrected.	read
rollback	Restore an earlier published version.	publish
formats add	Enable an output format.	write
languages add	Add a target language.	write
mcp	Run the MCP server for an AI agent.	Depends on the tools the agent calls

Commands that call the server read the API key from --token, or from the EASYI18N_TOKEN environment variable when the option is absent.

Global options

Global options go before the command: easyi18n --json status.

Option	Default	Description
--config <path>	easyi18n.yaml	Path to the config file.
--json		Emit structured JSON output when the command supports it.
--version		Print the CLI version. It cannot be combined with a command.
-h, --help		Print usage. easyi18n help <command> and easyi18n <command> --help print the same text.

--json is supported by every command on this page except a bare easyi18n mcp, which is a server and not a batch command. pull --watch refuses it. An unknown option or a refused value exits with code 64; with --json the error is a JSON record whose code is usage_error. Structured output describes the error record.

init

easyi18n init [arguments]

Sets up the project in the current directory for easyi18n. It needs no API key and does not call the server.

Option	Default	Description
--stack <name>	flutter	Stack adapter: flutter, xcode or web, or auto to detect it.
--workspace <handle>		The workspace handle, the @handle segment of your project URL. Use with --project.
--project <slug>		The project slug. Use with --workspace.
--project-id <id>		The project ID, instead of --workspace and --project.
--base-url <url>	https://api.easyi18n.com	Backend origin.
--format <id>	arb	Output format. The xcode and web stacks pick their own when you leave it out.
--output <dir>	lib/l10n	Directory to write files into.
--catalog <path>	Detected	The catalog file easyi18n sync uploads and writes back, for the xcode and web stacks.
--mode <a|b>	Detected from l10n.yaml	a keeps your gen_l10n setup and writes only the config and .gitignore. b wires the Flutter SDK.
-f, --force		Rewrite an existing easyi18n.yaml from the options.
--[no-]agents	On	Write the easyi18n block into AGENTS.md, for coding agents without MCP. It never touches CLAUDE.md or .cursorrules.
--dry-run		Report what would change without writing anything.

See Configure a project.

doctor

easyi18n doctor [arguments]

Checks the config, the platform wiring, the ICU syntax of your strings and the published translations against your tr() calls. It spends no credits and exits with code 1 when it finds a blocking problem.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the read scope. Reads the published coverage of a Mode A project and the project languages of a web project.
--source-dir <dir>	lib	Directory to scan for tr() calls, relative to the config file.

See Diagnose and maintain an integration.

extract

easyi18n extract [arguments]

Scans the source tree for tr() strings and reports them against easyi18n.lock. It works offline and needs no API key.

Option	Default	Description
--source-dir <dir>	lib	Directory to scan, relative to the config file.
--fail-on-orphans		Exit with code 1 if the lockfile has strings that are no longer in the code.

push

easyi18n push [arguments]

Extracts tr() strings, registers them and starts their translation.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the translate scope. --publish also needs publish. In Mode A, --publish needs read too, and write to adopt a missing output format.
--source-dir <dir>	lib	Directory to scan, relative to the config file.
--lang <code>	All project languages	Restrict to these target languages. Repeat the option for several.
--max-credits <n>		Stop if the estimate exceeds this many credits. Decimals are allowed.
--dry-run		Estimate the cost without registering or translating anything.
-y, --yes		Skip the confirmation prompt, for CI.
--prune		Drop orphaned strings from the lockfile. It never deletes translations.
--publish		After pushing, wait for the AI translation to finish and publish a new version.
--approved-only		With --publish: treat unapproved translations as missing.
--require-complete		With --publish: fail before publishing when extracted strings remain untranslated after the retries, or when the scan finds no strings.

See Push strings from the Flutter runtime SDK.

sync

easyi18n sync [arguments]

Syncs the local translation catalog: uploads it, translates what changed, publishes and writes the result back.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the translate, publish and read scopes.
--dry-run		Classify and price the sync without writing anything.
-y, --yes		Skip the confirmation prompt, for CI.
--max-credits <n>		Stop if the estimated cost exceeds this many credits.
--no-publish		Upload and translate, but do not publish or write the result back.
--require-complete		Fail when any key and language pair could not be translated.
--on-conflict <server|file>	server	What to do when the catalog carries an older text than the project. server keeps the project's text and reports the row. file imports the catalog's text over it, including over a corrected source.
--force		Replace a locale file that changed since the pull that wrote it. Without it, such a file stops the sync before it uploads.

See Sync an Xcode String Catalog and Sync a web project with JSON catalogs.

pull

easyi18n pull [arguments]

Downloads the translated files of a published version and writes them to disk.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the read scope. Adopting a missing output format also needs write.
--version <id>	Latest	Published version to pull, in the form YYYY.MM.DD.N.
--lang <code>	All locales	Pull one locale only, for example es.
--require-complete		Exit with code 1 when any target language of the pulled version is missing translations. It needs mode: a in the config.
--dry-run		List the files that would be written without writing them.
--watch		Keep running and pull again whenever a new version is published. Stop it with Ctrl-C.
--interval <seconds>	30	Seconds between version checks with --watch. The minimum is 5.
--force		Replace a file that changed since the pull that wrote it. Without it, such a file stops the pull before anything is written.

See Pull published files and Check completeness in CI.

status

easyi18n status [arguments]

Shows whether the local translations are up to date with the server. It exits with code 1 when the project has never been published, has never been pulled, or is behind.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the read scope.

apply

easyi18n apply [arguments]

Rewrites the tr() literals that source review corrected. Without --write it only previews the changes.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the read scope.
--source-dir <dir>	lib	Directory to scan and rewrite, relative to the config file.
--write		Apply the rewrites to disk.

rollback

easyi18n rollback [version]

Restores an earlier published version as a new version. Without an argument it restores the one before the current version.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the publish scope.

formats add

easyi18n formats add <id>

Enables an output format on the project without removing the others.

Option	Default	Description
--token <key>	$EASYI18N_TOKEN	API key with the write scope.

See Enable output formats.

languages add

easyi18n languages add <code>

Adds a target language to the project, or brings back one that was removed.

Option	Default	Description
--fill-mode <ai|manual>	A new language gets ai; an existing one keeps its mode	Whether AI translates the language. With manual, AI runs skip it and its translations come from the dashboard or your files.
--token <key>	$EASYI18N_TOKEN	API key with the write scope.

mcp

easyi18n mcp
easyi18n mcp config [arguments]

easyi18n mcp runs the MCP server on standard input and output, for an AI agent to drive. An MCP client starts it; you do not run it by hand. AI agents covers the tools it exposes.

easyi18n mcp config prints the snippet that registers the server in an AI client.

Option	Values	Description
--client <name>	claude-code, claude-desktop, cursor, vscode, codex, gemini, windsurf, zed, generic	The MCP client to print the snippet for.
--runner <name>	npx (default), dart	How the client starts the CLI. npx uses the npm package @easyi18n.com/cli and needs Node, not Dart. dart uses the package installed with dart pub global activate easyi18n_cli.