Command Line Interface (CLI)

The Messagevisor CLI is the main authoring and operations surface for a project. It covers project setup, validation, examples, evaluation, building, testing, catalog workflows, CSV exchange, and sets-based promotion flows.

This page is the command reference for the CLI. Use it as the practical map, then follow the related links for deeper model-specific details.

Before you start#

The CLI expects to run inside a Messagevisor project directory or a child directory of one.

Typical invocation:

Command

$ npx messagevisor <command> [options]

If your project uses sets, some commands require --set=<name> so Messagevisor knows which definition tree to operate on.

Output modes#

Many commands support one or more of these output styles:

plain text: optimized for humans in a terminal
--json: machine-readable output
--pretty: pretty-print JSON output
--verbose: more detail for debugging

When a command supports JSON output, prefer it for scripts and CI checks.

Typical authoring loop#

Command

$ npx messagevisor lint
$ npx messagevisor test
$ npx messagevisor build

Add these as needed:

examples when you want to inspect authored examples
evaluate when you want to debug a single message, raw string, or segment
catalog when you want a browsable project view

`init`#

Create a new project starter.

Use this when:

bootstrapping a new repo
creating a scratch project to try a workflow
comparing YAML and JSON project layouts

Examples:

Command

$ npx messagevisor init
$ npx messagevisor init --project=json
$ npx messagevisor init --project=environments

Notes:

run init from an empty project directory for the cleanest setup
if the current directory is not empty, init prompts for a new child directory name and initializes the starter there
pass --overwrite to initialize in the current directory anyway; existing conflicting files are skipped, not replaced
--project selects a starter shape
the generated project is only a starting point; you will usually tailor directories, config, and modules right away

Read next:

`config`#

Print the resolved project configuration.

Use this when:

confirming which parser is active
checking resolved directory paths
verifying sets/modules/export options

Examples:

Command

$ npx messagevisor config
$ npx messagevisor config --json --pretty

Notes:

this shows resolved configuration, not just the literal contents of messagevisor.config.js
it is often the fastest way to confirm whether a path override or module registration is being picked up

Read next:

Configuration

`info`#

Show a quick entity-count summary for the current project.

Use this when:

sanity-checking a project after import or promotion
getting a quick overview before a review or debugging session

Example:

Command

$ npx messagevisor info

Read next:

`lint`#

Validate project definitions.

Use this when:

checking schema correctness
catching missing references and invalid format shapes
validating tests before running them

Examples:

Command

$ npx messagevisor lint
$ npx messagevisor lint --json --pretty
$ npx messagevisor lint --set=staging

Behavior notes:

lint validates authoring definitions, not runtime output
for sets-based projects, lint can cover all sets or a single set depending on how you invoke it
if you are changing locale format presets, target filters, or test assertion shapes, lint is usually the first command that tells you whether the structure is valid

Read next:

`list`#

List one class of entity at a time.

Supported entity switches:

--messages
--locales
--segments
--attributes
--targets

Examples:

Command

$ npx messagevisor list --messages
$ npx messagevisor list --messages --target=web
$ npx messagevisor list --locales
$ npx messagevisor list --targets

Common filters:

--keyPattern=<regex>
--description=<regex>
--withTests
--withoutTests
--archived=true|false
--promotable=true|false

Target-aware behavior:

list --messages --target=<target> filters messages by the target's includeMessages and excludeMessages
when multiple targets are provided, the result is the union of messages included by those targets

Edge cases:

pass exactly one of --messages, --locales, --segments, --attributes, or --targets
--withTests and --withoutTests are not supported for attributes

Read next:

`find-duplicates`#

Find active message keys that resolve to the same translation value.

Use this when:

reviewing copy reuse before cleanup
finding accidental duplicate labels across namespaces
auditing inherited regional translations

Examples:

Command

$ npx messagevisor find-duplicates
$ npx messagevisor find-duplicates --locale=en-US
$ npx messagevisor find-duplicates --set=staging
$ npx messagevisor find-duplicates --locale=en-US --json --pretty

Behavior notes:

duplicate groups are scoped by locale
locale translation inheritance is applied before comparing values
overrides are ignored
archived messages and empty translation values are ignored
in sets-based projects, the command scans all sets independently unless --set=<set> is passed

Read next:

`create`#

Scaffold entities from the CLI.

Use this when:

creating many messages quickly
generating empty locale or segment files to fill in later
reducing repetitive path creation during authoring

Typical example:

Command

$ npx messagevisor create --messages --keys=$'auth.signin\nauth.signout'

Notes:

this is a convenience authoring command, not a migration framework
it is most useful for generating the initial file structure, then editing the authored content yourself

Read next:

`examples`#

Resolve and print authored examples from locales and messages.

Use this when:

previewing example output without building an app
checking matrix-expanded examples
verifying that locale inheritance, target formats, and module behavior are producing the intended results

Examples:

Command

$ npx messagevisor examples
$ npx messagevisor examples --locale=en-US
$ npx messagevisor examples --exampleIndex=2 --matrixIndex=3
$ npx messagevisor examples --descriptionPattern=welcome --translationPattern=adult
$ npx messagevisor examples --onlyMessages
$ npx messagevisor examples --onlyLocales
$ npx messagevisor examples --json --pretty

Important behaviors:

examples covers both locale examples and message examples
--onlyMessages and --onlyLocales narrow the output to one class
--locale=<locale> filters to one locale
--exampleIndex and --matrixIndex are 1-based filters for already-authored example numbering
values that look like ISO date strings are coerced into Date objects before evaluation so authored examples can drive date/time formatting cleanly
the same message and locale examples are also available in the generated Catalog, which is better for browsing and stakeholder review

Read next:

`evaluate`#

Evaluate one thing directly from the CLI. This is the fastest debugging command in the toolchain.

There are three modes:

--message=<key>: resolve an existing message key through a built target+locale datafile
--rawMessage=<string>: evaluate an inline message string through the runtime modules for a locale
--segment=<key>: evaluate a segment against context

Examples:

Command

$ npx messagevisor evaluate --message=auth.signin --locale=en-US
$ npx messagevisor evaluate --message=dashboard.welcome --locale=en-US --values='{"name":"Ada"}'
$ npx messagevisor evaluate --rawMessage="Hello {name}" --locale=en-US --values='{"name":"Ada"}'
$ npx messagevisor evaluate --segment=platform-web --context='{"platform":"web"}'

How the modes differ:

--message uses the real built datafile path for the selected target and locale
--rawMessage skips message lookup and formats the literal string through registered modules
--segment does not need --locale; it only needs segment definitions plus context

Common options:

--target=<target>
--locale=<locale>
--values=<json>
--context=<json>
--set=<set>
--json
--pretty

Edge cases:

pass either --message or --rawMessage, not both
--message and --rawMessage require --locale
--segment works without --locale
malformed JSON in --values or --context fails early

Read next:

`benchmark`#

Benchmark translation evaluation against a built target+locale datafile.

Use this when:

comparing target sizes or override complexity
measuring hot-path translation performance
checking the effect of modules or context-heavy messages

Typical usage:

Command

$ npx messagevisor benchmark --message=auth.signin --target=web --locale=en-US -n=1000

Behavior notes:

benchmark numbers are only meaningful when you keep target, locale, values, and modules stable between runs
if you care about app startup cost too, combine this with build output inspection and catalog inspection

Read next:

`build`#

Generate runtime JSON datafiles.

Use this when:

publishing translations for applications
inspecting the exact target-filtered output the SDK will consume
validating target-level format overrides and included-message sets

Examples:

Command

$ npx messagevisor build
$ npx messagevisor build --target=web --locale=en-US
$ npx messagevisor build --set=production
$ npx messagevisor build --showSize

What build does:

resolves locale format inheritance
applies target-level locale format overrides
filters messages by target inclusion/exclusion rules
includes only the attributes and segments needed by included overrides
writes one datafile per target and locale combination

Key options:

--target=<target>
--locale=<locale>
--set=<set>
--showSize
--json
--pretty
--noStateFiles

Edge cases:

in sets mode, some invocations require --set
building a single target/locale pair is often the easiest way to debug a target-specific issue
target context influences which overrides survive the build
target files control datafile serialization with pretty, stringify, and revisionFromHash

Read next:

`test`#

Run Messagevisor project tests.

Supported test subjects:

messages
segments
locales
targets

Examples:

Command

$ npx messagevisor test
$ npx messagevisor test --keyPattern=welcome
$ npx messagevisor test --assertionPattern=evaluation
$ npx messagevisor test --onlyFailures
$ npx messagevisor test --showDatafile
$ npx messagevisor test --verbose
$ npx messagevisor test --json --pretty

What tests can do:

message assertions evaluate resolved translations
segment assertions verify segment matching against context
locale assertions can verify resolved formats and evaluate rawMessage
target assertions can verify included/excluded messages, resolved formats, and evaluate either rawMessage or message

Helpful filters:

--keyPattern=<regex> narrows the test file set
--assertionPattern=<regex> narrows individual assertions by description
--onlyFailures keeps output short when you already know the suite is noisy
--showDatafile is especially useful for target assertions

Behavior notes:

matrix-expanded assertions are filtered after description expansion
key-like fields stay literal in matrix expansion unless the assertion type explicitly supports placeholders there
target assertion evaluation uses the actual built target datafile, so missing translations follow normal SDK behavior instead of producing a custom test-only error

Read next:

`export`#

Export translations to CSV.

Use this when:

preparing files for translators
reviewing translation status outside the repo
exchanging direct and inherited translations in a spreadsheet workflow

Examples:

Command

$ npx messagevisor export
$ npx messagevisor export --locale=en-US --target=web
$ npx messagevisor export --locale=en --locale=nl-NL --target=web
$ npx messagevisor export --print

Useful options:

--locale=<locale>; omit it for all locales, or repeat it for multiple locale columns
--target=<target>
--includeMessages=<pattern>
--excludeMessages=<pattern>
--excludeOverrides
--withoutDescription
--withoutStatus
--onlyUntranslated
--onlyDirectlyUntranslated
--print
--output=<path>
--force
--delimiter=<char>
--bom
--lineEnding=lf|crlf

Behavior notes:

export status distinguishes direct, inherited, and missing translations
repeated --locale is useful for source/reference plus target handoff files
target filters apply before rows are emitted
--print writes the CSV to stdout instead of creating a file

Read next:

`import`#

Import translations from CSV, or from a flat JSON object with --from-json.

Use this when:

round-tripping a Messagevisor export through external translation work
applying translated cells back into message and override translation maps
previewing CSV changes before writing files
pulling already available JSON translations into one locale

Examples:

Command

$ npx messagevisor import exports/messagevisor-export-20260419T123456.csv
$ npx messagevisor import --input=translator/nl.csv --apply
$ npx messagevisor import --input=translator/nl.csv --locale=nl-NL --apply
$ npx messagevisor import --input=translator/en-US.csv --locale=en-US --prune --apply
$ npx messagevisor import vendor/new-copy.csv --create-missing
$ npx messagevisor import translations.csv --set=staging
$ npx messagevisor import translations.json --from-json --locale=nl-NL
$ npx messagevisor import https://example.com/nl-NL.json --from-json --locale=nl-NL --apply
$ npx messagevisor import payload.json --from-json --json-path=data.translations --locale=nl-NL

Useful options:

--input=<path>
--set=<set>
--locale=<locale>
--create-missing
--apply
--prune
--from-json
--json-path=<path>
--delimiter=<char>
--bom

Behavior notes:

import expects the export-style CSV shape
without --locale, import reads all known locale columns in the CSV
repeat --locale to import only selected locale columns
--from-json expects one flat object of messageKey: translation pairs and exactly one --locale
--json-path selects a nested object using dot-path syntax, such as data.translations
import previews changes by default and does not write files
--apply writes imported translations to message files
--prune skips or removes direct translations when the imported value matches inherited copy
--create-missing allows import to create unknown messages and unknown overrides; without it, unknown rows are skipped with warnings
when creating an override row, the base message must already exist or be created by another row in the same import
--createMissing is also accepted as a camelCase alias
override rows are mapped using the configured exportOverrideKeySeparator
in sets projects, JSON import requires exactly one --set=<set>

Read next:

`generate-code`#

Generate typed runtime helpers from your project.

Use this when:

you want generated message key types or helpers
you want a React-oriented codegen shape for app integration

Examples:

Command

$ npx messagevisor generate-code --language typescript --out-dir src/generated
$ npx messagevisor generate-code --language typescript --out-dir src/generated --react

Behavior notes:

generated output depends on your current project definitions
code generation complements the SDK; it does not replace datafile building

Read next:

`prune`#

Remove stale authoring data.

Use this when:

cleaning unused translations
removing dead format presets
narrowing a project after target or locale changes

Examples:

Command

$ npx messagevisor prune --translations
$ npx messagevisor prune --translations --target=web --apply
$ npx messagevisor prune --formats --locale=en-US

Behavior notes:

prune commands are intentionally selective; preview first, then apply
target-aware pruning lets you ask "what is unused for this target?" rather than only "what is unused globally?"

Read next:

`promote`#

Copy authoring changes from one set to another.

Use this when:

moving definitions through dev -> staging -> production
reviewing whether one set can be promoted cleanly
producing an audit trail for sets-based change movement

Examples:

Command

$ npx messagevisor promote --from=dev --to=staging
$ npx messagevisor promote --from=dev --to=staging --target=web
$ npx messagevisor promote --from=dev --to=staging --excludeOverrides
$ npx messagevisor promote --from=dev --to=staging --conflicts=fail
$ npx messagevisor promote --from=dev --to=staging --showUnchanged
$ npx messagevisor promote --from=dev --to=staging --apply
$ npx messagevisor promote --from=dev --to=staging --apply --audit=markdown

Useful options:

--from=<set>
--to=<set>
--target=<target>
--locale=<locale>
--includeMessages=<pattern>
--excludeMessages=<pattern>
--excludeOverrides
--conflicts=source|destination|fail
--allowEmpty
--apply
--audit=json|markdown
--showUnchanged

Behavior notes:

promote previews changes by default and does not write files
--apply writes the promotion to the destination set
--audit writes an audit file only when used with --apply
conflict handling is explicit because promotions can merge arrays and object structures, not just copy whole files
projects can restrict allowed flows via promotionFlows

Read next:

`catalog`#

Work with the generated project catalog.

Main entry points:

catalog: combined export + serve + watch flow
catalog export: generate static catalog files
catalog serve: serve the generated catalog locally

Examples:

Command

$ npx messagevisor catalog
$ npx messagevisor catalog --with-translation-search
$ npx messagevisor catalog --with-duplicates
$ npx messagevisor catalog export
$ npx messagevisor catalog export --with-translation-search
$ npx messagevisor catalog export --with-duplicates
$ npx messagevisor catalog serve
$ npx messagevisor catalog export --hashRouter
$ npx messagevisor catalog serve --hashRouter

Routing behavior:

browser router is the default
that means generated URLs are clean and do not include #
use --hashRouter only when your host cannot fall back to index.html for deep routes

Translation search:

by default, catalog generation skips the translation-value search index for faster exports on large projects
use --with-translation-search with catalog or catalog export to enable translation:"keyword" searches in the message list
catalog serve only serves generated files; it does not build or change the translation search index

Duplicate reports:

by default, catalog generation skips locale duplicate translation reports for faster exports on large projects
use --with-duplicates with catalog or catalog export to generate duplicate data and show locale Duplicates tabs
catalog serve only serves generated files; it does not build or change duplicate reports

Read next:

Troubleshooting patterns#

A translation looks wrong#

Run evaluate --message=... --target=... --locale=...
If the result depends on conditions, add --context=...
If the message uses formatting or ICU syntax, confirm your project modules in config
If the message is target-specific, build that target+locale pair and inspect the datafile or catalog

A segment does not match the way you expect#

Run evaluate --segment=... --context=...
Check the attribute schema and condition operators
If the segment is only used in overrides, build or test the affected message/target path too

A target seems to be missing a message#

Run list --messages --target=<target>
Run test --keyPattern=<target-or-message>
Build the target+locale pair and inspect the resulting datafile
If you are using sets, make sure you are looking at the right --set

An example or locale test is formatting differently than expected#

Confirm locale format inheritance in Locales
Check target-level format overrides in Targets
Confirm runtime modules in Modules
Re-run with examples, evaluate, or test --showDatafile depending on whether you are debugging authoring examples, raw runtime behavior, or built output

Workflow recipes#

Validate a project before publishing datafiles#

Command

$ npx messagevisor lint
$ npx messagevisor test
$ npx messagevisor build --showSize

Debug a raw ICU string for one locale#

Command

$ npx messagevisor evaluate --rawMessage="{count, plural, one {# item} other {# items}}" --locale=en-US --values='{"count":2}'

Inspect only locale examples#

Command

$ npx messagevisor examples --onlyLocales --locale=en-US --json --pretty

Review a target-specific issue#

Command

$ npx messagevisor list --messages --target=web
$ npx messagevisor test --keyPattern=web --showDatafile
$ npx messagevisor build --target=web --locale=en-US

Generate and browse the catalog locally#

Command

$ npx messagevisor catalog

Before you start#

Output modes#

Typical authoring loop#

init#

config#

info#

lint#

list#

find-duplicates#

create#

examples#

evaluate#

benchmark#

build#

test#

export#

import#

generate-code#

prune#

promote#

catalog#

Troubleshooting patterns#

A translation looks wrong#

A segment does not match the way you expect#

A target seems to be missing a message#

An example or locale test is formatting differently than expected#

Workflow recipes#

Validate a project before publishing datafiles#

Debug a raw ICU string for one locale#

Inspect only locale examples#

Review a target-specific issue#

Generate and browse the catalog locally#

Related#

`init`#

`config`#

`info`#

`lint`#

`list`#

`find-duplicates`#

`create`#

`examples`#

`evaluate`#

`benchmark`#

`build`#

`test`#

`export`#

`import`#

`generate-code`#

`prune`#

`promote`#

`catalog`#